Vite plugin eliminates assets.directory configuration
When using the Cloudflare Vite plugin, you do not need to specify `assets.directory` in wrangler.json, as the plugin handles static assets configuration automatically.
Cloudflare Workers · all subjects
configuration
366 notes in this subject, read out of this brain and free to use. This is page 5 of 7.
Wrangler configuration for selective run_worker_first routing
Example wrangler.json configuration showing selective Worker-script-first routing: { "name": "my-spa-worker", "compatibility_date": "$today", "main": "./src/index.ts", "assets": { "directory": "./dist/", "not_found_handling": "single-page-application", "binding": "ASSETS", "run_worker_first": ["/api/*", "!/api/docs/*"] } }
not_found_handling configuration option
The `not_found_handling` option under `assets` in Wrangler configuration controls the default behavior for requests that don't match a static asset. It accepts two values: 'single-page-application' (returns 200 OK with index.html) and '404-page' (returns 404 Not Found with nearest 404.html).
Wrangler configuration for static assets with SPA routing
Example wrangler.json configuration for a Single Page Application with static assets: { "assets": { "directory": "./dist", "not_found_handling": "single-page-application" } }
Static assets directory configuration
Static assets are uploaded from the directory specified in the Wrangler configuration file under the `assets.directory` field. During deployment, Wrangler automatically uploads files from this directory to Cloudflare's infrastructure, and requests are routed to locations closest to users.
Wrangler configuration for single-page applications
For single-page applications migrated from Netlify to Workers, create a wrangler.jsonc or wrangler.toml file in the root of the project. The configuration must include a name field with the project name, a compatibility_date field set to today, and an assets object with a directory field set to the build directory from Netlify and a not_found_handling field set to 'single-page-application'.
Wrangler configuration for static sites
For static sites migrated from Netlify to Workers, create a wrangler.jsonc or wrangler.toml file in the root of the project. The configuration must include a name field with the project name, a compatibility_date field set to today, and an assets object with a directory field set to the build directory from Netlify.
Static site wrangler configuration
For a static site migrating from Vercel, create a wrangler.jsonc or wrangler.toml file in the project root with the following configuration: name (project name), compatibility_date, and assets.directory (the build directory from Vercel, e.g., ./dist or ./build).
Single page application wrangler.jsonc example
{ "name": "<your-project-name>", "compatibility_date": "$today", "assets": { "directory": "<your-build-directory>", "not_found_handling": "single-page-application", }, }
Static site wrangler.jsonc example
{ "name": "<your-project-name>", "compatibility_date": "$today", "assets": { "directory": "<your-build-directory>", }, }
Single page application wrangler configuration
For a single page application migrating from Vercel, create a wrangler.jsonc or wrangler.toml file in the project root with name, compatibility_date, assets.directory, and assets.not_found_handling set to "single-page-application".
Redirects configuration for Workers static assets
Workers static assets can be configured with redirect rules using a _redirects file.
none HTML handling behavior
With html_handling set to none, built-in HTML handling is disabled entirely. Only requests for files with exact extensions like /file.html or /folder/index.html are served as 200. All other requests depend on the not_found_handling configuration for their response and asset served.
auto-trailing-slash HTML handling behavior
With html_handling set to auto-trailing-slash, individual HTML files are served without a trailing slash and folder index files are served with a trailing slash. Requests for /file are served as 200 from /dist/file.html. Requests for /file.html and /file/ redirect with 307 to /file. Requests for /folder redirect with 307 to /folder/. Requests for /folder/ are served as 200 from /dist/folder/index.html. Requests for /folder.html and /folder/index redirect with 307 to /folder.
drop-trailing-slash HTML handling behavior
With html_handling set to drop-trailing-slash, all canonical URLs have no trailing slashes. Requests for /file are served as 200 from /dist/file.html. Requests for /file.html, /file/, /file/index, and /file/index.html redirect with 307 to /file. Requests for /folder are served as 200 from /dist/folder/index.html. Requests for /folder.html, /folder/, /folder/index, and /folder/index.html redirect with 307 to /folder.
HTML handling configuration options
The assets.html_handling configuration in wrangler.json determines how requests for HTML content are redirected and rewritten. It specifies the pattern for canonical URLs and where Cloudflare serves HTML content from and redirects non-canonical URLs to. Valid options are: auto-trailing-slash (default), force-trailing-slash, drop-trailing-slash, and none.
Trailing slash SEO impact
Forcing or dropping trailing slashes on request paths impacts SEO because search engines often treat URLs with and without trailing slashes as different, separate pages. This distinction can lead to duplicate content issues, indexing problems, and overall confusion about the correct canonical version of a page.
Headers and redirects files support in Workers
Workers natively supports _headers and _redirects files for static assets, just like Pages. Ensure these files are included in the static asset directory of the project.
Wrangler configuration mandatory fields
A Wrangler configuration file (wrangler.jsonc, wrangler.json, or wrangler.toml) requires two mandatory fields: 'name' (the name of the Worker to deploy to, must conform to Workers name restrictions including max length) and 'compatibility_date' (can be the same date from Pages Functions if migrating, or the current date for new projects).
Migration: Pages build output directory to Workers assets directory
When migrating from Pages to Workers, the Pages 'pages_build_output_dir' configuration must be replaced with the Workers 'assets.directory' configuration. Example: Pages used {"name": "my-pages-project", "pages_build_output_dir": "./dist/client/"} whereas Workers uses {"name": "my-worker", "compatibility_date": "$today", "assets": {"directory": "./dist/client/"}}.
Assets binding requires main property in Workers configuration
The 'binding' field in the assets configuration is only valid if the Worker configuration includes a 'main' property pointing to a Worker script. If a Worker will only contain assets and no Worker script, the 'binding' field should be removed.
Workers requires explicit asset serving behavior configuration
Unlike Pages which automatically attempts to determine serving behavior (SPA vs custom 404), Workers requires explicit manual configuration of asset serving behavior. This is set via the 'assets.not_found_handling' field which accepts values 'single-page-application' for SPA or '404-page' for custom 404 pages.
Single Page Application configuration in Workers
To configure a Single Page Application in Workers, set the assets configuration to include 'not_found_handling': 'single-page-application'. Example: {"name": "my-worker", "compatibility_date": "$today", "assets": {"directory": "./dist/client/", "not_found_handling": "single-page-application"}}.
Custom 404 page configuration in Workers
To configure custom 404 pages in Workers, set the assets configuration to include 'not_found_handling': '404-page'. Example: {"name": "my-worker", "compatibility_date": "$today", "assets": {"directory": "./dist/client/", "not_found_handling": "404-page"}}.
.assetsignore file to exclude assets from upload
Create an .assetsignore file in the project's static asset directory to exclude certain files and folders from being uploaded as static assets, similar to how Pages automatically excluded some files. The .assetsignore file uses glob patterns such as **/node_modules, **/.DS_Store, and **/.git.
Migrating Pages Functions with _worker.js advanced mode
When migrating Pages Functions that use an 'advanced mode' _worker.js file, the script must not be uploaded as a static asset. Either move _worker.js out of the static asset directory (recommended) or create an .assetsignore file in the static asset directory and include _worker.js. Then update the Wrangler configuration's 'main' field to point to the _worker.js location.
Compile Pages Functions folder to Workers script
To migrate Pages Functions that use a 'functions/' folder, compile them into a single Worker script using the command: wrangler pages functions build --outdir=./dist/worker/. Then update the Wrangler configuration's 'main' field to point to the compiled script location, typically ./dist/worker/index.js.
Workers default asset serving order differs from Pages
Pages defaults to serving Pages Functions ahead of static assets. Workers defaults to serving static assets ahead of the Worker script. To replicate Pages behavior, set 'assets.run_worker_first': true in the configuration. This option is required when performing authentication checks or logging requests before serving static assets.
Configuring placement, compatibility flags in Workers
If migrating from Pages with customized placement, compatibility date, or compatibility flags, these can be defined in the Workers Wrangler configuration file. Example: {"name": "my-worker", "compatibility_date": "$today", "compatibility_flags": ["nodejs_compat"], "placement": {"mode": "smart"}, "assets": {"directory": "./dist/client/"}}.
Variables and bindings availability in Workers
Variables and bindings can be set in the Wrangler configuration file and are made available in the Worker's environment (env). Secrets can be uploaded with Wrangler, defined in the Cloudflare dashboard for production, or defined in .dev.vars for local development.
Workers Builds requires separate build environment variable configuration
Unlike Pages, Workers does not share the same set of runtime and build-time variables. When using Workers Builds, any variables relevant to the build environment must be separately configured in the Workers Builds configuration.
Enable preview URLs in Workers configuration
To enable preview URLs in Workers, set 'preview_urls': true in the Wrangler configuration file. Example: {"name": "my-worker", "compatibility_date": "$today", "main": "./worker/index.ts", "assets": {"directory": "./dist/client/"}, "preview_urls": true}.
Different bindings in production vs non-production builds limitation
Unlike Pages, Workers does not natively support defining different bindings in production vs. non-production builds. As a workaround, consider using Wrangler Environments with an appropriate Workers Build configuration.
Workers.dev subdomain configuration
Workers offers a personalized workers.dev subdomain for Worker projects. This can be configured in the Cloudflare dashboard and enabled with the 'workers_dev' option in the Wrangler configuration file. Example: {"name": "my-worker", "compatibility_date": "$today", "main": "./worker/index.ts", "workers_dev": true}.
Custom domains support in Workers
Workers supports custom domains when the domain's nameservers are managed by Cloudflare, similar to Pages. Additionally, Workers allows configuring a route to serve only specific paths with a Worker.
Workers custom domain nameserver requirement
Unlike Pages, Workers requires that custom domains must have their nameservers managed by Cloudflare. Workers does not support custom domains whose nameservers are not managed by Cloudflare.
Early Hints support on Workers requires zone setting and Link headers
Workers can use Early Hints when the zone setting is turned on. The Worker must send the appropriate Link headers. Refer to the 103 Early Hints example for implementation details.
Serving static assets from subdirectory requires Wrangler v3.98.0+
The feature to configure a Worker with static assets on a subpath requires Wrangler v3.98.0 or later.
assets.html_handling behavior options
The assets.html_handling option supports three modes. auto-trailing-slash is the default and serves individual files (e.g. foo.html) without a trailing slash and folder index files (e.g. foo/index.html) with a trailing slash. force-trailing-slash adds trailing slashes to all HTML page requests. drop-trailing-slash removes trailing slashes from all HTML page requests.
Custom 404 page handling with assets.not_found_handling
Configuring assets.not_found_handling to "404-page" overrides the default serving behavior of Workers for static assets. When an incoming request does not match a file in the assets.directory, Workers will serve the contents of the nearest 404.html file with a 404 Not Found status.
Required and optional assets configuration for SSG
To deploy a Static Site Generation application to Workers, you must configure assets.directory in your Wrangler configuration file. Optionally, you can configure assets.not_found_handling and assets.html_handling. The assets.html_handling option defaults to auto-trailing-slash.
Wrangler assets configuration example for SSG
Example SSG configuration in wrangler.json: ```json { "name": "my-worker", "compatibility_date": "$today", "assets": { "directory": "./dist/", "not_found_handling": "404-page", "html_handling": "auto-trailing-slash" } } ```
SPA configuration with run_worker_first example
Example Wrangler configuration for SPA with advanced routing: ```json { "name": "my-worker", "compatibility_date": "$today", "main": "./src/index.ts", "assets": { "directory": "./dist/", "not_found_handling": "single-page-application", "binding": "ASSETS", "run_worker_first": ["/api/*", "!/api/docs/*"] } } ``` This configuration provides explicit routing control without relying on browser navigation headers. The run_worker_first array pattern "/api/*" with negation "!/api/docs/*" demonstrates route matching and exclusion.
SPA single-page-application mode configuration
To deploy a Single Page Application to Workers, configure assets.directory and assets.not_found_handling in the Wrangler configuration file. Set assets.not_found_handling to "single-page-application" to override default serving behavior. When an incoming request does not match a file in assets.directory, Workers will serve the contents of /index.html file with a 200 OK status.
run_worker_first with route patterns configuration example
Example wrangler.json configuration with run_worker_first set to an array of route patterns: ```json { "name": "my-worker", "compatibility_date": "$today", "main": "./worker/index.ts", "assets": { "directory": "./dist/", "not_found_handling": "single-page-application", "binding": "ASSETS", "run_worker_first": ["/oauth/callback"] } } ``` This configuration causes the Worker script to run first only for the /oauth/callback path, while other requests follow the default asset-first behavior.
assets.run_worker_first configuration setting
The assets.run_worker_first setting controls when your Worker script runs relative to static asset serving. It can be set to true to run the Worker before all requests, or set to an array of route patterns to run the Worker first only for specific routes.
run_worker_first true configuration example
Example wrangler.json configuration with run_worker_first set to true: ```json { "name": "my-worker", "compatibility_date": "$today", "main": "./worker/index.ts", "assets": { "directory": "./dist/", "binding": "ASSETS", "run_worker_first": true } } ``` This configuration causes the Worker script to run before every request, allowing you to perform checks like authentication, logging, or asset transformation before static assets are served.
logUnhandledRejections option removed in Miniflare v3
The logUnhandledRejections option has been removed from Miniflare v3. Unhandled rejections can now be handled in Workers using addEventListener('unhandledrejection') instead.
cfFetch renamed to cf in Miniflare v3
In Miniflare v3, cfFetch has been renamed to cf. It accepts a boolean, a string (as before), or an object to use as the cf object for incoming requests.
packagePath option removed in Miniflare v3
Miniflare v3 no longer loads script paths from package.json files. Use the scriptPath option to specify your script instead.
globals option removed in Miniflare v3
Injecting arbitrary globals is not supported by workerd in Miniflare v3. If using a service worker, bindings will be injected as globals, but these must be JSON-serialisable.
crons option removed in Miniflare v3
The crons option has been removed from Miniflare v3 because workerd does not support triggering scheduled events yet. This option may be added back in a future release.
mounts option removed in Miniflare v3, use workers instead
Miniflare v3 no longer has the concept of parent and child Workers or mounts. Instead, all Workers can be defined at the same level using the new workers option, which accepts an array of worker configurations. Each worker configuration can have its own bindings and script. Service bindings can be used to communicate between workers, and custom service bindings can be defined as async functions with access to external variables.
metaProvider option removed in Miniflare v3
The metaProvider option has been removed in Miniflare v3. The cf object and X-Forwarded-Proto/X-Real-IP headers can be specified when calling dispatchFetch() instead. A default cf object can be specified using the new cf option.
durableObjectAlarms always enabled in Miniflare v3
Miniflare v3 always enables Durable Object alarms. The durableObjectAlarms option has been removed.
globalAsyncIO, globalTimers, globalRandom options removed in Miniflare v3
The globalAsyncIO, globalTimers, and globalRandom options have been removed from Miniflare v3 because workerd cannot support these options without fundamental changes.
actualTime always returns current time in Miniflare v3
Miniflare v3 always returns the current time. The actualTime option has been removed.
Workers support npm packages
All projects deployed to Cloudflare Workers support npm packages. You can install and use npm packages in Workers projects just like in standard Node.js applications, using npm install to add dependencies to package.json.
Modern JavaScript tooling in Workers
Cloudflare Workers supports modern JavaScript features including ES modules, npm packages, and async/await functions.
Create Turso database token with no expiration
To create a long-lived authentication token for your Worker to use, run 'turso db tokens create <DATABASE_NAME> -e none'. The -e none flag sets no expiration on the token.