diff --git a/docs/content/6.errors/DF8007.md b/docs/content/6.errors/DF8007.md
new file mode 100644
index 00000000..02dcae81
--- /dev/null
+++ b/docs/content/6.errors/DF8007.md
@@ -0,0 +1,38 @@
+---
+title: 'DF8007: Hub Base Is Outside the Deploy Base'
+description: 'buildHub''s base ("{base}") is not under its deployBase ("{deployBase}"), so the hub itself would be served outside the deploy root.'
+---
+
+## Message
+
+> buildHub's base ("`{base}`") is not under its deployBase ("`{deployBase}`"), so the hub itself would be served outside the deploy root.
+
+## Cause
+
+`deployBase` is the URL prefix the whole output tree is served under, and the hub sits inside that tree. A hub `base` outside it describes a second deployment, so the baked URLs and the file layout would disagree.
+
+## Example
+
+```ts
+// ✓ Good: the hub base includes the deploy prefix
+await buildHub({
+ outDir: 'dist/__devtools',
+ base: '/ci-build-123456/__devtools/',
+ deployBase: '/ci-build-123456/',
+})
+
+// ✗ Bad: the hub would be served at the domain root
+await buildHub({
+ outDir: 'dist/__devtools',
+ base: '/__devtools/',
+ deployBase: '/ci-build-123456/',
+})
+```
+
+## Fix
+
+Include the deploy prefix in `base`, or omit `deployBase` when the output is served at the domain root.
+
+## Source
+
+- [`packages/hub/src/node/build.ts`](https://github.com/devframes/devframe/blob/main/packages/hub/src/node/build.ts): `buildHub()` rejects a `base` that does not start with `deployBase`.
diff --git a/docs/content/8.references/6.hub-api.md b/docs/content/8.references/6.hub-api.md
index a79606e3..b16d02c4 100644
--- a/docs/content/8.references/6.hub-api.md
+++ b/docs/content/8.references/6.hub-api.md
@@ -124,6 +124,7 @@ The options of `buildHub()` from `@devframes/hub/build`: [Static builds](/guide/
|---|---|
| `outDir` | Output directory for the hub subtree; corresponds to `base` at serve time (build `base: '/__devframes/'` into `dist/__devframes`). A mount served outside the hub base (a devframe SPA or asset dir kept as a sibling of it) is written to this directory's parent (the deploy root) by its absolute path. |
| `base` | Mount base baked into every absolute URL the build emits. Default `/__devframes/`. |
+| `deployBase` | URL prefix the deploy root is served under. Root-absolute URLs the build emits are rebased under it. Must be a prefix of `base`. Default `/`. |
| `context` | An already-mounted `DevframeHubContext` to bake instead of `devframes` (the build counterpart of `initHub({ context })`); reads `ctx.frames` and `ctx.views.buildStaticDirs`. Mutually exclusive with `devframes`. |
| `clean` | Remove `outDir` before writing. Default `true`; set `false` to bake beside an app's own build output. |
| `pretty` | Pretty-print RPC dump JSON shards. Default `false` (minified). |
diff --git a/packages/hub/src/node/__tests__/build.test.ts b/packages/hub/src/node/__tests__/build.test.ts
index 378a79cc..1cf0589c 100644
--- a/packages/hub/src/node/__tests__/build.test.ts
+++ b/packages/hub/src/node/__tests__/build.test.ts
@@ -228,4 +228,73 @@ describe('buildHub', () => {
const index = JSON.parse(readFileSync(join(outDir, '__index.json'), 'utf-8'))
expect(index.frames.map((frame: { id: string }) => frame.id)).toEqual(['gamma'])
})
+
+ it('rejects a hub base outside `deployBase`', async () => {
+ await expect(buildHub({
+ outDir: join(mkdtempSync(join(tmpdir(), 'hub-build-out-')), 'hub'),
+ base: '/__hub/',
+ deployBase: '/sub/',
+ cwd: mkdtempSync(join(tmpdir(), 'hub-build-cwd-')),
+ })).rejects.toThrow(/not under its deployBase/)
+ })
+
+ it('rebases the deploy-root layout under `deployBase`', async () => {
+ const deployRoot = mkdtempSync(join(tmpdir(), 'hub-build-out-'))
+ const outDir = join(deployRoot, '__devtools')
+ const panel = makeDist('')
+ writeFileSync(join(panel, 'app.js'), 'export const base = "/__panel/"\n', 'utf-8')
+
+ await buildHub({
+ outDir,
+ base: '/ci-build-123456/__devtools/',
+ deployBase: '/ci-build-123456/',
+ cwd: mkdtempSync(join(tmpdir(), 'hub-build-cwd-')),
+ async configure(ctx) {
+ await ctx.install(makeFrame('alpha', {
+ distDir: makeDist(''),
+ }), { base: '/__alpha/' })
+ ctx.views.hostStatic('/__panel/', panel)
+ ctx.docks.register({
+ id: 'panel',
+ title: 'Panel',
+ icon: '/__panel/icon.svg',
+ type: 'iframe',
+ url: '/__panel/',
+ })
+ },
+ })
+
+ // The deploy root layout is unchanged on disk: siblings sit beside the hub.
+ expect(existsSync(join(outDir, '__connection.json'))).toBe(true)
+ expect(existsSync(join(deployRoot, '__alpha/index.html'))).toBe(true)
+ expect(existsSync(join(deployRoot, '__panel/app.js'))).toBe(true)
+
+ // Discovery and per-frame meta spell the served URLs.
+ const index = JSON.parse(readFileSync(join(outDir, '__index.json'), 'utf-8'))
+ expect(index.base).toBe('/ci-build-123456/__devtools/')
+ expect(index.frames).toEqual([
+ { id: 'alpha', base: '/ci-build-123456/__alpha/', title: 'Frame alpha' },
+ ])
+ const frameMeta = JSON.parse(readFileSync(join(deployRoot, '__alpha/__connection.json'), 'utf-8'))
+ expect(frameMeta.baseUrl).toBe('/ci-build-123456/__devtools/__connection.json')
+
+ // The baked RPC dump carries the served dock URL, not the root-absolute one.
+ const manifest = JSON.parse(readFileSync(join(outDir, '__rpc-dump/index.json'), 'utf-8'))
+ const stateEntry = manifest['devframe:rpc:server-state:get']
+ const records = (Object.values(stateEntry.records) as string[])
+ .map(path => readFileSync(join(outDir, path), 'utf-8'))
+ const docksRecord = records.find(text => text.includes(HUB_EVENTS.sharedState.docks))!
+ expect(docksRecord).toContain('/ci-build-123456/__alpha/')
+ expect(docksRecord).toContain('/ci-build-123456/__panel/')
+ expect(docksRecord).not.toContain('"/__alpha/"')
+ expect(docksRecord).not.toContain('"/__panel/"')
+
+ // Root-absolute asset references inside copied SPAs follow the new location.
+ expect(readFileSync(join(deployRoot, '__alpha/index.html'), 'utf-8'))
+ .toContain('/ci-build-123456/__alpha/app.js')
+ expect(readFileSync(join(deployRoot, '__panel/index.html'), 'utf-8'))
+ .toContain('/ci-build-123456/__panel/app.js')
+ expect(readFileSync(join(deployRoot, '__panel/app.js'), 'utf-8'))
+ .toContain('/ci-build-123456/__panel/')
+ })
})
diff --git a/packages/hub/src/node/build.ts b/packages/hub/src/node/build.ts
index 1a580b65..dd182bb2 100644
--- a/packages/hub/src/node/build.ts
+++ b/packages/hub/src/node/build.ts
@@ -12,7 +12,7 @@ import { collectStaticRpcDump, writeStaticRpcDump } from 'devframe/rpc/dump'
import { colors as c } from 'devframe/utils/colors'
import { resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
import { joinURL } from 'devframe/utils/url'
-import { dirname, resolve } from 'pathe'
+import { dirname, extname, resolve } from 'pathe'
import { DEVFRAMES_HUB_BASE, DOCK_RENDERERS_STATE_KEY, normalizeHubBase } from '../constants'
import { mountDevframes, renderClientImportsModule, resolveDevframesInput, resolveRendererRegistrations } from './assemble'
import { createHubContext } from './context'
@@ -35,6 +35,13 @@ export interface BuildHubOptions {
* pointers). Default: `/__devframes/`.
*/
base?: string
+ /**
+ * URL prefix the deploy root is served under (e.g. `/ci-build-123456/`).
+ * Root-absolute URLs the build emits are rebased under it, so the output
+ * works below the domain root. Must be a prefix of
+ * {@link BuildHubOptions.base}. Default: `/`.
+ */
+ deployBase?: string
/** Devframes to bake as docks, same input as `initHub({ devframes })`. */
devframes?: DevframesInput
/**
@@ -113,6 +120,9 @@ export async function buildHub(options: BuildHubOptions): Promise {
throw diagnostics.DF8002()
const base = normalizeHubBase(options.base ?? DEVFRAMES_HUB_BASE)
+ const deployBase = normalizeHubBase(options.deployBase ?? '/')
+ if (deployBase !== '/' && !base.startsWith(deployBase))
+ throw diagnostics.DF8007({ base, deployBase })
const cwd = options.cwd ?? process.cwd()
const outDir = resolve(cwd, options.outDir)
const rendererRegistrations = resolveRendererRegistrations(options.renderers ?? [])
@@ -132,26 +142,55 @@ export async function buildHub(options: BuildHubOptions): Promise {
* corresponds to the hub base). A base outside it is a deploy-root sibling:
* `outDir`'s parent is the deploy root, and the base resolves under it by its
* absolute path. This is the layout Vite DevTools serves, where devframe SPAs
- * and assets sit beside `/__devtools/` rather than under it.
+ * and assets sit beside `/__devtools/` rather than under it. The deploy
+ * prefix, when set, is stripped first: it moves the URLs, not the files.
*/
const deployRoot = dirname(outDir)
+ const hubBase = stripDeployBase(base, deployBase)
const resolveOutPath = (urlBase: string): string => {
- if (urlBase.startsWith(base))
- return resolve(outDir, urlBase.slice(base.length))
- if (!urlBase.startsWith('/'))
+ const localBase = stripDeployBase(urlBase, deployBase)
+ if (localBase.startsWith(hubBase))
+ return resolve(outDir, localBase.slice(hubBase.length))
+ if (!localBase.startsWith('/'))
throw diagnostics.DF8006({ urlBase, base })
- return resolve(deployRoot, urlBase.slice(1))
+ return resolve(deployRoot, localBase.slice(1))
}
- await copyBuildStatics(ctx, resolveOutPath)
+ // Everything served outside the deploy prefix needs it added to the baked
+ // URLs. Longest first, so a nested mount is rewritten before its parent.
+ const servedBases = new Set([
+ ...ctx.frames.map(frame => frame.base),
+ ...ctx.views.buildStaticDirs.map(dir => dir.baseUrl),
+ ])
+ const rewrites = deployBase === '/'
+ ? []
+ : [...servedBases]
+ .filter(url => url.startsWith('/') && !isUnderDeployBase(url, deployBase))
+ .sort((a, b) => b.length - a.length)
+ .map(url => [
+ url,
+ serveUrl(url, deployBase),
+ ] as const)
+ const rebaseText = createTextRebaser(rewrites, deployBase)
+ const rebaseValue = rewrites.length
+ ? createUrlValueRebaser(rewrites)
+ : (value: T): T => value
+
+ await copyBuildStatics(ctx, resolveOutPath, rewrites.length ? rebaseText : undefined)
await publishRendererManifest(ctx, rendererRegistrations, base, outDir)
await writeUiArtifacts(options.ui, outDir)
- await fs.writeFile(resolve(outDir, DEVFRAME_DOCK_IMPORTS_FILENAME), renderClientImportsModule(ctx), 'utf-8')
- await writeHubIndex(ctx, base, outDir, options)
- await writeConnectionMetas(ctx, base, outDir, resolveOutPath)
+ await fs.writeFile(
+ resolve(outDir, DEVFRAME_DOCK_IMPORTS_FILENAME),
+ rebaseText(renderClientImportsModule(ctx)),
+ 'utf-8',
+ )
+ await writeHubIndex(ctx, base, outDir, options, deployBase)
+ await writeConnectionMetas(ctx, base, outDir, resolveOutPath, rebaseValue)
console.log(c.cyan`[devframes-hub] writing RPC dump to ${resolve(outDir, '__rpc-dump')}`)
const dump = await collectStaticRpcDump(ctx.rpc.definitions.values(), ctx)
+ for (const file of Object.values(dump.files))
+ file.data = rebaseValue(file.data)
await writeStaticRpcDump(dump, outDir, { pretty: options.pretty })
const count = ctx.frames.length
@@ -160,6 +199,110 @@ export async function buildHub(options: BuildHubOptions): Promise {
: 's'} -> ${outDir}`)
}
+/** File types that can carry absolute URLs. */
+const TEXT_ASSET_EXTENSIONS = new Set([
+ '.css',
+ '.html',
+ '.js',
+ '.json',
+ '.mjs',
+ '.svg',
+])
+
+/** Whether a root-absolute URL already sits under the deploy prefix. */
+function isUnderDeployBase(url: string, deployBase: string): boolean {
+ return deployBase === '/' || url === deployBase || url.startsWith(deployBase)
+}
+
+/**
+ * `url` without the deploy prefix, so a served URL maps onto its on-disk
+ * layout. The prefix moves URLs, not files.
+ */
+function stripDeployBase(url: string, deployBase: string): string {
+ return deployBase !== '/' && url.startsWith(deployBase)
+ ? `/${url.slice(deployBase.length)}`
+ : url
+}
+
+/** Prefix a root-absolute URL with the deploy base. Idempotent. */
+function serveUrl(url: string, deployBase: string): string {
+ if (!url.startsWith('/') || isUnderDeployBase(url, deployBase))
+ return url
+ return joinURL(deployBase, url)
+}
+
+/**
+ * Rewrite each URL prefix in a text asset, skipping occurrences that already
+ * carry the deploy prefix.
+ */
+function createTextRebaser(
+ rewrites: readonly (readonly [string, string])[],
+ deployBase: string,
+): (text: string) => string {
+ if (!rewrites.length || deployBase === '/')
+ return text => text
+ const prefixedBefore = deployBase.slice(0, -1)
+ return (text) => {
+ let result = text
+ for (const [from, to] of rewrites) {
+ result = result.replaceAll(from, (match: string, offset: number, whole: string) => {
+ const alreadyPrefixed = offset >= prefixedBefore.length
+ && whole.startsWith(prefixedBefore, offset - prefixedBefore.length)
+ return alreadyPrefixed ? match : to
+ })
+ }
+ return result
+ }
+}
+
+/** Rebase strings in an RPC payload that start with a registered URL prefix. */
+function createUrlValueRebaser(
+ rewrites: readonly (readonly [string, string])[],
+): (value: T) => T {
+ const rebaseString = (value: string): string => {
+ for (const [from, to] of rewrites) {
+ if (value === from.slice(0, -1))
+ return to.slice(0, -1)
+ if (value.startsWith(from))
+ return `${to}${value.slice(from.length)}`
+ }
+ return value
+ }
+ const visit = (value: T): T => {
+ if (typeof value === 'string')
+ return rebaseString(value) as T
+ if (Array.isArray(value))
+ return value.map(item => visit(item)) as T
+ if (value && typeof value === 'object') {
+ const prototype = Object.getPrototypeOf(value)
+ if (prototype !== Object.prototype && prototype !== null)
+ return value
+ return Object.fromEntries(
+ Object.entries(value).map(([key, item]) => [
+ key,
+ visit(item),
+ ]),
+ ) as T
+ }
+ return value
+ }
+ return visit
+}
+
+/** Rewrite the text assets under a copied static dir in place. */
+async function rebaseTextAssets(dir: string, rebase: (text: string) => string): Promise {
+ const entries = await fs.readdir(dir, { recursive: true, withFileTypes: true })
+ for (const entry of entries) {
+ if (!entry.isFile() || !TEXT_ASSET_EXTENSIONS.has(extname(entry.name)))
+ continue
+ const filepath = resolve(entry.parentPath, entry.name)
+ const text = await fs.readFile(filepath, 'utf-8')
+ const next = rebase(text)
+ if (next !== text)
+ await fs.writeFile(filepath, next, 'utf-8')
+ }
+}
+
/**
* Build a `mode: 'build'` hub context and mount the `devframes` input. The host
* copies nothing live (`mountStatic`/`mountConnectionMeta` are no-ops): every
@@ -213,7 +356,11 @@ async function createAndMountContext(options: BuildHubOptions, base: string, cwd
* remote source (e.g. a plugin's `--assets` package) resolves to the same
* locally-installed copy it would serve live.
*/
-async function copyBuildStatics(ctx: DevframeHubContext, resolveOutPath: (urlBase: string) => string): Promise {
+async function copyBuildStatics(
+ ctx: DevframeHubContext,
+ resolveOutPath: (urlBase: string) => string,
+ rebaseText?: (text: string) => string,
+): Promise {
const storageDir = ctx.host.getStorageDir('project')
for (const { baseUrl, source, resolveFrom } of ctx.views.buildStaticDirs) {
const target = resolveOutPath(baseUrl)
@@ -223,6 +370,8 @@ async function copyBuildStatics(ctx: DevframeHubContext, resolveOutPath: (urlBas
await fs.cp(resolved, target, { recursive: true })
else
await resolved.materialize(target)
+ if (rebaseText)
+ await rebaseTextAssets(target, rebaseText)
}
}
@@ -278,12 +427,17 @@ async function writeHubIndex(
base: string,
outDir: string,
options: BuildHubOptions,
+ deployBase: string,
): Promise {
await fs.writeFile(resolve(outDir, '__index.json'), `${JSON.stringify({
name: options.name,
version: options.version,
base,
- frames: ctx.frames.map(({ id, base, title }) => ({ id, base, title })),
+ frames: ctx.frames.map(({ id, base, title }) => ({
+ id,
+ base: serveUrl(base, deployBase),
+ title,
+ })),
endpoints: {
connection: DEVFRAME_CONNECTION_META_FILENAME,
clientImports: DEVFRAME_DOCK_IMPORTS_FILENAME,
@@ -307,19 +461,20 @@ async function writeConnectionMetas(
base: string,
outDir: string,
resolveOutPath: (urlBase: string) => string,
+ rebaseValue: (value: T) => T,
): Promise {
const jsonSerializableMethods: string[] = []
for (const def of ctx.rpc.definitions.values()) {
if (def.jsonSerializable === true)
jsonSerializableMethods.push(def.name)
}
- const meta: ConnectionMeta = {
+ const meta: ConnectionMeta = rebaseValue({
backend: 'static',
jsonSerializableMethods,
...(Object.keys(ctx.staticConfig).length > 0
? { configs: ctx.staticConfig }
: {}),
- }
+ } satisfies ConnectionMeta)
await fs.writeFile(resolve(outDir, DEVFRAME_CONNECTION_META_FILENAME), JSON.stringify(meta, null, 2), 'utf-8')
const frameMeta: ConnectionMeta = {
...meta,
diff --git a/packages/hub/src/node/diagnostics.ts b/packages/hub/src/node/diagnostics.ts
index 55933c41..b4acfe47 100644
--- a/packages/hub/src/node/diagnostics.ts
+++ b/packages/hub/src/node/diagnostics.ts
@@ -34,6 +34,10 @@ export const diagnostics = defineDiagnostics({
why: (p: { urlBase: string, base: string }) => `A static hub build writes each mount either under its base ("${p.base}") or as an absolute-path sibling of it, but "${p.urlBase}" is neither.`,
fix: 'buildHub maps a mount under the hub base into its `outDir`, and any other mount to the deploy root (`outDir`\'s parent) by its absolute path. Give the mount an absolute base (starting with `/`) so it resolves to one of those.',
},
+ DF8007: {
+ why: (p: { base: string, deployBase: string }) => `buildHub's base ("${p.base}") is not under its deployBase ("${p.deployBase}"), so the hub itself would be served outside the deploy root.`,
+ fix: 'Pass the hub mount base with the deploy prefix included, e.g. `base: "/ci-build-123456/__devtools/"` with `deployBase: "/ci-build-123456/"`.',
+ },
DF8100: {
why: (p: { id: string }) => `Dock with id "${p.id}" is already registered`,
fix: 'Use the `force` parameter to overwrite an existing registration.',
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts
index 4178d6dd..5553f68f 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts
@@ -5,6 +5,7 @@
export interface BuildHubOptions {
outDir: string;
base?: string;
+ deployBase?: string;
devframes?: DevframesInput;
context?: DevframeHubContext;
services?: DevframeServiceInput[];