Reference

Plugin options, environment variables, endpoints, and exports for payload-dev-tools.

Plugin options

enabledbooleandefault NODE_ENV === 'development'

Turns the endpoints on or off. The default gates everything to development, and no value forces them on under NODE_ENV=production — a deployed build registers nothing. Pass true for the environments in between, such as a test run or an integration harness.

optionsDevToolsOptions

The plugin's own knobs.

devRoutestringdefault '/dev'

Where the host app mounts the createDevPage catch-all. Drives the toolbar's built-in link and the browser redirect from GET /api/dev.

regionsDevRegion[]default DEFAULT_REGIONS

The locations the toolbar's Region view offers, each as { code, label, regime, consent }. Defaults to one region per distinct behaviour (DE, FR, GB, CH, US, US-CA, BR, CA, JP). Entries here also win over the built-in lookup table, so this is where you correct or add a region. See Testing by location.

accessDevToolsAccessOptions

Per-endpoint gate for the plugin's HTTP endpoints — one EndpointAccess ((req) => boolean | Promise<boolean>) covering all /dev* routes. See Gating endpoints.

devEndpointAccessdefault public

Gates every /dev* endpoint. Public by default — they only register in development — but this knob lets you close them on a shared dev environment.

interface DevToolsPluginOptions {
  enabled?: boolean
  options?: {
    devRoute?: string // default '/dev'
    regions?: DevRegion[] // default DEFAULT_REGIONS
    access?: {
      dev?: EndpointAccess // default: public (the /dev* endpoints already only register in dev)
    }
  }
}

interface DevRegion {
  code: string // ISO 3166 — 'DE', or 'US-CA' for a subdivision with its own law
  label: string
  regime: 'gdpr' | 'uk-gdpr' | 'ccpa' | 'lgpd' | 'pipeda' | 'fadp' | 'appi' | 'pipl' | 'none'
  consent: 'opt-in' | 'opt-out' | 'none'
}

access.dev gates the endpoints, not the pages. It's checked in the /api/dev* handlers only. The /dev HTML pages check enabled and nothing else, so a gate that closes the endpoints still leaves the pages — and the counts, slugs, and seed state they render — open to anyone with the URL. To close the pages, set enabled: false (or don't deploy the catch-all route).

createDevPage({ payload, tests, enabled }) and <DevToolbar tests links enabled /> take the same enabled override and the same tests array (from defineTest). createDevPage also requires a payload handle (getPayload({ config })); tests and enabled are optional. The toolbar's links adds extra rows to its Pages view; point them at your own labs.

Environment variables

Gating is the enabled option (defaulting to NODE_ENV === 'development'), not an env var. These two exist only as the handoff from the payload-dev-env CLI — you set them by using it, not by hand. See Environments.

Variable	What
`PAYLOAD_DEV_ENV`	The env name the CLI booted with; the toolbar and `/dev` show it. Stamped into the child process.
`PAYLOAD_DEV_ENV_FILE`	The env file the CLI loaded. Read as an input too: it overrides the `.env.<name>.local` → `.env.<name>` search.

The checklist in the Info view reports variables other plugins read (ENABLE_SEED, MUX_TOKEN_ID, …) — presence only, never values. They belong to those plugins, not this one.

CLI

Command	What
`payload-dev-env <name> [--file <path>] -- <command…>`	Loads `.env.<name>.local` / `.env.<name>` (or `--file`) and runs the command with those values in front of the ambient environment. Exits non-zero, without running anything, when no file matches.

Endpoints

All five routes 404 outside development — with enabled off they're never registered. Where they are registered, options.access.dev gates them (public by default; the knob lets you close them — see Gating endpoints). A denial is 403 {"error":"Forbidden."}, not a 404. See The /dev pages for the snapshot shape and what each view renders.

Route	What
`GET /api/dev`	Machine-readable app snapshot (env, plugins, seed status, counts, misses). Browsers are redirected to `/dev`.
`GET /api/dev/stage`	Stages a test version (`?test=…&version=…`) or a header/footer chrome slot (`?slot=header\|footer`) in a cookie, then redirects (`?to=` targets it, `?clear=1` resets).
`GET /api/dev/region`	Overrides the visitor's location in a cookie (`?code=DE`, `?clear=1` resets, `?to=` targets the redirect). 400s on a code it can't resolve.
`GET /api/dev/draft`	Toggles Next.js draft mode.
`POST /api/dev/icons/activate`	Sets the active icon set.

Exports

Export	From	What
`devToolsPlugin`	`@pro-laico/payload-dev-tools`	Plugin factory; registers the `/api/dev*` endpoints.
`defineTest`	`@pro-laico/payload-dev-tools` (and `/next`, `/toolbar`)	Identity helper defining a test's versions with full typing.
`readDevToolsMarker`	`@pro-laico/payload-dev-tools`	Reads this plugin's `config.custom` marker (`PayloadDevToolsMarker`) — the resolved `devRoute` and `regions`, for custom tooling.
`PayloadDevToolsMarker`	`@pro-laico/payload-dev-tools`	The marker's type: `{ options, devRoute, regions }`.
`DevToolsPluginOptions`	`@pro-laico/payload-dev-tools`	The `devToolsPlugin(options?)` argument type: `{ enabled?, options? }`.
`DevToolsAccessOptions`	`@pro-laico/payload-dev-tools`	The `options.access` gate-map shape: `{ dev? }`.
`EndpointAccess`	`@pro-laico/payload-dev-tools`	The endpoint-gate function type `(req) => boolean \| Promise<boolean>`; see Gating endpoints.
`Test` / `TestKind` / `TestVersion`	`@pro-laico/payload-dev-tools` (and `/next`, `/toolbar`)	What `defineTest` returns and takes — a test, its kind (`page` / `header` / `footer` / `block` / `custom`), and one version.
`TestMeta`	`@pro-laico/payload-dev-tools`	A test stripped of its `render` functions — the label-only shape the toolbar receives.
`DevSnapshot` / `CollectionCount` / `SeedSnapshot` / `ImagesSnapshot` / `IconsSnapshot` / `FontsSnapshot` / `MuxSnapshot`	`@pro-laico/payload-dev-tools`	The `GET /api/dev` response shape and its per-plugin panels, for typed consumers.
`EnvSnapshot` / `EnvVarStatus` / `DatabaseStatus`	`@pro-laico/payload-dev-tools`	The snapshot's `env` block: what booted, the variable checklist, and the database host.
`regionFor`	`@pro-laico/payload-dev-tools`	Pure code → region lookup (`(code, regions?) => DevRegion \| undefined`). Framework-free, so it works in middleware.
`REGIONS` / `DEFAULT_REGIONS`	`@pro-laico/payload-dev-tools`	Every resolvable region (the EEA plus the countries with their own regime), and the default toolbar chips.
`DevRegion` / `PrivacyRegime` / `ConsentModel`	`@pro-laico/payload-dev-tools` (and `/toolbar`)	One region, the regime it falls under, and the `opt-in` / `opt-out` / `none` model to branch on.
`STAGE_COOKIE` / `REGION_COOKIE`	`@pro-laico/payload-dev-tools`	The stage and region cookie names, for custom staging tooling.
`createDevPage`	`@pro-laico/payload-dev-tools/next`	The `/dev` pages; one catch-all drop-in file.
`CreateDevPageOptions`	`@pro-laico/payload-dev-tools/next`	`createDevPage`'s argument type: `{ payload, tests?, enabled? }`.
`DevToolbar`	`@pro-laico/payload-dev-tools/toolbar`	The floating toolbar server component; one line in your layout.
`DevToolbarProps` / `DevLink`	`@pro-laico/payload-dev-tools/toolbar`	The toolbar's props (`{ tests?, links?, enabled? }`), and one `links` entry (`{ href, title }`).
`resolveDevChrome`	`@pro-laico/payload-dev-tools/toolbar`	The chrome-swap seam: returns the real header/footer, or the toolbar-selected variant.
`ResolveDevChromeOptions`	`@pro-laico/payload-dev-tools/toolbar`	`resolveDevChrome`'s argument type: `{ tests, header, footer, enabled? }`.
`resolveDevRegion`	`@pro-laico/payload-dev-tools/toolbar`	The location seam: returns the real region, or the toolbar-selected one in development.
`ResolveDevRegionOptions`	`@pro-laico/payload-dev-tools/toolbar`	`resolveDevRegion`'s argument type: `{ region?, regions?, enabled? }`.

Collections & globals

None — this plugin registers no collections or globals. It reads sibling plugins' collections through their config.custom markers to build the /dev pages and snapshot.