Publish Beyond source to npm

Publish a package as Beyond source so that the CDN recognizes it and compiles its public modules through Packages.

  • Availability: Planned
  • Evidence: Read from source
  • How-to guide

Starting state

You have a Beyond package with public modules, and you want applications on the CDN to depend on it. There are two publication forms. This guide covers the source form: you publish your sources, and the CDN compiles the public modules that applications actually reach. For the other form see Publish a precompiled distribution.

Choose the source form when you want the CDN to produce outputs for the conditions and formats each application asks for, with the compiler version the CDN runs.

Declare the form

A package states how it was published in the beyond.publication field of its package.json:

JSON
{
  "name": "@acme/shop",
  "version": "1.4.0",
  "type": "module",
  "beyond": {
    "publication": { "protocol": "beyond-publication/1", "form": "source", "modules": "modules" }
  }
}
Member Required Meaning
protocol Yes beyond-publication/1
form Yes source
modules No The package-relative root of the public module sources. The package default applies when absent.

The field is the only discriminator. File extensions and directory layout never decide the form.

Publish

Publish the package to your registry with your usual npm tooling, and make sure the archive includes the sources of your public modules.

Use it from an application

Name the package in a target or in the selections of a registration. During preparation the CDN downloads the pinned version, verifies its integrity, reads the field and compiles only the public modules that are reachable from the application's entries.

Failures and limits

Situation Outcome
The field is present and invalid: "publication": true, a missing protocol, an unknown form An error. It is never treated as an ordinary npm package.
The field mixes members of both forms, such as modules together with compiler Rejected: a field cannot describe both forms
protocol is a later version than the CDN knows UNSUPPORTED_INPUT
A public module does not compile The preparation job fails with BUILD_FAILED and its diagnostics. The active release is untouched.
  • Internal source files do not become public modules by being published. Only the public modules of the package are addressable.
  • A dynamic import with a computed target must be declared, or the closure cannot be completed. See Preparation and inventory.
  • A package whose public modules share private files is reported as unsupported, because code is divided by public module only and nothing is split further. Svelte and Shoelace components are known cases.