Backend targets

Prepare a backend target, read its artifact closure and frozen resolution, and run it in an environment of your own. The CDN never runs it.

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

Starting state

Your application has server code authored as public modules. You want the CDN to compile and deliver it together with the frontend, as part of the same immutable release.

Define the target

JSON
{ "kind": "backend", "package": "@example/api", "selection": "1.0.0", "entry": ".", "runtime": "node>=22" }

Send it with targets.define, for example to /v1/applications/{application}/targets/api. runtime is a requirement you state to whoever runs the target. The CDN stores it and reports it back; it does not check or provide the runtime.

Backend modules need no Widgets. They are public modules compiled for a server target, so their delivery requests use target=node:

Text
/m/@example/api@1.0.0/modules/~root?target=node&format=esm

Prepare, then read the closure

Register and prepare as for any target. Once the release is ready, read the closure of the backend target:

Operation Request Capability
releases.closure GET /v1/applications/{application}/releases/{release}/targets/{target}/closure application.read
Member Meaning
entry The public specifier to import first, and its origin-relative url
runtime The requirement you stated on the target
conditions, format What the outputs were built for. format is esm.
resolution The frozen beyond-resolution/1 document of the target
artifacts Every artifact of the closure: origin-relative url, kind (module, style, map, asset), digest, bytes and media
ready Whether every artifact is durable and retrievable

A closure of a release that is not in a state that has one answers 409 STATE_INVALID.

ready reports artifacts only. It says that the bytes exist and can be fetched. It says nothing about a process, a port or a health check, because the CDN starts none.

Run it yourself

Your environment does three things, in this order:

  1. Fetch the closure and verify each artifact against its digest.
  2. Resolve imports with the frozen resolution, prepending the CDN origin to each origin-relative URL.
  3. Import the entry.

How you load ES modules from URLs depends on your runtime and is outside this contract. Pin the release: the closure of a release never changes, so a host that loaded release 12 keeps running release 12 until you deploy another.

Limits

  • Rolling back the frontend does not roll back your host. Coordinate the two yourself, and remember that a code rollback cannot undo database changes.
  • Secrets never belong in a target, a module or a URL. Provide them in your own environment.
  • A private application restricts who can fetch its artifacts. Give your host its own access; see Private access.