Deploying a Weaverse Theme to Cloudflare Workers

This is a migration, not a supported preset. Weaverse themes (Pilot, Naturelle) ship configured for Shopify Oxygen — the Oxygen Vite plugin, the Oxygen request handler, and Oxygen worker types. There is no Cloudflare plugin, wrangler config, Cloudflare worker entry, or cf-* script in the theme. Everything on this page is something you add yourself.For production storefronts, use Shopify Oxygen. Only take this path if you have a concrete reason to host on Cloudflare, and budget time to validate the result end to end.

What your theme ships with today

Before changing anything, it helps to see exactly what you are migrating away from. In the current Pilot theme:

File	Current state
`vite.config.ts`	Uses `oxygen()` from `@shopify/mini-oxygen/vite` alongside `hydrogen()` and `reactRouter()`
`server.ts`	Module-format `fetch(request, env, executionContext)` handler built on `createRequestHandler` from `@shopify/hydrogen/oxygen`
`react-router.config.ts`	`presets: [hydrogenPreset()]`, `ssr: true`, `buildDirectory: "dist"`
`env.d.ts`	References `@shopify/oxygen-workers-types` for the worker globals
`package.json`	Scripts are `dev` / `build` / `preview` / `start` via the Shopify CLI — no `deploy`, `cf-dev`, `cf-typegen`, or `check`
`wrangler.json`	Does not exist
`.gitignore`	Already ignores `.env` and `.wrangler/`

Nothing below is pre-configured. Treat each step as a change you are making to your own fork.

Prerequisites

Node.js: >=22.12.0 (this is the engines.node requirement of the current Pilot theme)
Cloudflare account: sign up at cloudflare.com
Shopify store: active store with Storefront API access
Weaverse project: a configured project ID for your storefront
A working Oxygen build first — run npm run build and confirm it succeeds before you start migrating

Quick Flow

Add the Cloudflare dependencies

npm i -D wrangler @cloudflare/vite-plugin

Swap the Oxygen Vite plugin for the Cloudflare plugin

Edit vite.config.ts.

Create wrangler.json

Point main at your worker entry and enable nodejs_compat.

Add your own npm scripts

deploy, cf-dev, cf-typegen, check — none of these exist yet.

Upload secrets and deploy

npx wrangler secret bulk .dev.vars then npx wrangler deploy.

The rest of this page expands each step.

1. Install the Cloudflare toolchain

npm install --save-dev wrangler @cloudflare/vite-plugin

@cloudflare/vite-plugin builds your app for the workerd runtime as Cloudflare runs it. wrangler is the CLI used to configure, preview, and deploy the worker.

2. Update `vite.config.ts`

Your theme currently registers the Oxygen plugin. Replace it with the Cloudflare plugin — running both is not supported, since each one owns the SSR environment.

vite.config.ts

  import { reactRouter } from "@react-router/dev/vite";
+ import { cloudflare } from "@cloudflare/vite-plugin";
  import { hydrogen } from "@shopify/hydrogen/vite";
- import { oxygen } from "@shopify/mini-oxygen/vite";
  import tailwindcss from "@tailwindcss/vite";
  import { defineConfig } from "vite";

  export default defineConfig(({ isSsrBuild }) => ({
    plugins: [
      hydrogen(),
-     oxygen(),
+     cloudflare({ viteEnvironment: { name: "ssr" } }),
      reactRouter(),
      tailwindcss(),
    ],
    build: {
      assetsInlineLimit: 0,
    },
    // ...keep the rest of your existing config
  }));

Keep assetsInlineLimit: 0. Pilot sets this so no asset is inlined as a data URI, which keeps the storefront compatible with a strict Content-Security-Policy. See Content Security Policy.

Removing oxygen() also removes the local Oxygen preview that npm run dev and npm run preview rely on. Decide up front whether you are keeping an Oxygen path for local development or moving entirely to wrangler dev.

3. Review your worker entry

server.ts already exports a module-format worker — a default object with an async fetch(request, env, executionContext) method — which is the shape Cloudflare Workers expects. What is not portable is the Oxygen-specific plumbing around it:

createRequestHandler is imported from @shopify/hydrogen/oxygen
env.d.ts pulls worker globals from @shopify/oxygen-workers-types
createHydrogenRouterContext builds the Hydrogen context from Oxygen’s env binding shape

Shopify does not publish a Cloudflare Workers entry for Hydrogen. You will need to verify that the Oxygen request handler, session storage, and caching behave correctly on Cloudflare, and adjust server.ts if they do not. Test this before pointing production traffic at it.

4. Create `wrangler.json`

This file does not exist in the theme — create it in the project root:

wrangler.json

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "your-project-name",
  "main": "./server.ts",
  "compatibility_date": "2025-10-08",
  "compatibility_flags": ["nodejs_compat"],
  "keep_vars": true,
  "observability": {
    "enabled": true
  },
  "upload_source_maps": true
}

Field	Purpose
`name`	Project name — becomes part of the `*.workers.dev` URL
`main`	Worker entry point
`compatibility_date`	Pins the `workerd` runtime behavior
`compatibility_flags`	`nodejs_compat` is required by Hydrogen’s Node built-in usage
`keep_vars`	Preserves dashboard-set variables across deploys
`observability`	Enables Workers logs and metrics
`upload_source_maps`	Readable stack traces in production

If your Cloudflare login has access to multiple accounts, add "account_id": "<your-cloudflare-account-id>" so Wrangler does not prompt. Find it in the Cloudflare Dashboard under Workers & Pages → Overview (right sidebar).

5. Configure environment variables

Wrangler reads local development values from .dev.vars. Create one from your existing .env values:

.dev.vars

NODE_ENV=production
SESSION_SECRET=your-secure-session-secret
PUBLIC_STORE_DOMAIN=your-shopify-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=your-shopify-storefront-api-token
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=your-customer-account-api-client-id
SHOP_ID=your-shop-id
WEAVERSE_PROJECT_ID=your-weaverse-project-id
WEAVERSE_HOST=https://studio.weaverse.io

Add any optional variables your theme uses (JUDGEME_PRIVATE_API_TOKEN, KLAVIYO_PRIVATE_API_TOKEN, PUBLIC_GOOGLE_GTM_ID, and so on) — see .env.example in your theme for the authoritative list. Upload them as Worker secrets:

npx wrangler secret bulk .dev.vars

Setting NODE_ENV=production prevents Hydrogen from injecting its development-only virtual routes into the production build.

Add .dev.vars to .gitignore. The theme already ignores .env and .wrangler/, but not .dev.vars — add it yourself.

6. Add npm scripts

None of these scripts exist in the theme. Add the ones you need to package.json:

package.json

{
  "scripts": {
    "cf-typegen": "wrangler types && react-router typegen",
    "cf-dev": "wrangler dev --port 8787",
    "check": "tsc --noEmit && react-router build && wrangler deploy --dry-run",
    "deploy": "wrangler deploy"
  }
}

Script	What it does
`cf-typegen`	Generates Worker binding types plus React Router route types
`cf-dev`	Runs the app locally in `workerd` on port 8787
`check`	Type check, build, and dry-run deploy — catches config errors before shipping
`deploy`	Publishes the worker

7. Deploy

# Authenticate (opens your browser)
npx wrangler login

# Install and build
npm install
npm run build

# Test in the Workers runtime locally
npm run cf-dev

# Validate before shipping
npm run check

# Ship it
npm run deploy

Wrangler prints the live URL on success, typically https://your-project-name.<subdomain>.workers.dev.

Post-Deployment

Stream logs

npx wrangler tail

Keep this running during your first smoke test so runtime errors surface immediately.

Custom domain

Open the Cloudflare Dashboard
Workers & Pages → select your worker
Settings → Domains & Routes
Add your domain and configure routes

Git-connected builds

Workers & Pages → your worker → Settings → Builds
Connect a Git repository and authorize access
Select the repository and branch
Build command npm run build, output directory dist

Rollback

npx wrangler deployments list
npx wrangler deployments rollback <deployment-id>

A rollback shifts all traffic immediately. Verify the target deployment is healthy first.

Troubleshooting

Build fails after removing oxygen() npm run dev, npm run preview, and npm run start all go through the Shopify CLI’s Oxygen sandbox. Once the Oxygen plugin is gone, use npm run cf-dev instead. nodejs_compat errors at runtime Confirm the flag is in wrangler.json and that compatibility_date is recent enough for the Node compatibility mode your dependencies need. Missing environment variables in production .dev.vars is local-only. Values reach production only after npx wrangler secret bulk .dev.vars, or by setting them in the dashboard. Names are case-sensitive. Weaverse Studio preview does not connect Check WEAVERSE_PROJECT_ID and WEAVERSE_HOST are present as Worker secrets, and that the deployed URL is registered on your Weaverse project. See Preview Errors. Session or cache behaves differently than on Oxygen Expected — this is the least-validated part of the migration. Compare against an Oxygen deployment before going live.

Environment

Building Components

Content Management

Internationalization

Security & Privacy

Pages & Routing

Advanced

Deployment

Deploy to Cloudflare Workers

Deploying a Weaverse Theme to Cloudflare Workers

What your theme ships with today

Prerequisites

Quick Flow

1. Install the Cloudflare toolchain

2. Update `vite.config.ts`

3. Review your worker entry

4. Create `wrangler.json`

5. Configure environment variables

6. Add npm scripts

7. Deploy

Post-Deployment

Stream logs

Custom domain

Git-connected builds

Rollback

Troubleshooting

Additional Resources

​Deploying a Weaverse Theme to Cloudflare Workers

​What your theme ships with today

​Prerequisites

​Quick Flow

​1. Install the Cloudflare toolchain

​2. Update vite.config.ts

​3. Review your worker entry

​4. Create wrangler.json

​5. Configure environment variables

​6. Add npm scripts

​7. Deploy

​Post-Deployment

​Stream logs

​Custom domain

​Git-connected builds

​Rollback

​Troubleshooting

​Additional Resources

Deploying a Weaverse Theme to Cloudflare Workers

What your theme ships with today

Prerequisites

Quick Flow

1. Install the Cloudflare toolchain

2. Update `vite.config.ts`

3. Review your worker entry

4. Create `wrangler.json`

5. Configure environment variables

6. Add npm scripts

7. Deploy

Post-Deployment

Stream logs

Custom domain

Git-connected builds

Rollback

Troubleshooting

Additional Resources