Compute
Static assets
Serve a Worker's static assets on OpenOrange from local files, routed like Cloudflare's router and asset Workers.
Orange serves the files in your Worker’s assets directory straight from
disk, and routes each request to a file or to your Worker as Cloudflare does.
Assets are files in your project, so they deploy with it and there is nothing
to migrate.
Quickstart
This serves a single-page app from public/ and sends /api/* to your
Worker.
-
Point assets at a directory
Add
assetstowrangler.jsonc.{ "name": "assets-spa", "main": "src/index.ts", "compatibility_date": "2026-09-03", "assets": { "directory": "./public", // Unknown paths serve index.html, so the browser app can route them. "not_found_handling": "single-page-application", // API requests always reach the Worker, even when no asset matches. "run_worker_first": ["/api/*"] } } -
Write the Worker for the API
Only requests that match
run_worker_firstreach this Worker. Your files answer everything else.export default { async fetch(request): Promise<Response> { const { pathname } = new URL(request.url); if (pathname === "/api/hello") { return Response.json({ message: "Hello from the Worker" }); } return Response.json({ error: `No API route for ${pathname}` }, { status: 404 }); }, } satisfies ExportedHandler; -
Run it
orange devserves the Worker on port 8787.orange devOpen
http://localhost:8787/aboutin a browser: the app’sindex.htmlloads. An API route that does not exist gets the Worker’s 404, neverindex.html.curl localhost:8787/api/hello {"message":"Hello from the Worker"} curl localhost:8787/api/missing # 404 {"error":"No API route for /api/missing"}
How it works
- A request whose path matches
run_worker_firstgoes to your Worker. - Any other request gets its matching file. When no file matches,
not_found_handlingor your Worker answers. - Orange reads the directory on each request, so a new or changed file serves without a restart.
AI context Compatibility, limits and details
Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.
Compatibility
Status: Partial. Orange serves the assets directory from local files.
| Feature | Status | Notes |
|---|---|---|
html_handling | Supported | All four modes, with their 307 redirects. |
not_found_handling | Supported | single-page-application, and 404-page with the nearest 404.html. |
run_worker_first | Supported | true, or patterns with * and !/ exclusions. |
assets.binding and env.ASSETS.fetch() | Supported | Follows redirects like any Fetcher. |
| Assets-only Workers | Supported | A project without main. |
.assetsignore | Supported | .gitignore syntax. |
ETag, If-None-Match, and Cache-Control | Supported | |
_headers and _redirects | Not supported | |
Workers Sites (site) | Not supported | |
The router’s /_next/image and /_image content-type checks | Not supported |
One difference reaches most projects:
_headersand_redirectshave no effect, andorange devwarns at startup when the directory has one. Set those headers and redirects in the Worker, and list their paths inrun_worker_first, so the Worker sees the requests before assets answer them.
Limits
| What | Limit | What happens over it |
|---|---|---|
| Size of one file | No limit set by Orange. Cloudflare’s is 25 MiB. | |
| Number of files | No limit set by Orange. Cloudflare’s is 100,000. | |
| Methods for an asset path | GET and HEAD | Assets answer 405 Method Not Allowed. |
What Orange reads
Orange reads assets as wrangler dev does, with these differences:
| In your project | On Orange |
|---|---|
assets.directory outside the project | orange dev serves it. orange deploy stops with orange deploy copies the project directory only, so assets must be inside it: <directory>, because it copies only the project directory. |
site, legacy_assets, or pages_build_output_dir | The configuration does not load: Unsupported Wrangler configuration: <keys>. |
Routing
Orange routes each request like Cloudflare’s router Worker, then serves it like the asset Worker, from the files on disk:
- A path that matches a
!/pattern inrun_worker_firstgoes to assets. - A path that matches another pattern, or any path with
run_worker_first: true, goes to the Worker. - Otherwise assets answer when a file matches, and the Worker runs when none does. An assets-only Worker serves every request from assets.
- A pattern matches the whole path, and
*matches any characters, including/. orange devandorange serveboth serve assets.
Configuration reference
directory resolves against the configuration file.
| Key | Default | Values |
|---|---|---|
directory | Required | A path, resolved against the configuration file |
binding | None | The name of env.<binding> |
html_handling | auto-trailing-slash | auto-trailing-slash, force-trailing-slash, drop-trailing-slash, none |
not_found_handling | none | single-page-application, 404-page, none |
run_worker_first | None | true, false, or an array of patterns |
Errors that stop config load, with Wrangler’s text where Wrangler has one:
| Configuration | Error message |
|---|---|
assets that is not an object | assets must be an object |
No directory | The `assets` property in your configuration is missing the required `directory` property. |
An empty directory | The assets directory cannot be an empty string. |
An unknown html_handling | assets.html_handling must be one of auto-trailing-slash, drop-trailing-slash, force-trailing-slash, none |
An unknown not_found_handling | assets.not_found_handling must be one of 404-page, none, single-page-application |
run_worker_first that is not a boolean or an array | assets.run_worker_first must be a boolean or an array of strings |
An empty run_worker_first array | No `run_worker_first` rules were provided; must provide at least 1 rule. |
A pattern that does not start with / or !/ | Invalid routes in `run_worker_first`: and a line for each, such as 'api/*': rules must start with '/' or '!/' or '!api': negative rules must start with '!/' |
Only !/ patterns | Only negative `run_worker_first` rules were provided; must provide at least 1 non-negative rule |
binding without main | Cannot use assets with a binding in an assets-only Worker. |
run_worker_first without main | Cannot set run_worker_first without a Worker script. |
run_worker_first: truewithoutbindingloads with the warningrun_worker_first=true set without an assets binding. Every request runs the Worker, which cannot fetch assets without assets.binding.orange devchecks the directory after the custom build inbuild.command. A missing directory stops it withThe directory specified by the "assets.directory" field in your configuration file does not exist:, and a file stops it withThe path specified by the "assets.directory" field in your configuration file doesn't point to a directory:.- The warning for
_headersisopen-orange does not apply the assets _headers file yet, so its rules have no effect._redirectsgets the same warning. - A configuration with neither
mainnorassetsfails withWrangler configuration must resolve a Worker entrypoint. - The compatibility flags
assets_navigation_prefers_asset_servingandassets_navigation_has_no_effectapply, so Orange does not warn about them. orange migrate prepareadds/__migrate/*and/__migrate-d1/*torun_worker_firstinwrangler.migrate.jsonc, so the migrator’s routes reach the Worker before assets. Arun_worker_first: truestays as it is. See Migrate from Cloudflare.
HTML handling
The handler is a port of Cloudflare’s asset Worker. It redirects with 307
only when nothing exists at the destination and the destination would serve
the same file. The query string is kept.
| Mode | /about.html serves at | /blog/index.html serves at |
|---|---|---|
auto-trailing-slash | /about | /blog/ |
force-trailing-slash | /about/ | /blog/ |
drop-trailing-slash | /about | /blog |
none | /about.html only | /blog/index.html only |
- Paths are decoded before the lookup, so non-ASCII and optionally encoded
characters match. A request for another spelling of the canonical path gets
a
307to it. - Under
drop-trailing-slash, the root keeps its slash. - With both
/foo.htmland/foo/index.html,force-trailing-slashkeeps/foo.htmlat its own path, anddrop-trailing-slashkeeps/foo/index.htmlat its own path.
Not-found handling
single-page-applicationserves/index.htmlwith200.404-pageserves the nearest404.htmlin the path’s directory or a parent directory, with404.noneanswers404with no body, or runs the Worker.- For a Worker with
mainand norun_worker_firstpatterns, the router appliesnot_found_handlingonly to a request withSec-Fetch-Mode: navigate, and only whileassets_navigation_prefers_asset_servingis on, as on Cloudflare. That flag is on from the compatibility date 2025-04-01, andassets_navigation_has_no_effectturns it off. Otherwise a missing path runs the Worker, so afetch()from your app to a missing path reaches the Worker. - With
run_worker_firstpatterns, in an assets-only Worker, and inenv.ASSETS.fetch(),not_found_handlingapplies to every request.
Responses
ETagis a strong ETag of 32 hex characters, from a SHA-256 of the file path and its modification time, as inwrangler dev.If-None-Matchwith it, strong orW/, gets304.Content-Typecomes from the file extension. Text types get; charset=utf-8.Cache-Control: public, max-age=0, must-revalidate, unless the request hasAuthorizationorRange.CF-Cache-Status: HITon every asset response, as for local reads inwrangler dev.- A request with
Rangegets the whole file with200. HEADgets the headers and no body..assetsignore,_headers, and_redirectsare never served. A path with a.or..segment matches no asset.
Deviations
These add to the differences under Compatibility and Limits.
- Orange reads the directory on each request.
wrangler devbuilds its view of the directory when it starts.
Conformance
tests/bindings/assets.test.tsruns a realorange dev. It covers content types,ETagand304, the HTML redirects,run_worker_firstpatterns,env.ASSETS.fetch()and its redirects, a file added whileorange devruns, the single-page app fallback for navigations only, an assets-only project withdrop-trailing-slashand the nearest404.html, and a missing directory.- The quickstart builds
tests/fixtures/examples/assets-spa, andtests/examples/runnable-examples.test.tsruns it end to end. - The asset Worker and router Worker tests from workers-sdk are not part of the conformance corpus.
- The compatibility matrix lists the
assetsconfiguration as partial and theassetsbinding as supported.