Standalone Workers

Deploying independent Workers separate from Pages

When to Use

Standalone Workers are best for:

• Search workers — Dedicated search APIs with their own data and dependencies
• AI chat workers — LLM-powered endpoints with API key bindings
• Webhook handlers — Receiving callbacks from external services
• Proxy workers — Routing or transforming requests

Project Structure

A typical standalone Worker project:

packages/my-worker/
├── src/
│   └── index.ts
├── wrangler.toml
├── package.json
└── tsconfig.json

Worker Entry Point

// src/index.ts
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/api/search") {
      return handleSearch(request, env);
    }

    return new Response("Not Found", { status: 404 });
  },
};

Deployment

Deploy with wrangler deploy (not wrangler pages deploy):

npx wrangler@4 deploy

In CI, deploy from the worker’s directory:

- name: Deploy Worker
  working-directory: packages/my-worker
  run: pnpm run deploy
  env:
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

Path-Triggered Deploys

For monorepos with multiple workers, trigger deploys only when the worker’s files change:

on:
  push:
    branches:
      - main
    paths:
      - 'packages/my-worker/**'
  workflow_dispatch:  # Allow manual triggers

This avoids unnecessary deploys when other parts of the monorepo change.