From 7c9eef9598f666ddf172d7da5c6e770132f64bcf Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 16 Jul 2026 22:20:47 -0400 Subject: [PATCH 1/3] feat: move `defineEnvVars` to `@sveltejs/kit/env` --- .changeset/ninety-jobs-bet.md | 5 +++++ .../20-core-concepts/70-environment-variables.md | 16 ++++++++-------- packages/kit/src/exports/env/index.js | 12 ++++++++++++ packages/kit/src/exports/hooks/index.js | 2 ++ packages/kit/src/exports/public.d.ts | 2 +- packages/kit/types/index.d.ts | 5 +++-- 6 files changed, 31 insertions(+), 11 deletions(-) create mode 100644 .changeset/ninety-jobs-bet.md create mode 100644 packages/kit/src/exports/env/index.js diff --git a/.changeset/ninety-jobs-bet.md b/.changeset/ninety-jobs-bet.md new file mode 100644 index 000000000000..d359a2c1df9c --- /dev/null +++ b/.changeset/ninety-jobs-bet.md @@ -0,0 +1,5 @@ +--- +'@sveltejs/kit': minor +--- + +feat: move `defineEnvVars` to `@sveltejs/kit/env` diff --git a/documentation/docs/20-core-concepts/70-environment-variables.md b/documentation/docs/20-core-concepts/70-environment-variables.md index 497ddad6296a..7d27e16e7022 100644 --- a/documentation/docs/20-core-concepts/70-environment-variables.md +++ b/documentation/docs/20-core-concepts/70-environment-variables.md @@ -48,14 +48,14 @@ export default { ```ts /// file: src/env.ts -import { defineEnvVars } from '@sveltejs/kit/hooks'; +import { defineEnvVars } from '@sveltejs/kit/env'; export const variables = defineEnvVars({ // ... }); ``` -Each value in the object passed to [`defineEnvVars`](@sveltejs-kit-hooks#defineEnvVars) is an [`EnvVarConfig`](@sveltejs-kit#EnvVarConfig) object that configures the environment variable. +Each value in the object passed to [`defineEnvVars`](@sveltejs-kit-env#defineEnvVars) is an [`EnvVarConfig`](@sveltejs-kit#EnvVarConfig) object that configures the environment variable. > [!NOTE] `defineEnvVars` returns its argument unaltered — it exists purely to help with type safety. @@ -65,7 +65,7 @@ By default, all variables are considered private. For example, you don't want to ```ts /// file: src/env.ts -import { defineEnvVars } from '@sveltejs/kit/hooks'; +import { defineEnvVars } from '@sveltejs/kit/env'; export const variables = defineEnvVars({ +++API_KEY: {}+++ @@ -88,7 +88,7 @@ Some variables are perfectly safe — necessary, even — to expose to the brow ```ts /// file: src/env.ts -import { defineEnvVars } from '@sveltejs/kit/hooks'; +import { defineEnvVars } from '@sveltejs/kit/env'; export const variables = defineEnvVars({ GOOGLE_ANALYTICS_ID: { @@ -133,7 +133,7 @@ You can specify a [Standard Schema](https://standardschema.dev/) validator such ```ts /// file: src/env.ts -import { defineEnvVars } from '@sveltejs/kit/hooks'; +import { defineEnvVars } from '@sveltejs/kit/env'; +++import * as v from 'valibot';+++ export const variables = defineEnvVars({ @@ -148,7 +148,7 @@ If a value is invalid, the app will fail to start (or build). To opt out of one ```ts /// file: src/env.ts -import { defineEnvVars } from '@sveltejs/kit/hooks'; +import { defineEnvVars } from '@sveltejs/kit/env'; +++import { building } from '$app/env'+++ import * as v from 'valibot'; @@ -168,7 +168,7 @@ By default, variables are dynamic. If a variable is configured with `static: tru ```ts /// file: src/env.ts -import { defineEnvVars } from '@sveltejs/kit/hooks'; +import { defineEnvVars } from '@sveltejs/kit/env'; import * as v from 'valibot'; export const variables = defineEnvVars({ @@ -212,7 +212,7 @@ You can document the purpose of an environment variable by adding a `description ```ts /// file: src/env.ts -import { defineEnvVars } from '@sveltejs/kit/hooks'; +import { defineEnvVars } from '@sveltejs/kit/env'; export const variables = defineEnvVars({ CACHE_TTL_SECONDS: { diff --git a/packages/kit/src/exports/env/index.js b/packages/kit/src/exports/env/index.js new file mode 100644 index 000000000000..1f3e591e4b20 --- /dev/null +++ b/packages/kit/src/exports/env/index.js @@ -0,0 +1,12 @@ +/** @import { EnvVarConfig } from '@sveltejs/kit' */ + +/** + * Utility for defining [environment variables](https://svelte.dev/docs/kit/environment-variables), + * which are made available via `$app/env/public` and `$app/env/private`. + * @template {Record>} T + * @param {T} variables + * @returns {T} + */ +export function defineEnvVars(variables) { + return variables; +} diff --git a/packages/kit/src/exports/hooks/index.js b/packages/kit/src/exports/hooks/index.js index 38bacee3ba48..460c07b366c8 100644 --- a/packages/kit/src/exports/hooks/index.js +++ b/packages/kit/src/exports/hooks/index.js @@ -8,7 +8,9 @@ export { sequence } from './sequence.js'; * @template {Record>} T * @param {T} variables * @returns {T} + * @deprecated Import `defineEnvVars` from `@sveltejs/kit/env` instead */ export function defineEnvVars(variables) { + console.warn(`\`defineEnvVars\` has moved — import it from \`@sveltejs/kit/env\` instead`); return variables; } diff --git a/packages/kit/src/exports/public.d.ts b/packages/kit/src/exports/public.d.ts index 68d71c1f0d30..e647f8c7a843 100644 --- a/packages/kit/src/exports/public.d.ts +++ b/packages/kit/src/exports/public.d.ts @@ -2366,7 +2366,7 @@ export type RemoteLiveQueryFunction = ( /** * [Environment variables](https://svelte.dev/docs/kit/environment-variables) can be configured by exporting - * a `variables` object from `src/env.ts`, using [`defineEnvVars`](https://svelte.dev/docs/kit/@sveltejs-kit-hooks#defineEnvVars). + * a `variables` object from `src/env.ts`, using [`defineEnvVars`](https://svelte.dev/docs/kit/@sveltejs-kit-env#defineEnvVars). */ export interface EnvVarConfig { /** diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts index 56081788b7e1..f30d2f718cc8 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -2339,7 +2339,7 @@ declare module '@sveltejs/kit' { /** * [Environment variables](https://svelte.dev/docs/kit/environment-variables) can be configured by exporting - * a `variables` object from `src/env.ts`, using [`defineEnvVars`](https://svelte.dev/docs/kit/@sveltejs-kit-hooks#defineEnvVars). + * a `variables` object from `src/env.ts`, using [`defineEnvVars`](https://svelte.dev/docs/kit/@sveltejs-kit-env#defineEnvVars). */ export interface EnvVarConfig { /** @@ -3050,7 +3050,8 @@ declare module '@sveltejs/kit/hooks' { /** * Utility for defining [environment variables](https://svelte.dev/docs/kit/environment-variables), * which are made available via `$app/env/public` and `$app/env/private`. - * */ + * @deprecated Import `defineEnvVars` from `@sveltejs/kit/env` instead + */ export function defineEnvVars>>(variables: T): T; /** * A helper function for sequencing multiple `handle` calls in a middleware-like manner. From 89b0f3cc3d14975a1fc358395aa03f9da4672716 Mon Sep 17 00:00:00 2001 From: "vercel[bot]" <35613825+vercel[bot]@users.noreply.github.com> Date: Fri, 17 Jul 2026 02:51:44 +0000 Subject: [PATCH 2/3] Fix: The new `@sveltejs/kit/env` entry point (exporting `defineEnvVars`) is referenced by docs and JSDoc but is never wired into the package `exports` map or the type generation script, making `import { defineEnvVars } from '@sveltejs/kit/env'` throw `ERR_PACKAGE_PATH_NOT_EXPORTED`. This commit fixes the issue reported at packages/kit/package.json:106 ## Bug The PR adds a new module `packages/kit/src/exports/env/index.js` exporting `defineEnvVars`, and updates docs (`documentation/docs/20-core-concepts/70-environment-variables.md`, 8 usages) and JSDoc/type links (`public.d.ts`, `types/index.d.ts`) to instruct users to `import { defineEnvVars } from '@sveltejs/kit/env'`. However, the subpath was never registered: 1. **`packages/kit/package.json` `exports` map** had no `./env` entry. Node resolves subpath imports strictly against the `exports` field, so `import ... from '@sveltejs/kit/env'` throws `ERR_PACKAGE_PATH_NOT_EXPORTED` at runtime/build time. Concrete trigger: any consumer following the new docs example would fail immediately on import. 2. **`packages/kit/scripts/generate-dts.js` `modules` map** had no `'@sveltejs/kit/env'` entry, so `pnpm generate:types` did not emit a `declare module '@sveltejs/kit/env'` block. The docs link `@sveltejs-kit-env#defineEnvVars` and TS resolution both depend on that generated declaration. ## Fix - Added a `./env` entry to the `exports` map mirroring the `./hooks` convention: ```json "./env": { "types": "./types/index.d.ts", "import": "./src/exports/env/index.js" } ``` - Added `'@sveltejs/kit/env': 'src/exports/env/index.js'` to the `modules` map in `generate-dts.js`. - Regenerated `types/index.d.ts` (`node scripts/generate-dts.js`), which now contains the `declare module '@sveltejs/kit/env'` block exporting `defineEnvVars`. Co-authored-by: Vercel Co-authored-by: Rich-Harris --- packages/kit/package.json | 4 ++++ packages/kit/scripts/generate-dts.js | 1 + packages/kit/types/index.d.ts | 11 +++++++++++ 3 files changed, 16 insertions(+) diff --git a/packages/kit/package.json b/packages/kit/package.json index 893461599f32..14532af8fb09 100644 --- a/packages/kit/package.json +++ b/packages/kit/package.json @@ -133,6 +133,10 @@ "types": "./types/index.d.ts", "import": "./src/exports/hooks/index.js" }, + "./env": { + "types": "./types/index.d.ts", + "import": "./src/exports/env/index.js" + }, "./vite": { "types": "./types/index.d.ts", "import": "./src/exports/vite/index.js" diff --git a/packages/kit/scripts/generate-dts.js b/packages/kit/scripts/generate-dts.js index 75f000f90bbf..763240d9871c 100644 --- a/packages/kit/scripts/generate-dts.js +++ b/packages/kit/scripts/generate-dts.js @@ -5,6 +5,7 @@ await createBundle({ output: 'types/index.d.ts', modules: { '@sveltejs/kit': 'src/exports/public.d.ts', + '@sveltejs/kit/env': 'src/exports/env/index.js', '@sveltejs/kit/hooks': 'src/exports/hooks/index.js', '@sveltejs/kit/node': 'src/exports/node/index.js', '@sveltejs/kit/node/polyfills': 'src/exports/node/polyfills.js', diff --git a/packages/kit/types/index.d.ts b/packages/kit/types/index.d.ts index f30d2f718cc8..b5e0df31ca8a 100644 --- a/packages/kit/types/index.d.ts +++ b/packages/kit/types/index.d.ts @@ -3045,6 +3045,17 @@ declare module '@sveltejs/kit' { export {}; } +declare module '@sveltejs/kit/env' { + import type { EnvVarConfig } from '@sveltejs/kit'; + /** + * Utility for defining [environment variables](https://svelte.dev/docs/kit/environment-variables), + * which are made available via `$app/env/public` and `$app/env/private`. + * */ + export function defineEnvVars>>(variables: T): T; + + export {}; +} + declare module '@sveltejs/kit/hooks' { import type { EnvVarConfig, Handle } from '@sveltejs/kit'; /** From d90d2b8d095106dad63b574659d107862efa7008 Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Thu, 16 Jul 2026 22:52:19 -0400 Subject: [PATCH 3/3] docs --- documentation/docs/98-reference/15-@sveltejs-kit-env.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 documentation/docs/98-reference/15-@sveltejs-kit-env.md diff --git a/documentation/docs/98-reference/15-@sveltejs-kit-env.md b/documentation/docs/98-reference/15-@sveltejs-kit-env.md new file mode 100644 index 000000000000..c33e44376ae1 --- /dev/null +++ b/documentation/docs/98-reference/15-@sveltejs-kit-env.md @@ -0,0 +1,5 @@ +--- +title: @sveltejs/kit/env +--- + +> MODULE: @sveltejs/kit/env