AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

cloudflare-deploy

Deploy applications and infrastructure to Cloudflare using Workers, Pages, and related platform services. Use when the user asks to deploy, host, publish, or set up a project on Cloudflare.

Original source
openai
License
Apache-2.0
Pinned revision
49f948faa9258a0c61caceaf225e179651397431

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read openai--cloudflare-deploy at revision 49f948faa9258a0c61caceaf225e179651397431, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 309

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