dotfiles/.agents/skills/cloudflare-deploy/references/static-assets/configuration.md

Configuration

Basic Setup

Minimal configuration requires only assets.directory:

{
  "name": "my-worker",
  "compatibility_date": "2025-01-01",  // Use current date for new projects
  "assets": {
    "directory": "./dist"
  }
}

Full Configuration Options

{
  "name": "my-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01",
  "assets": {
    "directory": "./dist",
    "binding": "ASSETS",
    "not_found_handling": "single-page-application",
    "html_handling": "auto-trailing-slash",
    "run_worker_first": ["/api/*", "!/api/docs/*"]
  }
}

Configuration keys:

• directory (string, required): Path to assets folder (e.g. ./dist, ./public, ./build)
• binding (string, optional): Name to access assets in Worker code (e.g. env.ASSETS). Default: "ASSETS"
• not_found_handling (string, optional): Behavior when asset not found
  • "single-page-application": Serve /index.html for non-asset paths (default for SPAs)
  • "404-page": Serve /404.html if present, otherwise 404
  • "none": Return 404 for missing assets
• html_handling (string, optional): URL trailing slash behavior
• run_worker_first (boolean | string[], optional): Routes that invoke Worker before checking assets

not_found_handling Modes

Mode	Behavior	Use Case
"single-page-application"	Serve /index.html for non-asset requests	React, Vue, Angular SPAs
"404-page"	Serve /404.html if exists, else 404	Static sites with custom error page
"none"	Return 404 for missing assets	API-first or custom routing

html_handling Modes

Controls trailing slash behavior for HTML files:

Mode	/page	/page/	Use Case
"auto-trailing-slash"	Redirect to /page/ if /page/index.html exists	Serve /page/index.html	Default, SEO-friendly
"force-trailing-slash"	Always redirect to /page/	Serve if exists	Consistent trailing slashes
"drop-trailing-slash"	Serve if exists	Redirect to /page	Cleaner URLs
"none"	No modification	No modification	Custom routing logic

Default: "auto-trailing-slash"

run_worker_first Configuration

Controls which requests invoke Worker before checking assets.

Boolean syntax:

{
  "assets": {
    "run_worker_first": true  // ALL requests invoke Worker
  }
}

Array syntax (recommended):

{
  "assets": {
    "run_worker_first": [
      "/api/*",           // Positive pattern: match API routes
      "/admin/*",         // Match admin routes
      "!/admin/assets/*"  // Negative pattern: exclude admin assets
    ]
  }
}

Pattern rules:

• Glob patterns: * (any chars), ** (any path segments)
• Negative patterns: Prefix with ! to exclude
• Precedence: Negative patterns override positive patterns
• Default: false (assets served directly)

Decision guidance:

• Use true for API-first apps (few static assets)
• Use array patterns for hybrid apps (APIs + static assets)
• Use false for static-first sites (minimal dynamic routes)

.assetsignore File

Exclude files from upload using .assetsignore (same syntax as .gitignore):

# .assetsignore
_worker.js
*.map
*.md
node_modules/
.git/

Common patterns:

• _worker.js - Exclude Worker code from assets
• *.map - Exclude source maps
• *.md - Exclude markdown files
• Development artifacts

Vite Plugin Integration

For Vite-based projects, use @cloudflare/vite-plugin:

// vite.config.ts
import { defineConfig } from 'vite';
import { cloudflare } from '@cloudflare/vite-plugin';

export default defineConfig({
  plugins: [
    cloudflare({
      assets: {
        directory: './dist',
        binding: 'ASSETS'
      }
    })
  ]
});

Features:

• Automatic asset detection during dev
• Hot module replacement for assets
• Production build integration
• Requires: Wrangler 4.0.0+, @cloudflare/vite-plugin 1.0.0+

Key Compatibility Dates

Date	Feature	Impact
2025-04-01	Navigation request optimization	SPAs skip Worker for navigation, reducing costs

Use current date for new projects. See Compatibility Dates for full list.

Environment-Specific Configuration

Use wrangler.jsonc environments for different configs:

{
  "name": "my-worker",
  "assets": { "directory": "./dist" },
  "env": {
    "staging": {
      "assets": {
        "not_found_handling": "404-page"
      }
    },
    "production": {
      "assets": {
        "not_found_handling": "single-page-application"
      }
    }
  }
}

Deploy with: wrangler deploy --env staging