Configure and use Cloudflare Static Assets with React Router, ensuring compatibility across development and production environments with automatic fallback handling. Use when deploying React Router applications to Cloudflare Workers that need to access files from the public directory.
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.
Development vs Production Mismatch:
public/ are automatically served at the root pathThis causes code like fetch('/data/config.json') to work locally but fail with 404 in production.
wrangler.jsoncEnable Static Assets by adding the configuration:
assets{
"compatibility_date": "2024-11-18",
"assets": {
"directory": "./public",
"binding": "ASSETS"
}
}
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}`);
}
}
import type { Route } from './+types/route';
import { fetchStaticJSON } from '~/lib/utils/static-assets';
interface AppConfig {
apiUrl: string;
features: string[];
}
export async function loader({ request, context }: Route.LoaderArgs) {
// Same code works in all environments
const config = await fetchStaticJSON<AppConfig>(
'/data/config.json',
context,
request
);
return { config };
}
export default function ConfigPage({ loaderData }: Route.ComponentProps) {
const { config } = loaderData;
return (
<div>
<h1>App Configuration</h1>
<p>API URL: {config.apiUrl}</p>
<ul>
{config.features.map(feature => (
<li key={feature}>{feature}</li>
))}
</ul>
</div>
);
}
import { fetchStaticText } from '~/lib/utils/static-assets';
export async function loader({ request, context }: Route.LoaderArgs) {
const markdown = await fetchStaticText(
'/content/about.md',
context,
request
);
return { markdown };
}
public directoryproject/
├── public/
│ ├── data/
│ │ └── config.json
│ ├── content/
│ │ └── about.md
│ └── images/
│ └── logo.png
├── app/
│ └── lib/
│ └── utils/
│ └── static-assets.ts
└── wrangler.jsonc