Skip to content

Wrangler Entry Point Configuration

Overview

This document explains how to properly configure the Wrangler entry point for Cloudflare Workers deployments, particularly when dealing with static assets and worker scripts.

Understanding the Error

If you encounter an error similar to:

If are uploading a directory of assets, you can either:
- Specify the path to the directory of assets via the command line: (ex: `npx wrangler deploy --assets=./dist`)
- Or create a "wrangler.jsonc" file containing:

This indicates that Wrangler cannot determine the entry point for your deployment. This typically occurs when:

  1. You're trying to deploy assets but haven't specified the assets directory
  2. The worker entry point (main file) is missing or incorrectly configured
  3. The wrangler.jsonc configuration file is missing required fields

Configuration Options

Option 1: Command Line Deployment

For simple asset-only deployments (no worker logic), specify the assets directory directly:

npx wrangler deploy --assets=./dist

This is suitable for: - Static websites - Pure HTML/CSS/JS applications - Sites without server-side logic

Option 2: wrangler.jsonc Configuration

For more complex deployments (worker + assets), create or update your wrangler.jsonc file:

Basic Assets-Only Configuration

{
  "name": "worker-name",
  "compatibility_date": "2025-11-02",
  "assets": {
    "directory": "./dist"
  }
}

{
  "name": "piquetickets-frontend",
  "main": ".open-next/worker.js",
  "compatibility_date": "2025-03-25",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  }
}

Key fields: - name: The name of your worker - main: Entry point for your worker script - compatibility_date: API compatibility date - compatibility_flags: Required features (e.g., Node.js compatibility) - assets.directory: Path to static assets - assets.binding: Binding name for accessing assets in worker code

PiqueTickets Configuration

Current Setup

For our Next.js frontend deployed to Cloudflare Workers using @opennextjs/cloudflare, we use the following configuration:

File: apps/frontend/wrangler.jsonc

{
  "main": ".open-next/worker.js",
  "compatibility_date": "2025-03-25",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "directory": ".open-next/assets",
    "binding": "ASSETS"
  },
  "routes": [
    { "pattern": "piquetickets.com/*", "zone_name": "piquetickets.com" },
    { "pattern": "www.piquetickets.com/*", "zone_name": "piquetickets.com" }
  ],
  "env": {
    "stage": {
      "routes": [
        { "pattern": "stage.piquetickets.com/*", "zone_name": "piquetickets.com" }
      ]
    }
  }
}

Build Process

The build process for our Next.js app creates the required structure:

# Build the Next.js app for Cloudflare Workers
npm run build:worker
# This runs: OPENNEXT_BUILD=true npx opennextjs-cloudflare build

# Result:
# .open-next/
# ├── worker.js        # Worker entry point
# └── assets/          # Static assets directory

Deployment Commands

# Deploy to production
npx wrangler deploy --name piquetickets-frontend-production

# Deploy to stage
npx wrangler deploy --env stage --name piquetickets-frontend-stage

# Deploy with specific assets directory (if needed)
npx wrangler deploy --assets=./.open-next/assets

Common Issues and Solutions

Issue 1: "No entry point found"

Error: 

Failed: error occurred while running deploy command

Solution: Ensure your wrangler.jsonc has either: - A main field pointing to your worker entry point, OR - An assets field with the assets directory

Issue 2: "Assets directory not found"

Error: 

Error: Assets directory './dist' does not exist

Solution: 1. Verify the build ran successfully 2. Check the assets path in wrangler.jsonc matches the build output 3. Run the build command before deploying: 

npm run build:worker
npx wrangler deploy

Issue 3: "Worker name missing"

Error: 

Error: Worker name is required

Solution: Either: - Add "name": "your-worker-name" to wrangler.jsonc, OR - Specify via command line: npx wrangler deploy --name your-worker-name

Recommendation: Use command line for multi-environment setups: 

npx wrangler deploy --name piquetickets-frontend-production
npx wrangler deploy --env stage --name piquetickets-frontend-stage

Issue 4: "Compatibility flags error"

Error: 

Error: Unknown compatibility flag: nodejs_compat

Solution: Update your compatibility_date to a recent date: 

{
  "compatibility_date": "2025-03-25",
  "compatibility_flags": ["nodejs_compat"]
}

Best Practices

1. Use Environment-Specific Worker Names

Avoid hardcoding worker names in wrangler.jsonc. Instead, use command-line flags:

# Production
npx wrangler deploy --name piquetickets-frontend-production

# Staging
npx wrangler deploy --env stage --name piquetickets-frontend-stage

2. Separate Routes from Variables

Keep environment-specific routes in wrangler.jsonc, but store sensitive data in environment variables:

{
  "routes": [...],  // ✅ OK in config
  "env": {
    "stage": {
      "routes": [...]  // ✅ OK in config
    }
  }
  // ❌ Don't add vars here - use GitHub Environments or .env files
}

3. Verify Build Output

Always check that the build creates the expected structure:

# For Next.js with opennextjs-cloudflare
ls -la .open-next/
# Should show:
# - worker.js
# - assets/

4. Test Locally Before Deploying

Use Wrangler's preview feature:

npm run preview:worker
# Or directly:
npx wrangler dev

5. Use Deployment Scripts

Add these to package.json:

{
  "scripts": {
    "build:worker": "OPENNEXT_BUILD=true npx opennextjs-cloudflare build",
    "preview:worker": "npx opennextjs-cloudflare preview",
    "deploy:stage": "npm run build:worker && npx wrangler deploy --env stage --name piquetickets-frontend-stage",
    "deploy:production": "npm run build:worker && npx wrangler deploy --name piquetickets-frontend-production"
  }
}

Troubleshooting Checklist

When encountering deployment issues, verify:

  • wrangler.jsonc exists in the correct directory
  • main field points to an existing file
  • assets.directory points to an existing directory
  • Build command has been run (npm run build:worker)
  • Wrangler CLI is installed and authenticated
  • compatibility_date is set to a recent date
  • Required compatibility_flags are specified (e.g., nodejs_compat)
  • Worker name is provided (via config or command line)
  • Cloudflare API token has correct permissions

CI/CD Integration

GitHub Actions Example

- name: Build for Cloudflare Workers
  working-directory: apps/frontend
  run: npm run build:worker
  env:
    NEXT_PUBLIC_API_URL: ${{ vars.NEXT_PUBLIC_API_URL }}
    NEXT_PUBLIC_ENVIRONMENT: ${{ vars.NEXT_PUBLIC_ENVIRONMENT }}

- name: Deploy to Cloudflare Workers
  working-directory: apps/frontend
  run: npx wrangler deploy --env stage --name piquetickets-frontend-stage
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Additional Resources