Test the Worker locally

Local testing is optional before deploying an unchanged checkout. It is useful when you modify the handler or configuration.

Start the local API

From the repository root:

pnpm install --frozen-lockfile

No secrets are needed. Quota defaults are in apps/api/wrangler.jsonc. Wrangler stores local quota state in .wrangler/state.

pnpm --filter @nobg/api dev

The API listens at http://localhost:8787. Check it with:

curl --fail-with-body http://localhost:8787/api/health

For direct local upload-route requests, include CF-Connecting-IP: 127.0.0.1 if the local runtime does not add it. Production callers should not set this header; Cloudflare supplies it.

Run checks

pnpm --filter @nobg/api typecheck
pnpm --filter @nobg/api test
pnpm --filter @nobg/api build

Tests mock the Images binding to check IP quotas, validation, errors, and response handling. Separate tests exercise real local Durable Objects for concurrency, persistence, and quota expiry. The build command runs wrangler deploy --dry-run and writes a local bundle. Neither command deploys a Worker.

Local image-processing limits

The local Wrangler runtime does not support background segmentation. An upload can fail at the Images inspection or transformation stage even when the HTTP request is correct. A passing mocked test does not establish background-removal quality or access to the deployed Images service.

The API’s development command uses --local and the config has no remote bindings. Use the deployment guide when you are ready to publish the Worker.

Test the browser demo

Copy the example files from the repository root before starting both apps:

cp apps/web/.env.example apps/web/.env
cp apps/api/.dev.vars.example apps/api/.dev.vars
pnpm dev

These files set PUBLIC_API_URL=http://localhost:8787 for the website and ALLOWED_ORIGINS=http://localhost:4321 for the API. Use matching hostnames if you prefer 127.0.0.1.

The demo uploads only when you choose Remove background. Local Images cannot perform segmentation; use mocked responses when testing preview, download, and error states without paid processing.