docs: introduce Client Assets guide - #242
Merged
Merged
Conversation
…ing CDN back-proxy
Every static-assets seam (cli.distDir, hostStatic, mountStatic, the
serve-static engine) now accepts a version-locked RemoteAssets
declaration ({ package, version }) alongside a local directory, so a
plugin's browser bundle can live in its own npm package instead of
shipping inside the node tarball.
Resolution order per request: a locally installed copy of the assets
package (resolved from the declaration's resolveFrom, warning on
minor/patch skew and rejecting a major mismatch), the per-file cache
under <project storage>/.remote-assets/<pkg>@<version>/, then the CDN
provider (jsdelivr by default, unpkg or a custom mirror via provider) —
streaming through to the browser while teeing into the cache. Request
paths resolve against the provider's file listing (correct 404s and SPA
fallback), degrading to per-file probing when the listing is
unreachable. HTML navigations that cannot be satisfied get a styled
error page pointing at the local-install fix; static builds materialize
the full file set so their output stays self-contained.
New diagnostics DF0058–DF0063 cover listing/fetch/cache/materialization
failures and version skew, each with a docs page.
…sets # Conflicts: # docs/errors/DF0058.md # packages/devframe/src/node/diagnostics.ts # packages/devframe/src/node/host-h3.ts # tests/__snapshots__/tsnapi/devframe/adapters/build.snapshot.d.ts # tests/__snapshots__/tsnapi/devframe/index.snapshot.d.ts # tests/__snapshots__/tsnapi/devframe/internal.snapshot.d.ts # tests/__snapshots__/tsnapi/devframe/types.snapshot.d.ts
Collapse the remote-assets module's public API from eight exports to one (resolveStaticAssetsSource) — cache-path helpers, createRemoteAssetsStore, resolveInstalledRemoteAssets, and the store options interfaces are now private, and the error page moves into serve-static as an internal helper. resolveStaticAssetsSource takes the project storage dir directly (dropping the options object), so every call site loses the cacheRoot plumbing; the build adapter reuses it too instead of hand-rolling install/materialize. RemoteAssetsStore.serve now returns a web Response, letting serve-static drop the RemoteAssetsServedFile / RemoteAssetsServeOptions types and the bespoke miss/stream/cancel handling. Net ~370 fewer lines.
The installed-package resolution returns pathe (forward-slash) paths, but the tests built the expected distDir with node:path — backslashes on Windows — so the equality assertions failed only on windows-latest. Compare both sides normalized to forward slashes.
A remote source's `package` and `version` are interpolated into CDN URLs and the on-disk cache path, so `resolveStaticAssetsSource` now rejects a value that isn't a valid npm package name / exact semver version (new `DF0065`) — closing off malformed URLs and cache-path traversal (e.g. a `..` version segment).
Add a Client Assets guide covering how a devframe serves its built UI: mounting a local dist directory (the basic form) and, as a deferral, pointing cli.distDir at a published npm package (RemoteAssets) so the SPA is fetched on demand and cached locally. Covers resolution order, options, offline use, custom providers, and publishing. Cross-references the field from Devframe Definition, the build/dev adapters, and the Vite framework page.
antfubot
force-pushed
the
feat/docs-remote-assets
branch
from
August 16, 2026 23:32
a2eccfd to
90d9fc2
Compare
antfubot
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #236
Base branch is
feat/remote-client-assets(the remote-assets engine) — the page documents that feature and links toDF0065, so it builds against this branch. Review/merge #236 first.What
Adds
docs/guide/client-assets.md(under Fundamentals, after Devframe Definition). It covers how a devframe serves its built UI:cli.distDirdirectory form, SPA fallback, and mount-path-portable builds.cli.distDirat a published npm package via aRemoteAssetsdeclaration, so the SPA is fetched on demand and cached locally instead of bundled. Includes a basic example, resolution order (installed → cache → CDN), the options table, offline/air-gapped use, a custom provider, and publishing the assets package.Cross-references
Links the field from Devframe Definition (
distDiris nowstring | RemoteAssets), the build and dev adapter pages, and the Vite framework page.Verification
pnpm docs:buildpasses VitePress's dead-link check; lint clean.Created with the help of an agent.