breaking: move `defineEnvVars` to `@sveltejs/kit/env` by Rich-Harris · Pull Request #16375 · sveltejs/kit

Rich-Harris · 2026-07-17T01:22:54Z

We decided this was more future-proof — we might in future want to have more env-related exports (e.g. some convenience schemas) and it would be weird to a) have them in a different place to defineEnvVars or b) put them in @sveltejs/kit/hooks

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
This message body should clearly illustrate what problems it solves.
Ideally, include a test that fails without this PR but passes with it.

Tests

Run the tests with pnpm test and lint the project with pnpm lint and pnpm check

Changesets

If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

Edits

Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.

changeset-bot · 2026-07-17T01:22:57Z

🦋 Changeset detected

Latest commit: 270338e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sveltejs/kit	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-svelte-dev · 2026-07-17T01:22:58Z

Install the latest version of @sveltejs/kit from 270338e:

pnpm add https://pkg.svelte.dev/@sveltejs/kit/c/270338e71f8a057e56e2e520ef1c608b50fb7c7a

Open in pkg.svelte.dev: https://pkg.svelte.dev/repos/kit/pr/16375

vercel

Additional Suggestions:

Adapter test apps still import defineEnvVars from @sveltejs/kit/hooks, which now throws, breaking their build/run.

The @sveltejs/kit/env subpath is imported across the codebase but is not registered in package.json's exports map (nor in generate-dts.js), so import { defineEnvVars } from '@sveltejs/kit/env' fails with ERR_PACKAGE_PATH_NOT_EXPORTED.

Documentation instructs users to import defineEnvVars from @sveltejs/kit/hooks, which now throws at runtime because the export was moved to @sveltejs/kit/env.

…it/hooks`, which now throws, breaking their build/run. This commit fixes the issue reported at packages/adapter-static/test/apps/spa/src/env.ts:1 ## Bug Commit `0804130` ("breaking: move `defineEnvVars` to `@sveltejs/kit/env`") changed `packages/kit/src/exports/hooks/index.js` so that `defineEnvVars` now throws unconditionally: ```js export function defineEnvVars() { throw new Error(``defineEnvVars` has moved — it should be imported from @sveltejs/kit/env`); } ``` The kit test apps were migrated to import from `@sveltejs/kit/env`, but three adapter test apps were missed and still import from `@sveltejs/kit/hooks`: - `packages/adapter-static/test/apps/spa/src/env.ts` - `packages/adapter-static/test/apps/prerendered/src/env.ts` - `packages/adapter-node/test/apps/basic/src/env.js` Each of these calls `defineEnvVars({...})` at module top level, so simply importing the module executes the throwing function. ## Trigger Running the adapter-static / adapter-node test suites (which build/prerender these apps) loads `env.ts`/`env.js`, immediately invoking the stub `defineEnvVars` and throwing `` `defineEnvVars` has moved ``. This is a concrete, deterministic failure at module evaluation time. ## Fix Updated the three files to import `defineEnvVars` from `@sveltejs/kit/env`, matching the kit test apps updated in the same commit. ## Related concern (see notes) The move commit did not add a `./env` entry to the `exports` map in `packages/kit/package.json`, so `@sveltejs/kit/env` may not resolve for any consumer. That is a broader issue affecting the kit test apps too and should be addressed separately by adding the `./env` export. Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: Rich-Harris <hello@rich-harris.dev>

…but is not registered in `package.json`'s `exports` map (nor in `generate-dts.js`), so `import { defineEnvVars } from '@sveltejs/kit/env'` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED`. This commit fixes the issue reported at packages/kit/package.json:115 ## Bug The PR adds `packages/kit/src/exports/env/index.js` exporting `defineEnvVars`, and rewrites imports across test apps to use `@sveltejs/kit/env`: ``` packages/kit/test/apps/basics/src/env.ts:1:import { defineEnvVars } from '@sveltejs/kit/env'; packages/kit/test/apps/options/source/env.ts:1:import { defineEnvVars } from '@sveltejs/kit/env'; ... (7 more test files) ``` However, `packages/kit/package.json`'s `exports` map only had entries for `.`, `./internal*`, `./node`, `./hooks`, and `./vite` — **no `./env` entry**. Under Node's package `exports` encapsulation, any subpath not listed is rejected. So `import { defineEnvVars } from '@sveltejs/kit/env'` resolves to `ERR_PACKAGE_PATH_NOT_EXPORTED`, breaking every test app (and any consumer) that imports it. **Concrete trigger:** running any of the integration test apps (e.g. `test/apps/basics`) whose `src/env.ts` imports from `@sveltejs/kit/env` — module resolution fails immediately. Additionally, `packages/kit/scripts/generate-dts.js` did not list `@sveltejs/kit/env` in its `modules` map, so no `.d.ts` declarations would be generated for the new subpath, leaving `defineEnvVars` untyped for TypeScript consumers. ## Fix 1. Added the `./env` entry to `exports` in `package.json`, mirroring the sibling `./node`/`./hooks` entries: ```json "./env": { "types": "./types/index.d.ts", "import": "./src/exports/env/index.js" }, ``` 2. Registered the module in `generate-dts.js` so declarations are emitted: ```js '@sveltejs/kit/env': 'src/exports/env/index.js', ``` Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: Rich-Harris <hello@rich-harris.dev>

…veltejs/kit/hooks`, which now throws at runtime because the export was moved to `@sveltejs/kit/env`. This commit fixes the issue reported at documentation/docs/20-core-concepts/70-environment-variables.md:28 ## Bug This PR relocated `defineEnvVars` from `@sveltejs/kit/hooks` to `@sveltejs/kit/env`: - `packages/kit/src/exports/env/index.js` now contains the real implementation (`return variables;`). - `packages/kit/src/exports/hooks/index.js` now throws: ```js export function defineEnvVars() { throw new Error(``defineEnvVars` has moved — it should be imported from @sveltejs/kit/env`); } ``` All the app test fixtures were updated to `@sveltejs/kit/env` (e.g. `packages/kit/test/apps/basics/src/env.ts`). However, `documentation/docs/20-core-concepts/70-environment-variables.md` still told users to write: ```ts import { defineEnvVars } from '@sveltejs/kit/hooks'; ``` **Concrete failure mode:** Any user following the docs and importing `defineEnvVars` from `@sveltejs/kit/hooks` triggers the `throw new Error(...)` above at module evaluation time — their app fails to start/build. This appeared in 7 code blocks (lines 28, 45, 68, 113, 128, 148, 192) plus the cross-reference doc-link on line 35 (`[`defineEnvVars`](@sveltejs-kit-hooks#defineEnvVars)`). ## Fix Updated the documentation to reference the new module: - Replaced all 7 `import { defineEnvVars } from '@sveltejs/kit/hooks';` occurrences with `@sveltejs/kit/env`. - Updated the doc-link from `@sveltejs-kit-hooks#defineEnvVars` to `@sveltejs-kit-env#defineEnvVars`. This matches the new export location and the updated test fixtures, so following the docs no longer produces a thrown error. See notes for related follow-ups (missing `./env` entry in `package.json` `exports` and stale generated `types/index.d.ts`) that are outside the scope of this docs fix. Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com> Co-authored-by: Rich-Harris <hello@rich-harris.dev>

svelte-docs-bot · 2026-07-17T01:31:32Z

Preview: https://svelte-dev-git-preview-kit-16375-svelte.vercel.app/

Rich-Harris · 2026-07-17T03:42:38Z

ignore this for now, revisit after #16378

Realised that it'll be easier to do this in stages, deprecating it first rather than erroring immediately (#16375). This way we can keep the docs intact, and allow svelte.dev to continue building. --- ### Please don't delete this checklist! Before submitting the PR, please make sure you do the following: - [x] It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs - [x] This message body should clearly illustrate what problems it solves. - [ ] Ideally, include a test that fails without this PR but passes with it. ### Tests - [x] Run the tests with `pnpm test` and lint the project with `pnpm lint` and `pnpm check` ### Changesets - [x] If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running `pnpm changeset` and following the prompts. Changesets that add features should be `minor` and those that fix bugs should be `patch`. Please prefix changeset messages with `feat:`, `fix:`, or `chore:`. ### Edits - [x] Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed. --------- Co-authored-by: vercel[bot] <35613825+vercel[bot]@users.noreply.github.com> Co-authored-by: Vercel <vercel[bot]@users.noreply.github.com>

This PR was opened by the [Changesets release](https://github.com/changesets/action) GitHub action. When you're ready to do a release, you can merge this and the packages will be published to npm automatically. If you're not ready to do a release yet, that's fine, whenever you add more changesets to version-3, this PR will be updated. ⚠️

⚠️

⚠️ `version-3` is currently in **pre mode** so this branch has prereleases rather than normal releases. If you want to exit prereleases, run `changeset pre exit` on `version-3`. ⚠️

⚠️

⚠️ # Releases ## @sveltejs/kit@3.0.0-next.10 ### Major Changes - breaking: move `defineEnvVars` to `@sveltejs/kit/env` ([#16375](#16375)) ### Patch Changes - fix: treat `data:` protocol URLs as external for redirect ([#16392](#16392)) - perf: skip import graph collection outside client environments ([#16383](#16383)) - fix: warn if there are plugins using `transformIndexHtml` ([#16394](#16394)) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

breaking: move defineEnvVars to @sveltejs/kit/env

0804130

vercel Bot reviewed Jul 17, 2026

View reviewed changes

vercel Bot and others added 4 commits July 17, 2026 01:29

docs

1528759

Rich-Harris added 2 commits July 16, 2026 21:32

regenerate

a1b6e5d

deprecate instead of erroring, for now

d3d806d

vercel Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread packages/kit/types/index.d.ts Outdated

Rich-Harris mentioned this pull request Jul 17, 2026

feat: move defineEnvVars to @sveltejs/kit/env #16378

Merged

6 tasks

Rich-Harris marked this pull request as draft July 17, 2026 03:42

Rich-Harris added 3 commits July 17, 2026 11:52

Merge branch 'version-3' into env-module

60f8c56

dedupe

e1a9430

strip internal

270338e

Rich-Harris marked this pull request as ready for review July 17, 2026 16:46

teemingc approved these changes Jul 17, 2026

View reviewed changes

Rich-Harris merged commit 6c2b2b4 into version-3 Jul 17, 2026
20 of 21 checks passed

Rich-Harris deleted the env-module branch July 17, 2026 17:10

github-actions Bot mentioned this pull request Jul 17, 2026

Version Packages (next) #16386

Merged

Navigation Menu

Uh oh!

Uh oh!

breaking: move `defineEnvVars` to `@sveltejs/kit/env` - #16375

breaking: move `defineEnvVars` to `@sveltejs/kit/env`#16375
Rich-Harris merged 10 commits into
version-3from
env-module

Rich-Harris commented Jul 17, 2026

Uh oh!

changeset-bot Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

pkg-svelte-dev Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

vercel Bot left a comment

Uh oh!

svelte-docs-bot Bot commented Jul 17, 2026

Uh oh!

Uh oh!

Rich-Harris commented Jul 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

Rich-Harris commented Jul 17, 2026

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Changesets

Edits

Uh oh!

changeset-bot Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-svelte-dev Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vercel Bot left a comment

Choose a reason for hiding this comment

Uh oh!

svelte-docs-bot Bot commented Jul 17, 2026

Uh oh!

Uh oh!

Rich-Harris commented Jul 17, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented Jul 17, 2026 •

edited

Loading

pkg-svelte-dev Bot commented Jul 17, 2026 •

edited

Loading