Build Output

Build Output is the deployable artifact produced by a Workers build implementation. It separates configuration evaluation and bundling from upload and deployment.

cf build validates Build Output after the project build finishes. cf deploy, cf previews deploy, cf workers versions create, cf workers triggers deploy, and cf workers check can reuse an existing artifact with --prebuilt.

Build Output is versioned at v0.

Build implementations write this project-relative structure:

The top-level config.json is required. Each Worker directory contains worker.config.json and at least one of bundle/ or assets/. Each Container directory contains container.config.json.

The reader accepts additional Worker directories. Commands use the Worker in workers/default/ unless you pass --worker <NAME>, which selects the Worker whose worker.config.json has that name. An unknown name fails before cf sends any API request, and the error lists the available Workers.

The root config.json contains the account settings from the default export of cloudflare.config.ts. It also records the context used for the build.

{
	"accountId": "<ACCOUNT_ID>",
	"complianceRegion": "public",
	"buildContext": {
		"isPreview": false,
		"mode": "production"
	}
}

Commands that take --prebuilt compare their --mode value with buildContext.mode:

• When Build Output records a mode, pass exactly that mode with --mode.
• When Build Output records no mode, do not pass --mode.

Vite builds always record a mode, and cf build without --mode records production. Builds through Wrangler record a mode only when you pass --mode to cf build.

buildContext.isPreview is true for output built by cf previews deploy. cf deploy, cf workers versions create, and cf workers triggers deploy refuse preview output.

worker.config.json contains the resolved Worker configuration. It replaces the source entrypoint with a build manifest.

The manifest identifies the main module and bundled module types. Supported types are esm, cjs, python, python-requirement, wasm, text, data, json, and sourcemap.

Declare a source map as a module with type sourcemap:

{
	"manifest": {
		"type": "complete",
		"mainModule": "index.js",
		"modules": {
			"index.js": { "type": "esm" },
			"index.js.map": { "type": "sourcemap" }
		}
	}
}

Set type to partial when the reader should discover additional modules in bundle/. A partial manifest must still identify an ES module as its main module.

The declared source map must exist under bundle/, such as bundle/index.js.map. cf deploy and cf workers versions create validate and upload declared source maps. A manifest cannot use a source map as its main module.

bundle/ contains compiled Worker modules. assets/ contains static files served with the Worker.

A Worker must contain a bundle, assets, or both.

container.config.json contains the resolved Container application configuration. The build implementation must build any local Dockerfile first and record the resulting image as a local reference.

cf deploy uploads local images and applies supported application settings for Containers referenced by the Worker. cf workers versions create records Container metadata and prepares images for Durable Object-managed Containers, but it does not apply Container applications.

The Cloudflare Vite plugin reads cloudflare.config.ts, builds each Vite environment, and writes Build Output. cf uses the plugin's 2.0 beta (@cloudflare/vite-plugin@beta), which writes Build Output whether cf build or vite build runs the build.

The plugin cleans previous output before a full build. It writes bundles and assets to the standard Build Output paths.

Use --prebuilt to deploy an existing artifact without running another build. Preserve the complete .cloudflare/output/v0/ directory, and pass the mode that Build Output records:

cf deploy --prebuilt --mode production

For the mode rule and more examples, refer to Deploy a prebuilt build. For a pipeline that builds in one job and deploys in another, refer to Use cf in CI.

The Build Output reader validates the root, Worker, and Container configuration files against shared schemas. It requires the default Worker and at least one bundle or asset directory for each Worker.

After reading the artifact, cf converts the Worker configuration to the deployment helper format. cf reports configuration and upload errors separately from malformed Build Output errors.