How to Deploy Remix to Cloudflare: Step-by-Step Guide

To deploy a Remix app to Cloudflare Workers, use the Remix Cloudflare adapter by installing @remix-run/cloudflare and configure your remix.config.js for Cloudflare. Then build your app and publish it using wrangler, Cloudflare's CLI tool.

Syntax

Deploying Remix to Cloudflare involves these main parts:

• Install Cloudflare adapter: Adds support for Cloudflare Workers.
• Configure remix.config.js: Set the adapter to Cloudflare and specify build options.
• Build the app: Compile Remix code for Cloudflare environment.
• Use Wrangler: Cloudflare's CLI to publish your app.

javascript

npm install @remix-run/cloudflare wrangler

// remix.config.js
/** @type {import('@remix-run/dev').AppConfig} */
module.exports = {
  serverBuildTarget: 'cloudflare-workers',
  server: './server.js',
  appDirectory: 'app',
  assetsBuildDirectory: 'public/build',
  publicPath: '/build/',
  // Use Cloudflare adapter
  serverBuildPath: 'build/index.js',
  devServerPort: 8002
};

Example

This example shows a simple Remix app configured for Cloudflare Workers deployment. It includes the wrangler.toml config and a basic server.js entry point.

javascript

// wrangler.toml
name = "my-remix-app"
type = "javascript"
account_id = "your-cloudflare-account-id"
workers_dev = true
route = ""
zone_id = ""

// server.js
import { createRequestHandler } from '@remix-run/cloudflare';
import * as build from './build/index.js';

addEventListener('fetch', event => {
  event.respondWith(createRequestHandler({
    build,
    getLoadContext() {
      return {};
    }
  })(event.request));
});

Output

Your Remix app runs on Cloudflare Workers and responds to HTTP requests.

Common Pitfalls

Common mistakes when deploying Remix to Cloudflare include:

• Not installing the @remix-run/cloudflare adapter, causing build errors.
• Misconfiguring wrangler.toml with wrong account or zone IDs.
• Forgetting to build the app before publishing.
• Using Node.js-specific APIs that Cloudflare Workers do not support.

Always test your app locally with wrangler dev before publishing.

javascript

// Wrong: Missing Cloudflare adapter in remix.config.js
module.exports = {
  serverBuildTarget: 'node', // wrong target for Cloudflare
};

// Right: Use Cloudflare adapter
module.exports = {
  serverBuildTarget: 'cloudflare-workers',
};

Quick Reference

Steps to deploy Remix to Cloudflare:

1. Install dependencies: npm install @remix-run/cloudflare wrangler
2. Configure remix.config.js with serverBuildTarget: 'cloudflare-workers'
3. Create wrangler.toml with your Cloudflare account info
4. Build your app: npm run build
5. Publish with Wrangler: wrangler publish

Key Takeaways

Use the @remix-run/cloudflare adapter to target Cloudflare Workers.

Configure remix.config.js with serverBuildTarget set to 'cloudflare-workers'.

Use Wrangler CLI to build and publish your Remix app to Cloudflare.

Test your app locally with wrangler dev before deploying.

Avoid Node.js-only APIs; Cloudflare Workers use a different runtime.