Skip to content
Compute / Static assets

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.

  1. Point assets at a directory

    Add assets to wrangler.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/*"]
      }
    }
  2. Write the Worker for the API

    Only requests that match run_worker_first reach 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;
  3. Run it

    orange dev serves the Worker on port 8787.

    orange dev

    Open http://localhost:8787/about in a browser: the app’s index.html loads. An API route that does not exist gets the Worker’s 404, never index.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_first goes to your Worker.
  • Any other request gets its matching file. When no file matches, not_found_handling or 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.

FeatureStatusNotes
html_handlingSupportedAll four modes, with their 307 redirects.
not_found_handlingSupportedsingle-page-application, and 404-page with the nearest 404.html.
run_worker_firstSupportedtrue, or patterns with * and !/ exclusions.
assets.binding and env.ASSETS.fetch()SupportedFollows redirects like any Fetcher.
Assets-only WorkersSupportedA project without main.
.assetsignoreSupported.gitignore syntax.
ETag, If-None-Match, and Cache-ControlSupported
_headers and _redirectsNot supported
Workers Sites (site)Not supported
The router’s /_next/image and /_image content-type checksNot supported

One difference reaches most projects:

  • _headers and _redirects have no effect, and orange dev warns at startup when the directory has one. Set those headers and redirects in the Worker, and list their paths in run_worker_first, so the Worker sees the requests before assets answer them.

Limits

WhatLimitWhat happens over it
Size of one fileNo limit set by Orange. Cloudflare’s is 25 MiB.
Number of filesNo limit set by Orange. Cloudflare’s is 100,000.
Methods for an asset pathGET and HEADAssets answer 405 Method Not Allowed.

What Orange reads

Orange reads assets as wrangler dev does, with these differences:

In your projectOn Orange
assets.directory outside the projectorange 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_dirThe 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:

  1. A path that matches a !/ pattern in run_worker_first goes to assets.
  2. A path that matches another pattern, or any path with run_worker_first: true, goes to the Worker.
  3. 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 dev and orange serve both serve assets.

Configuration reference

directory resolves against the configuration file.

KeyDefaultValues
directoryRequiredA path, resolved against the configuration file
bindingNoneThe name of env.<binding>
html_handlingauto-trailing-slashauto-trailing-slash, force-trailing-slash, drop-trailing-slash, none
not_found_handlingnonesingle-page-application, 404-page, none
run_worker_firstNonetrue, false, or an array of patterns

Errors that stop config load, with Wrangler’s text where Wrangler has one:

ConfigurationError message
assets that is not an objectassets must be an object
No directoryThe `assets` property in your configuration is missing the required `directory` property.
An empty directoryThe assets directory cannot be an empty string.
An unknown html_handlingassets.html_handling must be one of auto-trailing-slash, drop-trailing-slash, force-trailing-slash, none
An unknown not_found_handlingassets.not_found_handling must be one of 404-page, none, single-page-application
run_worker_first that is not a boolean or an arrayassets.run_worker_first must be a boolean or an array of strings
An empty run_worker_first arrayNo `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 !/ patternsOnly negative `run_worker_first` rules were provided; must provide at least 1 non-negative rule
binding without mainCannot use assets with a binding in an assets-only Worker.
run_worker_first without mainCannot set run_worker_first without a Worker script.
  • run_worker_first: true without binding loads with the warning run_worker_first=true set without an assets binding. Every request runs the Worker, which cannot fetch assets without assets.binding.
  • orange dev checks the directory after the custom build in build.command. A missing directory stops it with The directory specified by the "assets.directory" field in your configuration file does not exist:, and a file stops it with The path specified by the "assets.directory" field in your configuration file doesn't point to a directory:.
  • The warning for _headers is open-orange does not apply the assets _headers file yet, so its rules have no effect. _redirects gets the same warning.
  • A configuration with neither main nor assets fails with Wrangler configuration must resolve a Worker entrypoint.
  • The compatibility flags assets_navigation_prefers_asset_serving and assets_navigation_has_no_effect apply, so Orange does not warn about them.
  • orange migrate prepare adds /__migrate/* and /__migrate-d1/* to run_worker_first in wrangler.migrate.jsonc, so the migrator’s routes reach the Worker before assets. A run_worker_first: true stays 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 307 to it.
  • Under drop-trailing-slash, the root keeps its slash.
  • With both /foo.html and /foo/index.html, force-trailing-slash keeps /foo.html at its own path, and drop-trailing-slash keeps /foo/index.html at its own path.

Not-found handling

  • single-page-application serves /index.html with 200.
  • 404-page serves the nearest 404.html in the path’s directory or a parent directory, with 404.
  • none answers 404 with no body, or runs the Worker.
  • For a Worker with main and no run_worker_first patterns, the router applies not_found_handling only to a request with Sec-Fetch-Mode: navigate, and only while assets_navigation_prefers_asset_serving is on, as on Cloudflare. That flag is on from the compatibility date 2025-04-01, and assets_navigation_has_no_effect turns it off. Otherwise a missing path runs the Worker, so a fetch() from your app to a missing path reaches the Worker.
  • With run_worker_first patterns, in an assets-only Worker, and in env.ASSETS.fetch(), not_found_handling applies to every request.

Responses

  • ETag is a strong ETag of 32 hex characters, from a SHA-256 of the file path and its modification time, as in wrangler dev. If-None-Match with it, strong or W/, gets 304.
  • Content-Type comes from the file extension. Text types get ; charset=utf-8.
  • Cache-Control: public, max-age=0, must-revalidate, unless the request has Authorization or Range.
  • CF-Cache-Status: HIT on every asset response, as for local reads in wrangler dev.
  • A request with Range gets the whole file with 200.
  • HEAD gets the headers and no body.
  • .assetsignore, _headers, and _redirects are 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 dev builds its view of the directory when it starts.

Conformance

  • tests/bindings/assets.test.ts runs a real orange dev. It covers content types, ETag and 304, the HTML redirects, run_worker_first patterns, env.ASSETS.fetch() and its redirects, a file added while orange dev runs, the single-page app fallback for navigations only, an assets-only project with drop-trailing-slash and the nearest 404.html, and a missing directory.
  • The quickstart builds tests/fixtures/examples/assets-spa, and tests/examples/runnable-examples.test.ts runs 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 assets configuration as partial and the assets binding as supported.