cloudflare-static-assets

Cloudflare Static Assets

Overview

This skill provides a robust solution for handling static assets in React Router applications deployed to Cloudflare Workers. It addresses the common issue where files in the public directory work in development (Vite) but fail with 404 errors in production due to differences in how assets are served.

Problem Context

Development vs Production Mismatch:

• Development (Vite): Files in public/ are automatically served at the root path
• Production (Cloudflare Workers): Static files need to be configured separately as Static Assets

This causes code like fetch('/data/config.json') to work locally but fail with 404 in production.

Solution: Configuration + Utility Functions

Step 1: Configure wrangler.jsonc

Enable Static Assets by adding the assets configuration:

{
  "compatibility_date": "2024-11-18",
  "assets": {
    "directory": "./public",
    "binding": "ASSETS"
  }
}

Step 2: Create Utility Functions

Create app/lib/utils/static-assets.ts (or similar path) with the following implementation:

/**
 * Static Assets Utility
 * 
 * Provides unified access to static files across different environments:
 * - Development (Vite): Uses standard fetch()
 * - Production (Cloudflare Workers): Uses ASSETS binding
 * - Build time (Node.js): Falls back to file system access
 */

interface CloudflareContext {
  cloudflare?: {
    env: Env;
  };
}

/**
 * Determines if we have access to Cloudflare Workers ASSETS binding
 */
function hasAssetsBinding(context?: CloudflareContext): boolean {
  return !!context?.cloudflare?.env?.ASSETS;
}

/**
 * Fetches a static asset with automatic fallback between ASSETS and standard fetch
 */
export async function fetchStaticAsset(
  path: string,
  context?: CloudflareContext,
  request?: Request,
): Promise<Response> {
  const normalizedPath = path.startsWith("/") ? path : `/${path}`;

  // Try Static Assets first if available
  if (hasAssetsBinding(context) && context?.cloudflare?.env?.ASSETS) {
    try {
      const assetUrl = new URL(normalizedPath, "https://example.com");
      const assetRequest = new Request(assetUrl.toString());
      const response = await context.cloudflare.env.ASSETS.fetch(assetRequest);

      if (response.ok) return response;

      // Log fallback only in development
      if (typeof process !== "undefined" && process.env.NODE_ENV === "development") {
        console.warn(
          `[Static Assets] Failed for ${normalizedPath} (${response.status}), using fallback`
        );
      }
    } catch (error) {
      // Log errors only in development
      if (typeof process !== "undefined" && process.env.NODE_ENV === "development") {
        console.warn(`[Static Assets] Error for ${normalizedPath}:`, error);
      }
    }
  }

  // Fallback: Use standard fetch
  let url = normalizedPath;
  if (request) {
    const requestUrl = new URL(request.url);
    url = `${requestUrl.origin}${normalizedPath}`;
  }

  const response = await fetch(url);
  if (!response.ok) {
    throw new Error(
      `Static asset not found: ${normalizedPath} (${response.status})`
    );
  }

  return response;
}

/**
 * Fetches and parses a JSON static asset
 */
export async function fetchStaticJSON<T>(
  path: string,
  context?: CloudflareContext,
  request?: Request,
): Promise<T> {
  try {
    const response = await fetchStaticAsset(path, context, request);
    const json = await response.json();
    return json as T;
  } catch (error) {
    // Log detailed errors only in development
    if (typeof process !== "undefined" && process.env.NODE_ENV === "development") {
      console.error(`Failed to fetch static JSON ${path}:`, error);
    }
    throw new Error(`Failed to load JSON asset: ${path}`);
  }
}

/**
 * Fetches a text static asset
 */
export async function fetchStaticText(
  path: string,
  context?: CloudflareContext,
  request?: Request,
): Promise<string> {
  try {
    const response = await fetchStaticAsset(path, context, request);
    const text = await response.text();
    return text;
  } catch (error) {
    // Log detailed errors only in development
    if (typeof process !== "undefined" && process.env.NODE_ENV === "development") {
      console.error(`Failed to fetch static text ${path}:`, error);
    }
    throw new Error(`Failed to load text asset: ${path}`);
  }
}