feat: better environment support

[angeloashmore]

Is your feature request related to a problem? Please describe.

Environments only have low-level controls. --env exists, but nothing persists it, so a developer has to pass it on every command and remember which environment they're in. That is easy to forget, and easy to target the wrong one.

The Type Builder has an environment dropdown, but it is specific to that UI. It has no connection to the CLI or the running website. There is no shared, persisted "active environment" that the CLI, the site, and the developer all agree on.

We want a persisted active environment, defaulting to production, that:

• the developer can select, clear, and inspect from the CLI, so they set it once instead of repeating --env;
• the running website resolves without the CLI at runtime, including in client-side bundles, which have no filesystem;
• works the same in CI, where the pipeline sets the environment;
• is scoped per project (per working copy), not per machine, so multiple projects or git worktrees do not collide;
• has one source of truth, so a manual change and a CLI change cannot silently drift apart.

Describe the solution you'd like

A persisted active environment managed through the CLI, defaulting to production, that the website reads natively at build time and that CI can set through the pipeline. The existing --env <name> per-command override stays for one-off targeting.

Concrete approaches are proposed and compared in the comments rather than fixed here.

Describe alternatives you've considered

Directions that are ruled out, to bound the solution:

• Injecting the value inline in package.json scripts (for example, command substitution). Not cross-platform, since npm runs scripts under cmd.exe on Windows.
• A wrapper run command (for example, prismic env exec -- next dev). Cross-platform, but intrusive, and it does not fit a developer's existing setup.
• Reading machine-global state at runtime. Not portable to client-side bundles, and machine scope is wrong for a per-project setting.
• A server-side active environment. Environments are for local development.

Additional context

The Type Builder shows an npx prismic pull command. When a non-production environment is active, that command should reflect it.

[angeloashmore]

Proposed solution: store it in .env.local

(Attempted in #210)

The active environment is one variable in the project's .env.local. The CLI writes it, the site reads it natively, nothing runs at build time.

Variable name

Per framework, matching the names Slice Machine already writes so existing projects keep working:

Next       NEXT_PUBLIC_PRISMIC_ENVIRONMENT
Nuxt       NUXT_PUBLIC_PRISMIC_ENVIRONMENT
SvelteKit  VITE_PRISMIC_ENVIRONMENT

The value is the resolved repo domain, so nothing hits the API at read time.

Commands

prismic env set <name>     # resolve <name>, write the var; production removes it
prismic env unset          # back to production
prismic env active         # print the active environment
prismic env list

--env <name> stays as the per-command override and writes nothing.

Resolution order

--env, then --repo, then process.env, then .env.local, then prismic.config.json. The CLI reads .env.local with util.parseEnv, so it never touches process.env.

How the site reads it

One line in the generated file:

// Next.js
export const repositoryName =
  process.env.NEXT_PUBLIC_PRISMIC_ENVIRONMENT || prismicConfig.repositoryName;

// SvelteKit
export const repositoryName =
  import.meta.env.VITE_PRISMIC_ENVIRONMENT || prismicConfig.repositoryName;

Nuxt needs no change; @nuxtjs/prismic reads the var on its own. CI sets the same var.

Tradeoffs

• Simple and dependency-free, and backward compatible with Slice Machine.
• The CLI writes into .env.local, a file the developer also owns.
• The var sits in the project where people can hand-edit it, so a manual change and a CLI change can drift.

[angeloashmore]

Proposed solution: read it through the CLI (no install)

The CLI owns the active environment in its own state file, keyed per project. env set/unset/active read and write it. Nothing goes in the project.

The config asks the CLI for it at build time and sets the site's var:

// next.config.ts
import { execSync } from "node:child_process";
process.env.NEXT_PUBLIC_PRISMIC_ENVIRONMENT ??=
  execSync("npx -y prismic env active", { encoding: "utf8" }).trim();

Vite, SvelteKit, and Astro are the same with their var. Nuxt needs nothing; @nuxtjs/prismic runs the same call in its module.

Tradeoffs

• No dependency. The command is the whole interface.
• Spawns npx on every dev/build start, so it adds startup latency and leans on the npx cache and registry. Skipped when the var is already set, so CI doesn't spawn. Needs a try/catch to fall back to production.
• env active has to print a clean value and skip telemetry when called this way.
• The read must be synchronous so it lands before the framework reads env. Fine for Next and the Vite frameworks; Nuxt goes through its module.

[angeloashmore]

Proposed solution: a one-line import

Same CLI-owned state, wrapped in a side-effect import so the config has one line and nothing to get wrong:

// next.config.ts
import "prismic/env/register";

The import reads the state in process and sets the framework's var. Under the hood it wraps the helper from the next option, kept internal here:

// prismic/env/register
import { getActiveEnvironment } from "prismic/env";
process.env.NEXT_PUBLIC_PRISMIC_ENVIRONMENT ??= getActiveEnvironment();

No npx, no spawn. Vite, SvelteKit, and Astro are the same with their var. Nuxt needs nothing; @nuxtjs/prismic reads the same state and sets runtimeConfig.public.

Tradeoffs

• Smallest surface: the developer never types the var name or the assignment.
• Requires installing prismic as a dependency, a change from the npx-only guidance.
• Reads state in process, so no spawn and no dependency on the npx cache or registry.
• Writes nothing to the project.

[angeloashmore]

Proposed solution: a getActiveEnvironment() helper

Same CLI-owned state, but prismic/env exports a synchronous getActiveEnvironment() the config calls directly:

// next.config.ts
import { getActiveEnvironment } from "prismic/env";
process.env.NEXT_PUBLIC_PRISMIC_ENVIRONMENT ??= getActiveEnvironment();

It reads the CLI state in process and returns the active repo, or the config default when nothing is set. No npx, no spawn, no API at build time. Vite, SvelteKit, and Astro are the same with their var. Nuxt needs nothing; @nuxtjs/prismic calls the same helper and writes runtimeConfig.public.

Tradeoffs

• Requires installing prismic as a dependency.
• Reads state in process, so no spawn and no dependency on the npx cache or registry.
• One helper works for every framework.
• More surface than the one-line import: the developer picks the var and writes the assignment, so placement is easier to get wrong.
• Writes nothing to the project.

[angeloashmore]

Rough shape of what I want to try in a PR before we commit to anything. Feedback welcome.

The active environment lives in the CLI, not in the project. You pick it with the CLI, and the site reads it at build time:

prismic env set my-staging-env
prismic env unset          # back to production
prismic env active         # prints the current one
prismic env list

In a Next / Vite / SvelteKit / Astro project, one import wires it up:

// next.config.ts
import "prismic/env/register";

That import is just:

import { getActiveEnvironment } from "prismic/env";
process.env.NEXT_PUBLIC_PRISMIC_ENVIRONMENT ??= getActiveEnvironment();

The var name comes from the framework adapter. getActiveEnvironment() returns the active repo, or undefined when nothing is set, so the ??= leaves CI's value alone and falls back to prismic.config.json.

Nuxt needs no config change. @nuxtjs/prismic calls getActiveEnvironment() itself and sets runtimeConfig.public.prismic.environment. (It doesn't today, but it would be updated to do it.)

getActiveEnvironment() is exported but undocumented. It's there for the Nuxt module, and as an escape hatch if someone wants a different var or to place the value themselves.

A few notes:

• State is stored in the CLI config dir (~/.config/prismic), keyed by project. Nothing lands in the repo, so there's no editable var to drift or hand-manage.
• Resolution order: --env flag, then process.env (CI), then CLI state, then prismic.config.json.
• This needs prismic installed as a dependency, which is new. Today we only tell people to npx prismic. prismic init can add it.

Why not Option 1 (write the var into .env.local): it puts an editable value in the project that people start managing by hand. Keeping it in CLI state is the whole point.

One thing to sort out: projects that used Slice Machine already have NEXT_PUBLIC_PRISMIC_ENVIRONMENT in .env.local. The framework loads that into process.env, so ??= would keep the stale value. env set probably needs to strip it.