Beyond CDN
What the Beyond CDN prepares and delivers, how its three stages work, what a GET request can never do, and what is outside version 1.
- Availability: Experimental
- Evidence: Read from source
- Explanation
What the CDN does
The Beyond CDN prepares a published application and then delivers it. An application has frontend targets, backend targets, or both. Each target names a public entry of a package, and the CDN works out everything that entry needs: the exact package versions, the public modules that are reachable from it, their styles and the static assets the packages declare.
Delivery is plain HTTP. A compiled public module has one address, and that address has the same relative form on a local development server and on the CDN:
https://cdn.beyondjs.com/m/@example/app@1.0.0/modules/core/router?target=browser&format=esm
https://cdn.beyondjs.com- Base origin: the only part you change
/m/- Namespace
@example/app- Package
@1.0.0- Exact version
/modules/- Resource family
core/router- Public module subpath
?target=browser&format=esm- Options
A consumer that works against a development server works against the CDN by changing the base origin and nothing else. The path, the options, the response headers and the error bodies follow one shared contract, @beyond-js/artifact-api. See URLs and identities.
Every origin also answers its resolution, /resolution.json and /importmap.json: which address delivers each public specifier. Each environment consumes those two documents its own way: a browser with an import map or with SystemJS, Node.js through BEE Node, Deno with --import-map. The model is one; the strategies differ. See Strategies per environment.
Packages come from npm, from other npm-compatible registries reachable over the Internet, from Git repositories pinned to a commit and from archive URLs pinned to a digest, and the address of every module says which. A public package produces public outputs even when your organization's token was used to read it. See Sources and Registry providers.
How this section is verified
Two kinds of verification apply to these pages, and they are not the same thing.
- Contract-verified. An automated test compares the reference with the contracts: every management operation with its method, path, capability and retry kind; every error and failure code with its status; every event type with its channels and delivery class; every request option with its values and default; the role table and the capabilities that depend on an environment; the members of a registration request; the quota names; the realtime pointer; and every engineering default a page cites. A page that names something the contracts do not define fails that test.
- Runtime-verified. An example was executed against a real service and its outcome was recorded. Nothing is deployed and the integrated service is still being assembled, so every example that needs an origin is recorded as not executed. The one exception is the resolution example, which runs offline against the shared codec.
A page labelled "Read from source" is contract-verified only. No page in this section claims a supported release.
Retrieval never compiles
A GET request to the CDN returns content that already exists, or reports that it does not. It never starts a build, resumes one or places work in a queue. This holds for every retrieval: a module, a stylesheet, a source map, an asset, a browser navigation and a cache miss.
When the CDN knows a module but does not hold the output you asked for, it answers 404 with the code OUTPUT_NOT_AVAILABLE. Asking again gives the same answer. Work starts only when someone sends an explicit preparation request through the management API.
This is the main difference from a development server. The Packages Dev Server compiles from your current sources when you request a module, and answers BUILD_FAILED when they do not compile. The CDN does not contain a development server and never runs one.
The three stages
Preparation is three separate stages. Each has its own durable state, logs and realtime events, and each can fail without touching the release that is live.
| Stage | What happens | What it does not do |
|---|---|---|
| 1. Register and resolve | You register the application, its targets and its dependency selections. The CDN resolves the complete package and version graph from registry metadata and pins it, with the origin and integrity of every package. | It analyzes no code and downloads no package archive. A provider that offers no metadata is recorded as an exception that required fetching a manifest. |
| 2. Prepare and analyze | An independent task downloads every package of the pinned graph that the CDN does not already hold, verifies its integrity and enforces size limits. It then traces what is reachable from your entries and stores an inventory: eager and lazy public modules, styles as modules, and declared assets. | It does not download packages one by one as modules are reached, and it does not compile every module of every package. Analysis is separate from generation. |
| 3. Generate and serve | Only the outputs that are missing are queued. Compatible work that another authorized application already paid for is reused. When every required output is stored and retrievable, the release becomes ready. | A finished worker or one stored file is not readiness. The whole serving closure must be durable. |
A public dependency does not wait for your application. Every public output whose own reachable closure was verified becomes available by its exact identity as soon as the preparation that produced it ends, whether your release ended ready or failed, and without the application being promoted to any environment. If your own module does not build, the React version that did build is still served to whoever asks for it; if React itself fails, nothing that imports it is served. This never lowers the bar for your release: that one is ready only with its entire closure.
Reachability from static analysis has a limit. A dynamic import whose target cannot be determined needs an explicit declaration, or it is reported as a diagnostic and the closure is not complete. See Preparation and inventory.
Releases
A release is immutable. Promoting a release binds an environment (production or testing) to it with an atomic compare-and-set, and rolling back rebinds the environment to a retained release. Neither operation resolves dependencies again or rebuilds anything. A failed preparation or a rejected promotion leaves the active release as it was. See Releases, promotion and rollback.
Once published, an application stays deliverable without npm for as long as its sources and artifacts are retained. A registry outage can block new inputs that are not cached. This is independence backed by retention, not a promise of unlimited storage or permanent availability.
What keeps bytes is a reference, never a visit: an output is retained because a live release, a release retained for rollback or a preparation in flight still needs it, and not because it was requested recently. When the last of those goes, the output and its published identity are released together. Asking for a public identity does not make it retained, and no URL is promised forever.
Development and the CDN together
The Packages Dev Server remains where you edit sources, use the File API and receive HMR updates. During local or cloud development the CDN supplies the released external dependencies, while the Dev Server serves the modules you are editing. Both answer the same module URLs and the same resolution routes. The Dev Server's editing, session and update endpoints are specific to development and do not exist on the CDN. The development runtime applies updates the same way in a browser, with SystemJS, in Node.js and in Deno; see During development.
Free and premium
Version 1 has free and premium capabilities and no payments or checkout. A platform operator enables premium for an organization manually, and credit belongs to the organization, never to a user.
| Free | Premium (enabled manually) | |
|---|---|---|
| Applications | Public | Public or private, with expiring guest access |
| Execution | Shared queue, scheduled in short turns across applications, no SLA | Same tasks without the short turn, with safety timeouts and credit limits |
| Build errors | Always reported | Always reported |
| Semantic TypeScript Diagnostics | Not included | Included, measured separately |
| Testing subdomain and custom domains | One testing subdomain per application; verified custom domains | Same |
Storage and traffic are not promised free or unlimited. See Plans, credit and usage and Quotas.
Outside version 1
Where to go next
- Quickstart: request one prepared module from two origins with one client.
- Delivery reference: URLs, options, outputs, environments and loaders, resolution, caching, private access and errors.
- Management reference: applications, the three stages, jobs, releases, domains, access, plans and quotas.
- Realtime reference: channels, events, reconnecting and revocation.
- Guides: publishing packages, ordinary npm dependencies, Widgets and view frameworks, backend targets and troubleshooting.