1## Best Practices
2 
3### 1. Use Selective Worker-First Routing
4 
5Instead of `run_worker_first = true`, use array patterns:
6 
7```jsonc
8{
9  "assets": {
10    "run_worker_first": [
11      "/api/*",           // API routes
12      "/admin/*",         // Admin area
13      "!/admin/assets/*"  // Except admin assets
14    ]
15  }
16}
17```
18 
19**Benefits:**
20- Reduces Worker invocations
21- Lowers costs
22- Improves asset delivery performance
23 
24### 2. Leverage Navigation Request Optimization
25 
26For SPAs, use `compatibility_date = "2025-04-01"` or later:
27 
28```jsonc
29{
30  "compatibility_date": "2025-04-01",
31  "assets": {
32    "not_found_handling": "single-page-application"
33  }
34}
35```
36 
37Navigation requests skip Worker invocation, reducing costs.
38 
39### 3. Type Safety with Bindings
40 
41Always type your environment:
42 
43```typescript
44interface Env {
45  ASSETS: Fetcher;
46}
47```
48 
49## Common Errors
50 
51### "Asset not found"
52 
53**Cause:** Asset not in assets directory, wrong path, or assets not deployed  
54**Solution:** Verify asset exists, check path case-sensitivity, redeploy if needed
55 
56### "Worker not invoked for asset"
57 
58**Cause:** Asset served directly, `run_worker_first` not configured  
59**Solution:** Configure `run_worker_first` patterns to include asset routes (see configuration.md:66-106)
60 
61### "429 Too Many Requests on free tier"
62 
63**Cause:** `run_worker_first` patterns invoke Worker for many requests, hitting free tier limits (100k req/day)  
64**Solution:** Use more selective patterns with negative exclusions, or upgrade to paid plan
65 
66### "Smart Placement increases latency"
67 
68**Cause:** `run_worker_first=true` + Smart Placement routes all requests through single smart-placed location  
69**Solution:** Use selective patterns (array syntax) or disable Smart Placement for asset-heavy apps
70 
71### "CF-Cache-Status header unreliable"
72 
73**Cause:** Header is probabilistically added for privacy reasons  
74**Solution:** Don't rely on `CF-Cache-Status` for critical routing logic. Use other signals (ETag, age).
75 
76### "JWT expired during deployment"
77 
78**Cause:** Large asset deployments exceed JWT token lifetime  
79**Solution:** Update to Wrangler 4.34.0+ (automatic token refresh), or reduce asset count
80 
81### "Cannot use 'assets' with 'site'"
82 
83**Cause:** Legacy `site` config conflicts with new `assets` config  
84**Solution:** Migrate from `site` to `assets` (see configuration.md). Remove `site` key from wrangler.jsonc.
85 
86### "Assets not updating after deployment"
87 
88**Cause:** Browser or CDN cache serving old assets  
89**Solution:** 
90- Hard refresh browser (Cmd+Shift+R / Ctrl+F5)
91- Use cache-busting (hashed filenames)
92- Verify deployment completed: `wrangler tail`
93 
94## Limits
95 
96| Resource/Limit | Free | Paid | Notes |
97|----------------|------|------|-------|
98| Max asset size | 25 MiB | 25 MiB | Per file |
99| Total assets | 20,000 | **100,000** | Requires Wrangler 4.34.0+ (Sep 2025) |
100| Worker invocations | 100k/day | 10M/month | Optimize with `run_worker_first` patterns |
101| Asset storage | Unlimited | Unlimited | Included |
102 
103### Version Requirements
104 
105| Feature | Minimum Wrangler Version |
106|---------|--------------------------|
107| 100k file limit (paid) | 4.34.0 |
108| Vite plugin | 4.0.0 + @cloudflare/vite-plugin 1.0.0 |
109| Navigation optimization | 4.0.0 + compatibility_date: "2025-04-01" |
110 
111## Performance Tips
112 
113### 1. Use Hashed Filenames
114 
115Enable long-term caching with content-hashed filenames:
116 
117```
118app.a3b2c1d4.js
119styles.e5f6g7h8.css
120```
121 
122Most bundlers (Vite, Webpack, Parcel) do this automatically.
123 
124### 2. Minimize Worker Invocations
125 
126Serve assets directly when possible:
127 
128```jsonc
129{
130  "assets": {
131    // Only invoke Worker for dynamic routes
132    "run_worker_first": ["/api/*", "/auth/*"]
133  }
134}
135```
136 
137### 3. Leverage Browser Cache
138 
139Set appropriate `Cache-Control` headers:
140 
141```typescript
142// Versioned assets
143'Cache-Control': 'public, max-age=31536000, immutable'
144 
145// HTML (revalidate often)
146'Cache-Control': 'public, max-age=0, must-revalidate'
147```
148 
149See patterns.md:169-189 for implementation.
150 
151### 4. Use .assetsignore
152 
153Reduce upload time by excluding unnecessary files:
154 
155```
156*.map
157*.md
158.DS_Store
159node_modules/
160```
161 
162See configuration.md:107-126 for details.
163