Skip to content

CF_WORKERS.md

Latest commit

 

History

History
150 lines (110 loc) · 5.43 KB

CF_WORKERS.md

File metadata and controls

150 lines (110 loc) · 5.43 KB
Raw

Cloudflare Workers deployment

This guide covers the repository adapter @itxtech/fdnext-cf-workers, which shares the core HTTP routes and external link providers.

For FlashMaster Classic or clients using legacy FlashDetector / FDWebServer routes, use fd-server.

1. Prerequisites

Complete Development setup (Chinese). Deployment requires a Cloudflare account and Wrangler authentication. Wrangler is pinned in the root development dependencies and installed with the workspace:

pnpm install --frozen-lockfile
pnpm exec wrangler login

In CI, use CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID instead of interactive login.

All Worker scripts use the installed Wrangler version from the lockfile. pnpm-workspace.yaml allows the esbuild and workerd build scripts during installation. Keep development dependencies installed in the build environment. No PNPM_CONFIG_STRICT_DEP_BUILDS=false override is needed; remove it if previously configured.

2. Configuration

packages/cf-workers/wrangler.jsonc contains:

{
  "$schema": "../../node_modules/wrangler/config-schema.json",
  "name": "fdnext",
  "main": "dist/index.js",
  "compatibility_date": "2026-05-10",
  "workers_dev": true,
  "minify": true,
  "keep_vars": true,
  "build": {
    "command": "pnpm -C ../core build && pnpm build",
    "watch_dir": [
      "../core/src",
      "../core/resources",
      "src"
    ]
  }
}
  • main points to the adapter bundle inside the package. Root scripts enter packages/cf-workers before invoking Wrangler.
  • build.command builds the core, then the adapter. See Build metadata for injected values and overrides.
  • keep_vars preserves Worker variables configured in the Cloudflare Dashboard across deployments.
  • The entry uses the Web Fetch API and does not require nodejs_compat.
  • workers_dev enables *.workers.dev. For a production domain, configure route / routes, or bind it in the Dashboard and keep Wrangler configuration consistent.

3. Cloudflare Workers Builds

For Git-connected Dashboard builds, explicitly build only the core and adapter. Root pnpm build builds the entire monorepo, including Node.js services. Configure the build command explicitly rather than relying on Wrangler's custom build step:

Setting Value
Root directory Empty or repository root
Build command pnpm install --frozen-lockfile && pnpm cf-workers:build
Deploy command pnpm cf-workers:deploy
Non-production branch deploy command pnpm -C packages/cf-workers exec wrangler versions upload --config wrangler.jsonc

Set build variable SKIP_DEPENDENCY_INSTALL=1 so the explicit pnpm command owns dependency installation instead of the platform choosing another package manager such as Bun.

Manage runtime FDNEXT_CORS_ORIGINS / FDNEXT_SEARCH_LIMIT in the Worker Dashboard; their meanings are in HTTP API. Do not also declare Dashboard-owned variables in Wrangler vars; keep_vars preserves them.

4. Local development

pnpm cf-workers:dev

Wrangler executes build.command before starting the Worker, usually at http://127.0.0.1:8787.

curl 'http://127.0.0.1:8787/'
curl 'http://127.0.0.1:8787/capabilities?lang=eng'
curl 'http://127.0.0.1:8787/parts/decode?query=MT29F64G08CBABA&lang=eng'
curl 'http://127.0.0.1:8787/identifiers/decode?query=2C,64,44,4B,A9,00'

Interpret responses using the HTTP route overview.

5. HTTP settings

HTTP API owns routes, parameters, responses, CORS, and search limits.

6. Manual deployment

Build locally:

pnpm cf-workers:build

Inspect the Wrangler bundle:

pnpm cf-workers:deploy:dry-run

Deploy:

pnpm cf-workers:deploy

Use the URL returned by Wrangler or your bound domain:

curl 'https://<worker>.<account>.workers.dev/'
curl 'https://<worker>.<account>.workers.dev/parts/search?query=MT29'

7. Custom external links

The default entry does not inject external link providers. The workspace package builds dist/index.js and exports createCfWorkersAdapter(). For a custom repository deployment, create an entry inside packages/cf-workers and set that package's Wrangler main to it:

import { createCfWorkersAdapter } from "./src/index";
import type { ExternalLinkProvider } from "@itxtech/fdnext-core/runtime";

const productPageLinks: ExternalLinkProvider = {
  id: "product-page",
  resolveLinks(context) {
    const partNumber = context.facts.partNumber;
    if (!partNumber) return [];
    return [
      {
        id: "product-page",
        label: "Product page",
        url: `https://example.com/parts/${encodeURIComponent(partNumber)}`,
        category: "ds",
        priority: 10
      }
    ];
  }
};

export default createCfWorkersAdapter({
  externalLinkProviders: [productPageLinks]
});

Provider contracts, URL filtering, and sorting are described in Runtime dispatch and external links.

8. Maintenance boundaries

  • The adapter delegates fetch() to the shared runtime.
  • HTTP routes, result contracts, and link filtering belong to packages/core.
  • Do not add legacy aliases or Worker behavior that differs from the Node.js adapter.
  • Resources are bundled into the Worker. Check final bundle size in Wrangler's dry-run output before deployment.