1## Configuration
2 
3### Basic Setup
4 
5Minimal configuration requires only `assets.directory`:
6 
7```jsonc
8{
9  "name": "my-worker",
10  "compatibility_date": "2025-01-01",  // Use current date for new projects
11  "assets": {
12    "directory": "./dist"
13  }
14}
15```
16 
17### Full Configuration Options
18 
19```jsonc
20{
21  "name": "my-worker",
22  "main": "src/index.ts",
23  "compatibility_date": "2025-01-01",
24  "assets": {
25    "directory": "./dist",
26    "binding": "ASSETS",
27    "not_found_handling": "single-page-application",
28    "html_handling": "auto-trailing-slash",
29    "run_worker_first": ["/api/*", "!/api/docs/*"]
30  }
31}
32```
33 
34**Configuration keys:**
35 
36- `directory` (string, required): Path to assets folder (e.g. `./dist`, `./public`, `./build`)
37- `binding` (string, optional): Name to access assets in Worker code (e.g. `env.ASSETS`). Default: `"ASSETS"`
38- `not_found_handling` (string, optional): Behavior when asset not found
39  - `"single-page-application"`: Serve `/index.html` for non-asset paths (default for SPAs)
40  - `"404-page"`: Serve `/404.html` if present, otherwise 404
41  - `"none"`: Return 404 for missing assets
42- `html_handling` (string, optional): URL trailing slash behavior
43- `run_worker_first` (boolean | string[], optional): Routes that invoke Worker before checking assets
44 
45### not_found_handling Modes
46 
47| Mode | Behavior | Use Case |
48|------|----------|----------|
49| `"single-page-application"` | Serve `/index.html` for non-asset requests | React, Vue, Angular SPAs |
50| `"404-page"` | Serve `/404.html` if exists, else 404 | Static sites with custom error page |
51| `"none"` | Return 404 for missing assets | API-first or custom routing |
52 
53### html_handling Modes
54 
55Controls trailing slash behavior for HTML files:
56 
57| Mode | `/page` | `/page/` | Use Case |
58|------|---------|----------|----------|
59| `"auto-trailing-slash"` | Redirect to `/page/` if `/page/index.html` exists | Serve `/page/index.html` | Default, SEO-friendly |
60| `"force-trailing-slash"` | Always redirect to `/page/` | Serve if exists | Consistent trailing slashes |
61| `"drop-trailing-slash"` | Serve if exists | Redirect to `/page` | Cleaner URLs |
62| `"none"` | No modification | No modification | Custom routing logic |
63 
64**Default:** `"auto-trailing-slash"`
65 
66### run_worker_first Configuration
67 
68Controls which requests invoke Worker before checking assets.
69 
70**Boolean syntax:**
71 
72```jsonc
73{
74  "assets": {
75    "run_worker_first": true  // ALL requests invoke Worker
76  }
77}
78```
79 
80**Array syntax (recommended):**
81 
82```jsonc
83{
84  "assets": {
85    "run_worker_first": [
86      "/api/*",           // Positive pattern: match API routes
87      "/admin/*",         // Match admin routes
88      "!/admin/assets/*"  // Negative pattern: exclude admin assets
89    ]
90  }
91}
92```
93 
94**Pattern rules:**
95 
96- Glob patterns: `*` (any chars), `**` (any path segments)
97- Negative patterns: Prefix with `!` to exclude
98- Precedence: Negative patterns override positive patterns
99- Default: `false` (assets served directly)
100 
101**Decision guidance:**
102 
103- Use `true` for API-first apps (few static assets)
104- Use array patterns for hybrid apps (APIs + static assets)
105- Use `false` for static-first sites (minimal dynamic routes)
106 
107### .assetsignore File
108 
109Exclude files from upload using `.assetsignore` (same syntax as `.gitignore`):
110 
111```
112# .assetsignore
113_worker.js
114*.map
115*.md
116node_modules/
117.git/
118```
119 
120**Common patterns:**
121 
122- `_worker.js` - Exclude Worker code from assets
123- `*.map` - Exclude source maps
124- `*.md` - Exclude markdown files
125- Development artifacts
126 
127### Vite Plugin Integration
128 
129For Vite-based projects, use `@cloudflare/vite-plugin`:
130 
131```typescript
132// vite.config.ts
133import { defineConfig } from 'vite';
134import { cloudflare } from '@cloudflare/vite-plugin';
135 
136export default defineConfig({
137  plugins: [
138    cloudflare({
139      assets: {
140        directory: './dist',
141        binding: 'ASSETS'
142      }
143    })
144  ]
145});
146```
147 
148**Features:**
149 
150- Automatic asset detection during dev
151- Hot module replacement for assets
152- Production build integration
153- Requires: Wrangler 4.0.0+, `@cloudflare/vite-plugin` 1.0.0+
154 
155### Key Compatibility Dates
156 
157| Date | Feature | Impact |
158|------|---------|--------|
159| `2025-04-01` | Navigation request optimization | SPAs skip Worker for navigation, reducing costs |
160 
161Use current date for new projects. See [Compatibility Dates](https://developers.cloudflare.com/workers/configuration/compatibility-dates/) for full list.
162 
163### Environment-Specific Configuration
164 
165Use `wrangler.jsonc` environments for different configs:
166 
167```jsonc
168{
169  "name": "my-worker",
170  "assets": { "directory": "./dist" },
171  "env": {
172    "staging": {
173      "assets": {
174        "not_found_handling": "404-page"
175      }
176    },
177    "production": {
178      "assets": {
179        "not_found_handling": "single-page-application"
180      }
181    }
182  }
183}
184```
185 
186Deploy with: `wrangler deploy --env staging`
187