Custom domains vs routes for Worker routing
Workers support two routing mechanisms: Custom domains make the Worker the origin (Cloudflare creates DNS records and SSL certificates automatically); use this when your Worker handles all traffic for a hostname. Routes make the Worker run in front of an existing origin server (you must have a Cloudflare proxied DNS record for the hostname first). The most common mistake with routes is missing the DNS record. Without a proxied DNS record, requests return ERR_NAME_NOT_RESOLVED and never reach your Worker. If you do not have a real origin, add a proxied AAAA record pointing to 100:: as a placeholder.
Production branch triggers Workers build on every push
When you connect a git repository to Workers, commits made on the production git branch will produce a Workers Build. Every push event made to the production branch will trigger a build and execute the build command, followed by the deploy command.
Non-production branch builds enable preview URLs and pull request comments
To take advantage of preview URLs and pull request comments, you can enable non-production branch builds in order to trigger a build on all branches of your repository.
Change production branch in Workers Settings
To change the production branch of your project, go to Overview, select your Workers project, then go to Settings > Build > Branch control. Workers will default to the default branch of your git repository, but this can be changed in the dropdown.
Enable non-production branch builds in Branch control
To enable or disable non-production branch builds, go to Overview, select your Workers project, then go to Settings > Build > Branch control. The checkbox 'Builds for non-production branches' allows you to enable or disable builds for non-production branches.
Non-production branch builds execute build and non-production deploy commands
When non-production branch builds are enabled, every push event made to a non-production branch will trigger a build and execute the build command, followed by the non-production branch deploy command.
ROUTES configuration structure
The router worker uses a ROUTES environment variable to determine which microfrontend handles each path. Routes are matched by specificity with longer paths taking precedence. Each route requires: path (the mount path for the microfrontend, must be distinct from other routes), binding (the name of the service binding in the Wrangler configuration file), and preload (optional, whether to prefetch this microfrontend for faster navigation). Example structure: {"routes": [{"path": "/app-a", "binding": "MICROFRONTEND_A", "preload": true}, {"path": "/app-b", "binding": "MICROFRONTEND_B", "preload": true}, {"path": "/", "binding": "MICROFRONTEND_HOME"}], "smoothTransitions": true}
Path matching patterns in routes
The router includes path matching logic that supports static paths (e.g., {"path": "/dashboard"}), dynamic parameters (e.g., {"path": "/users/:id"}), wildcard matching for zero or more segments (e.g., {"path": "/docs/:path*"}), and required segments for one or more segments (e.g., {"path": "/api/:path+"}).
SPA asset routing configuration
Set assets.not_found_handling to single-page-application in wrangler.jsonc so that routes handled by the React SPA do not go to the Worker and are thus free to serve.
SvelteKit deployment targets
SvelteKit projects can be deployed to a *.workers.dev subdomain or a Custom Domain. Deployment can be done from your own machine or from any CI/CD system, including Cloudflare's own.
Wrangler configuration for Vue SPA routing
For Vue single-page applications, set assets.not_found_handling to 'single-page-application' in wrangler.jsonc. This ensures routes handled by the Vue SPA do not go to the Worker and are thus free.
Route specificity with trailing wildcard behaves unexpectedly
When defining route specificity with a trailing `/*` in your pattern, it may not act as expected. When two Workers are deployed to the same zone, one with route `example.com/images/*` and another with `example.com/images*`, all requests including `example.com/images/hello` will be resolved to the `example.com/images*` route instead of the more specific `example.com/images/*` route.
Static assets routing and configuration
Static assets on Workers are configured and routed using the Routing configuration documentation. Assets have their own binding available for full-stack applications.
Default static assets routing behavior
By default, if a requested URL matches a file in the static assets directory, that file is served without invoking Worker code. If no matching asset is found and a Worker script is present, the request is processed by the Worker. If no Worker script is present, a 404 Not Found response is returned.
run_worker_first option for routing
The `run_worker_first` option can be set to `true` to invoke the Worker script for all requests before serving static assets, or configured as an array of route patterns for selective Worker-script-first routing. Route patterns can use wildcards (e.g., '/api/*') and exclusions (e.g., '!/api/docs/*').
Workers Custom Domains requirement
Workers Custom Domains only supports domains that are configured as zones on your Cloudflare account. A zone refers to a domain like example.com that Cloudflare manages for you, including its DNS and traffic.
Advanced routing for Workers static assets
Advanced routing options are available for configuring static assets served by Cloudflare Workers, including custom path handling and fallback behavior.
Files outside configured static asset path are not served
Files located outside the configured path for static assets will not be served by the Worker, unless they are designated for not_found_handling for Single Page Applications or custom 404 pages. For example, a home.html file in the root of the asset directory will not be served when requesting example.com/blog/home. These files can still be manually fetched using the static assets binding.
Serving static assets from a subdirectory
To serve static assets from a subdirectory on your domain, the assets must be organized in a directory structure that mirrors the desired path. For example, to serve assets from example.com/blog/*, create a blog directory in your asset directory. Configure the Wrangler configuration file with a route parameter specifying the desired path (e.g., 'route': 'example.com/blog/*') and set the assets directory to the parent directory containing the subdirectory (e.g., 'directory': 'dist').
Static assets path routing example
To serve assets at example.com/blog/*, create a dist directory with a blog subdirectory containing your files. Requests to example.com/blog/ will serve dist/blog/index.html, and requests to example.com/blog/posts/post1 will serve dist/blog/posts/post1.html. This requires the Wrangler configuration route to be set to 'example.com/blog/*' and assets.directory to be 'dist'.
Static assets routing configurations
Cloudflare Workers allows configuring different routing architectures for static assets, including asset-only and Worker-first modes. These configurations determine how requests are routed between static asset handlers and Worker code.
SPA default routing behavior with Sec-Fetch-Mode header
When single-page-application mode is configured, Cloudflare automatically serves /index.html for navigation requests (those with Sec-Fetch-Mode: navigate headers) which do not match any other asset.
SPA advanced routing with run_worker_first
Advanced routing control for SPAs is available through the run_worker_first configuration option, which accepts an array of route patterns. This approach disables automatic Sec-Fetch-Mode: navigate detection and gives explicit control over which requests should be handled by the Worker script versus served as static assets. Advanced routing control requires Wrangler v4.20.0 and above or Cloudflare Vite plugin v1.7.0 and above.
Miniflare routing with routes API
Routing can be enabled in Miniflare by specifying `routes` via the API using the standard route syntax. Port numbers are ignored when matching routes. Multiple routes can be specified as an array.
Route pattern examples: http://127.0.0.1/api* and api.mf/*
Routes can use patterns like 'http://127.0.0.1/api*' for path-based matching or 'api.mf/*' for hostname-based matching. The standard route syntax for path matching with wildcards applies.
Configure routes in Wrangler for custom domain
To configure a route in the Wrangler configuration file, add a routes array to the environment. Each route object contains a pattern field and a zone_id field. Example: { "routes": [{ "pattern": "example.com/about", "zone_id": "<YOUR_ZONE_ID>" }] }. If you have specified your zone ID in the environment of your Wrangler configuration file, you will not need to write it again in object form.
Configure subdomains in Wrangler configuration
To configure a subdomain in the Wrangler configuration file, add a routes array with an object containing a pattern field set to the subdomain (e.g., "subdomain.example.com") and a custom_domain field set to true. Example: { "routes": [{ "pattern": "subdomain.example.com", "custom_domain": true }] }.
Explicit routing with run_worker_first configuration
Use the assets.run_worker_first configuration with an array of route patterns to explicitly define which routes invoke the Worker, opting out of implicit routing based on the Sec-Fetch-Mode header. For example, run_worker_first: ['/api/*'] makes the Worker handle all API routes.