Dev notes

This project creates a small placeholder worker entrypoint at dist/_worker.js/index.js to satisfy the Cloudflare plugin's config-time checks for the main entry in wrangler.toml. Without an entrypoint the build or adapter checks can fail early.

To make development pleasant we now do one of two things:

• In normal build flows the placeholder is a minimal 503 response:

  • Response body: Worker building — placeholder response
  • Status: 503
  • This file is intended to be overwritten by the real build artifact during astro build.

• In development (recommended) the placeholder is a dev-proxy:

  • It forwards incoming requests to the local dev server (default: http://127.0.0.1:8083) so visiting the public URL returns the same content you see on astro dev.
  • The placeholder file contains both:
    • /* AUTOGENERATED BY scripts/ensure-worker-main.mjs */
    • /* DEV_PROXY_PLACEHOLDER */ (if the proxy mode is enabled)

How to use

• Start dev (default dev script enables the proxy):

  pnpm run dev

  This runs node scripts/ensure-worker-main.mjs with DEV_PLACEHOLDER_PROXY=1 (so the placeholder will proxy to the local dev server), cleans ports, then runs astro dev.

• Create / update the placeholder manually (proxy mode):

  DEV_PLACEHOLDER_PROXY=1 node scripts/ensure-worker-main.mjs

• Create the minimal (non-proxy) placeholder:

  node scripts/ensure-worker-main.mjs

• Custom dev server URL:

  DEV_PLACEHOLDER_PROXY=1 DEV_SERVER_URL=http://127.0.0.1:8088 node scripts/ensure-worker-main.mjs

Troubleshooting

• If you see Worker building — placeholder response in dev:
  1. Make sure pnpm run dev was used (it sets DEV_PLACEHOLDER_PROXY=1 by default).
  2. Run DEV_PLACEHOLDER_PROXY=1 node scripts/ensure-worker-main.mjs to ensure the placeholder is in proxy mode.
  3. Verify the placeholder at dist/_worker.js/index.js contains /* DEV_PROXY_PLACEHOLDER */.
  4. If your dev server uses a different port, set DEV_SERVER_URL to the correct address.

Why this exists

The Cloudflare plugin validates that the main path in wrangler.toml points to an existing file at config time. We create a safe, idempotent placeholder so the plugin and local tooling don't fail. In dev the proxy mode makes the placeholder behave like a helpful bridge to your running astro dev process until the real worker build replaces it.

If you want this behavior changed or made conditional in another way, let us know and we can adjust the script or the dev script in package.json.