Delivery & Versioning
How the Coframe SDK is delivered from the edge — and why there's no npm install
Copy this guide and your current settings as a prompt for your AI agent.
Preview agent promptSee the guide, code and settings included when you copy.
On this page
01How the SDK is delivered
The Coframe SDK is served as a <script> tag whose src points to the edge
worker at https://edge.cofra.me/cf.js. When the browser fetches that URL, the
edge worker returns a single JavaScript response that contains:
- A CFQ
projectDatapush — the project JSON and personalization headers baked into the response for the current visitor. - The compiled SDK bundle (modern or legacy build, selected by User-Agent).
This means the entire SDK and its project initialisation data arrive in one HTTP response, eliminating a separate fetch round-trip.
The edge also reads a config query parameter from the request. This parameter
carries a JSON-encoded, URL-encoded CoframeConfig object; the install snippet
builds and appends it automatically. The parameter must include at minimum
projectId and currentUrl and may be at most 16,384 characters before
URL-decoding.
The install snippet handles snippet construction for you. For the task-oriented guide and a copy-ready install snippet, see JavaScript Installation.
02Why there’s no npm package
The Coframe SDK is not published to npm. There is no npm install path for end
users — the script-tag-from-edge delivery model is the only supported
integration method.
The source is available on GitHub at https://github.com/Coframe/coframe-js.
03Versioned bundles
In addition to the default /cf.js route, the edge serves versioned bundles
identified by a 12-hex content hash, for example:
https://edge.cofra.me/cf-static-d1afdec09cc5.jsThe path pattern is /cf-static-{12hexchars}.js (and a
/cf-static-{12hexchars}-non-minified.js debug variant). These bundles are
stored in a static asset map compiled into the edge worker at deploy time.
Versioned bundles exist so that historical script tags continue to resolve after new deployments — sites that pin a specific content-hash URL receive the exact bundle they originally loaded. Both minified and non-minified variants are retained.
Current versions in the deployed edge:
| Component | Version |
|---|---|
Browser SDK (cf.js) |
1.0.1 |
| Edge worker | 1.0.0 |
04Caching & updates
Versioned bundles (/cf-static-*.js) are served with
Cache-Control: public, max-age=31536000, immutable, meaning browsers and
intermediate caches may hold them indefinitely — the content at a given hash URL
never changes.
The default /cf.js route is cached briefly and revalidated: it sets
Cache-Control: private, max-age=60 and an ETag (content hash), and returns
304 Not Modified when the browser’s If-None-Match still matches. So each
browser may reuse its copy for up to 60 seconds, then revalidates — letting SDK
and project-config changes propagate within about a minute. If you need a bundle
that is guaranteed never to change, pin a versioned /cf-static-*.js URL.
For config options that affect how the SDK initialises after it loads, see Config Reference.
# Delivery & Versioning
How the Coframe SDK is delivered from the edge — and why there's no npm install
## How the SDK is delivered
The Coframe SDK is served as a `<script>` tag whose `src` points to the edge
worker at `https://edge.cofra.me/cf.js`. When the browser fetches that URL, the
edge worker returns a single JavaScript response that contains:
- A CFQ `projectData` push — the project JSON and personalization headers baked
into the response for the current visitor.
- The compiled SDK bundle (modern or legacy build, selected by User-Agent).
This means the entire SDK and its project initialisation data arrive in one HTTP
response, eliminating a separate fetch round-trip.
The edge also reads a `config` query parameter from the request. This parameter
carries a JSON-encoded, URL-encoded `CoframeConfig` object; the install snippet
builds and appends it automatically. The parameter must include at minimum
`projectId` and `currentUrl` and may be at most 16,384 characters before
URL-decoding.
The install snippet handles snippet construction for you. For the task-oriented
guide and a copy-ready install snippet, see
[JavaScript Installation](../docs/javascript.html).
## Why there’s no npm package
The Coframe SDK is not published to npm. There is no `npm install` path for end
users — the script-tag-from-edge delivery model is the only supported
integration method.
The source is available on GitHub at
[https://github.com/Coframe/coframe-js](https://github.com/Coframe/coframe-js).
## Versioned bundles
In addition to the default `/cf.js` route, the edge serves versioned bundles
identified by a 12-hex content hash, for example:
PLAINTEXT
```
https://edge.cofra.me/cf-static-d1afdec09cc5.js
```
The path pattern is `/cf-static-{12hexchars}.js` (and a
`/cf-static-{12hexchars}-non-minified.js` debug variant). These bundles are
stored in a static asset map compiled into the edge worker at deploy time.
Versioned bundles exist so that historical script tags continue to resolve after
new deployments — sites that pin a specific content-hash URL receive the exact
bundle they originally loaded. Both minified and non-minified variants are
retained.
Current versions in the deployed edge:
Component |
Version |
Browser SDK (`cf.js`) |
`1.0.1` |
Edge worker |
`1.0.0` |
## Caching & updates
Versioned bundles (`/cf-static-*.js`) are served with
`Cache-Control: public, max-age=31536000, immutable`, meaning browsers and
intermediate caches may hold them indefinitely — the content at a given hash URL
never changes.
The default `/cf.js` route is cached briefly and revalidated: it sets
`Cache-Control: private, max-age=60` and an `ETag` (content hash), and returns
`304 Not Modified` when the browser’s `If-None-Match` still matches. So each
browser may reuse its copy for up to 60 seconds, then revalidates — letting SDK
and project-config changes propagate within about a minute. If you need a bundle
that is guaranteed never to change, pin a versioned `/cf-static-*.js` URL.
For config options that affect how the SDK initialises after it loads, see
[Config Reference](../docs/config-reference.html).