fix: deprecate resolveClientAssets exports from /define, which was never meant to be public

Author: antfu

packages/devframe/src/adapters/build.ts

@@ -9,12 +9,12 @@ import { colors as c } from 'devframe/utils/colors'
 import { resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
 import { structuredCloneStringify } from 'devframe/utils/structured-clone'
 import { dirname, resolve } from 'pathe'
+import { resolveClientAssets } from '../client-assets'
 import {
   DEVFRAME_CONNECTION_META_FILENAME,
   DEVFRAME_RPC_DUMP_DIRNAME,
   DEVFRAME_RPC_DUMP_MANIFEST_FILENAME,
 } from '../constants'
-import { resolveClientAssets } from '../define'
 import { createHostContext } from '../node/context'
 import { diagnostics } from '../node/diagnostics'
 import { createH3DevframeHost } from '../node/host-h3'

packages/devframe/src/adapters/initiate.ts

@@ -14,8 +14,8 @@ import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { H3 } from 'h3'
 import { resolve } from 'pathe'
 import { joinURL } from 'ufo'
+import { resolveClientAssets } from '../client-assets'
 import { DEVFRAME_CONNECTION_META_FILENAME } from '../constants'
-import { resolveClientAssets } from '../define'
 import { createHostContext } from '../node/context'
 import { diagnostics } from '../node/diagnostics'
 import { createH3DevframeHost } from '../node/host-h3'

packages/devframe/src/client-assets.ts

@@ -0,0 +1,15 @@
+import type { DevframeDefinition, StaticAssetsSource } from 'devframe/types'
+
+/**
+ * Resolve a definition's client assets source — the built SPA served as its
+ * UI. Prefers the top-level {@link DevframeDefinition.clientAssets} and falls
+ * back to the deprecated `cli.distDir`, so both the new and legacy shapes
+ * resolve. Returns `undefined` when neither is set (bridge mode — the SPA is
+ * hosted elsewhere).
+ *
+ * Internal: exposed to first-party integrations via `devframe/internal`, not
+ * part of the stable public API.
+ */
+export function resolveClientAssets(d: DevframeDefinition): StaticAssetsSource | undefined {
+  return d.clientAssets ?? d.cli?.distDir
+}

packages/devframe/src/define.ts

@@ -1,5 +1,6 @@
 import type { DevframeDefinition, DevframeNodeContext, StaticAssetsSource } from 'devframe/types'
 import { createDefineWrapperWithContext } from 'devframe/rpc'
+import { resolveClientAssets as resolveClientAssetsInternal } from './client-assets'
 
 export const defineRpcFunction = createDefineWrapperWithContext<DevframeNodeContext>()
 
@@ -12,12 +13,10 @@ export function defineDevframe(d: DevframeDefinition): DevframeDefinition {
 }
 
 /**
- * Resolve a definition's client assets source — the built SPA served as its
- * UI. Prefers the top-level {@link DevframeDefinition.clientAssets} and falls
- * back to the deprecated {@link DevframeCliOptions.distDir}, so both the new
- * and legacy shapes resolve. Returns `undefined` when neither is set (bridge
- * mode — the SPA is hosted elsewhere).
+ * @deprecated Read {@link DevframeDefinition.clientAssets} from the definition
+ * directly. This helper is internal machinery that was never meant to be part
+ * of the public API and is scheduled for removal.
  */
 export function resolveClientAssets(d: DevframeDefinition): StaticAssetsSource | undefined {
-  return d.clientAssets ?? d.cli?.distDir
+  return resolveClientAssetsInternal(d)
 }

packages/devframe/src/internal/index.ts

@@ -29,10 +29,16 @@
 // - `resolveBasePath` / `normalizeBasePath` — the mount-base resolution
 //   `initDevframe` itself uses; a bridge (`@devframes/vite`) that mounts a
 //   devframe onto a host it doesn't own reuses the exact same defaulting.
+// - `resolveClientAssets` — the definition → static-assets-source
+//   resolution every UI-serving adapter uses (`clientAssets`, falling back to
+//   the legacy `cli.distDir`), so a bridge that serves a devframe's SPA itself
+//   (`@devframes/vite`, `@devframes/next`, the hub's `ctx.install`) resolves it
+//   identically.
 // - `diagnostics` — devframe core's structured diagnostics instance
 //   (`DF00xx`), so a first-party integration built outside this package can
 //   report against the same registered codes instead of minting its own.
 export { normalizeBasePath, resolveBasePath } from '../adapters/_shared'
+export { resolveClientAssets } from '../client-assets'
 export { coerceAgentPositionalArgs } from '../node/agent-args'
 export type { AgentArgsFallback } from '../node/agent-args'
 export { diagnostics } from '../node/diagnostics'

packages/hub/src/node/install-devframe.ts

@@ -2,7 +2,7 @@ import type { DevframeDefinition } from 'devframe/types'
 import type { ClientScriptEntry, DevframeViewIframe } from '../types/docks'
 import type { DevframeHubContext } from './context'
 import { existsSync } from 'node:fs'
-import { resolveClientAssets } from 'devframe'
+import { resolveClientAssets } from 'devframe/internal'
 import { resolveBasePath } from 'devframe/node/hub-internals'
 import { basename, dirname, isAbsolute, resolve } from 'pathe'
 import { joinURL, withTrailingSlash } from 'ufo'

packages/next/src/handler.ts

@@ -3,8 +3,8 @@ import type { InitDevframeOptions } from 'devframe/initiate'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import process from 'node:process'
-import { resolveClientAssets } from 'devframe'
 import { initDevframe } from 'devframe/initiate'
+import { resolveClientAssets } from 'devframe/internal'
 
 export interface CreateDevframeNextHandlerOptions {
   /**

packages/vite/src/single.ts

@@ -4,9 +4,8 @@ import type { DevframeAuthHandler } from 'devframe/node/auth'
 import type { IncomingMessage, Server as NodeHttpServer, ServerResponse } from 'node:http'
 import type { Plugin } from 'vite'
 import process from 'node:process'
-import { resolveClientAssets } from 'devframe'
 import { initDevframe } from 'devframe/initiate'
-import { diagnostics, normalizeBasePath, resolveBasePath } from 'devframe/internal'
+import { diagnostics, normalizeBasePath, resolveBasePath, resolveClientAssets } from 'devframe/internal'
 import { resolveStaticAssetsSource } from 'devframe/utils/remote-assets'
 import { serveStaticNodeMiddleware } from 'devframe/utils/serve-static'
 import { join, resolve } from 'pathe'

tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts

@@ -511,6 +511,7 @@ export type StaticAssetsSource = string | RemoteAssets;
 
 // #region Functions
 export declare function defineDevframe(_: DevframeDefinition): DevframeDefinition;
+/** @deprecated */
 export declare function resolveClientAssets(_: DevframeDefinition): StaticAssetsSource | undefined;
 // #endregion
 

tests/__snapshots__/tsnapi/devframe/index.snapshot.js

@@ -3,6 +3,7 @@
  */
 // #region Functions
 export function defineDevframe(_) {}
+/** @deprecated */
 export function resolveClientAssets(_) {}
 // #endregion