static-assets

30 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Static assets served before Worker script by default

When both static assets and a Worker script are configured, Cloudflare attempts to serve static assets first if one matches the incoming request. If no matching static asset is found, Cloudflare invokes the Worker script.

Combining static assets with Worker script

Static assets and Worker scripts can be combined together to create powerful applications such as full-stack applications, Single Page Applications (SPAs), or Static Site Generation (SSG) applications with an API.

Custom headers and redirects for Vite plugin static assets

Custom headers and redirects are supported at build, preview and deploy time by adding _headers and _redirects files to your public directory. The paths in these files should reflect the structure of your client build output, with generated assets typically located in an assets subdirectory.

Vite plugin static assets automatic detection

The Vite plugin does not require the assets field in configuration. It automatically determines whether to include assets based on whether the client environment has been built. The client environment is built if any of these conditions are met: there is an index.html file in the root, build.rollupOptions.input or environments.client.build.rollupOptions.input is specified in the Vite config, there is a non-empty public directory, or the Worker imports assets as URLs.

Vite plugin generates wrangler.json with assets.directory

When running vite build, the Vite plugin generates an output wrangler.json configuration file as part of the build output. The assets.directory field in this file is automatically populated with the path to the client build output, so you do not need to manually provide the assets.directory field in your input Worker configuration.

Vite plugin assets configuration for routing and binding

The assets configuration should be used if you wish to set routing configuration or enable the assets binding. Example configuration for single-page application not_found_handling: {"assets": {"not_found_handling": "single-page-application"}}

Vite plugin static asset handling features

The Vite plugin ensures that all of Vite's static asset handling features are supported in the Worker and frontend. These features include importing assets as URLs, importing as strings, importing from the public directory, and inlining assets.

Fetching assets imported as URLs via assets binding

Assets imported as URLs can be fetched via the assets binding. The binding's fetch method requires a full URL, so it is recommended to use the request URL as the base. Example: import myImage from "./my-image.png"; export default { fetch(request, env) { return env.ASSETS.fetch(new URL(myImage, request.url)); } };

Assets imported as URLs moved to client build output

Assets imported as URLs in your Worker are automatically moved to the client build output. When running vite build, the paths of any moved assets are displayed in the console.

Multi-Worker application asset access limitation

If you are developing a multi-Worker application, assets can only be accessed on the client and in your entry Worker.

Static assets with single-page-application not_found_handling

Set assets.not_found_handling to 'single-page-application' in wrangler configuration to serve index.html for all not found requests. This ensures routing configuration works consistently between development and production.

Directory field not used with Vite plugin

When using the Cloudflare Vite plugin, do not specify the directory field in the assets configuration. The output directory is automatically set to the client build output.

Direct upload is an advanced API approach for static assets

Directly uploading assets via APIs is an advanced approach which, unless building a programmatic integration, most users will not need. Users are encouraged to deploy Workers with Wrangler instead.

Static assets uploaded via API can be served for free

Static assets uploaded via the Workers API can be served for free, and users can also fetch assets through an optional assets binding to power more advanced applications.

Three phases of asset upload flow

The asset upload flow consists of three distinct phases: 1) Registration of a manifest, 2) Upload of the assets, 3) Deployment of the Worker.

Asset manifest structure with hash and size

The asset manifest is a ledger tracking files for the Worker. Each file is a key representing the file path and name, containing an object with metadata: hash (32 hexadecimal character hash of the file) and size (size in bytes).

Manifest upload endpoint for Workers for Platforms

POST /client/v4/accounts/:accountId/workers/dispatch/namespaces/:dispatchNamespace/scripts/:scriptName/assets-upload-session is used to register the asset manifest for Workers for Platforms.

Manifest upload response contains JWT and bucket instructions

The manifest upload response contains a JWT (valid for one hour) which provides authentication during file upload, and a buckets field with instructions on how to optimally batch upload files. Each array in buckets contains file hashes to upload together. Unmodified files are not returned in buckets.

Empty buckets means skip to script deployment

If all assets have been previously uploaded, buckets will be empty and jwt will contain a completion token. Uploading files is not necessary and you can skip directly to uploading a new script or version.

File upload API endpoint

POST /client/v4/accounts/:accountId/workers/assets/upload?base64=true is used to upload static asset files.

File upload requirements and format

Files must be uploaded using multipart/form-data. The contents of each file must be base64 encoded, and the base64 query parameter in the URL must be set to true. The provided Content-Type header of each file part will be attached when serving the file. If you wish to avoid sending a Content-Type header, application/null may be sent at upload time. The Authorization header must be provided as a bearer token using the JWT from the manifest upload call.

File upload completion response contains JWT

Once every file in the manifest has been uploaded, a status code of 201 is returned with the jwt field present. This JWT is a final completion token which can be used to create a deployment of a Worker with this set of assets. The completion token is valid for 1 hour.

Worker metadata requires assets jwt or keep_assets option

When creating or deploying a new Worker version with assets, the metadata part in form data must include either the completion token from the upload assets step in the assets.jwt field, or a boolean keep_assets option if re-using an existing set of assets without specifying a new completion token.

Worker metadata example with completion token

Example Worker metadata specifying completion token: { "main_module": "main.js", "assets": { "jwt": "<completion_token>" }, "compatibility_date": "2021-09-14" }

Worker metadata example with keep_assets option

Example Worker metadata specifying keep_assets: { "main_module": "main.js", "keep_assets": true, "compatibility_date": "2021-09-14" }

Asset routing configuration in metadata

Asset routing configuration can be provided in the assets object, such as html_handling and not_found_handling options.

Worker metadata example with asset configuration

Example Worker metadata specifying asset configuration: { "main_module": "main.js", "assets": { "jwt": "<completion_token>", "config": { "html_handling": "auto-trailing-slash" } }, "compatibility_date": "2021-09-14" }

Assets binding in Worker metadata

An assets binding can be provided if you wish to fetch and serve assets from within Worker code. The binding is defined as an object with type "assets" and a name property.

Worker metadata example with assets binding

Example Worker metadata specifying asset binding: { "main_module": "main.js", "assets": { "jwt": "<completion_token>" }, "bindings": [ { "name": "ASSETS", "type": "assets" } ], "compatibility_date": "2021-09-14" }

Programmatic static assets upload example TypeScript

Complete working example showing how to upload static assets to Cloudflare Workers using the cloudflare-typescript SDK. The example demonstrates creating a manifest from a directory, uploading assets in batches, creating a Worker version with asset bindings, and deploying it. It handles manifest creation, asset uploading, Worker creation, version creation with deployment. Environment variables required: CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID, ASSETS_DIRECTORY, and optional CLOUDFLARE_SUBDOMAIN.

Give your agent this brain