feat: explicit environment variables#15934
Conversation
Ah yes - this solves my concerns around validate parsing/coercing too. Nice :) |
|
@f-elix still not completely sure I understand — for the Vercel example, if you need env vars locally you don't need to manage anything yourself you can just do For the 1Password example, what's the advantage of calling the CLI from inside As for Having said all that: if you do need to load variables directly inside import { defineEnvVars } from '@sveltejs/kit/hooks';
import * as v from 'valibot';
import { execSync } from 'child_process';
const mode = import.meta.env.MODE;
const value = (v: string | Promise<string>) => v.pipeAsync(v.unknown(), v.transformAsync(() => v));
export const variables = defineEnvVars({
POSTGRES_URL: {
// Could be a static value
schema: value('postgresql://...'),
// Can be derived from import.meta.env.MODE
schema: value(mode === 'production' ? 'postgresql://...' : 'local-db-url')
// The value can be async, so we can fetch the value from somewhere else
schema: value(vercel.environment.getSharedEnvVar({
id: "<id>",
teamId: "team_1a2b3c4d5e6f7g8h9i0j1k2l",
slug: "my-team-url-slug",
}));
// The 1Password CLI could be used like this, but it could be any CLI
schema: value(execSync(`op read op://${mode}/postgresurl`))
},
});We should probably also expose It's also straightforward to configure (or, if desired) load things in bulk if necessary: import { defineEnvVars } from '@sveltejs/kit/hooks';
import { systemEnvVars } from '@sveltejs/adapter-vercel/env'; // hypothetical!
import { load1PasswordEnvironment } from '$lib/server/1password';
import { dev } from '$app/env';
export const variables = defineEnvVars({
...systemEnvVars(), // VERCEL_URL etc
...load1PasswordEnvironment(dev ? 'development' : 'production'),
MY_OTHER_STUFF: {...}
}); |
|
Actually I take it back, we can't allow async validators right now as that would force In the meantime you can of course -schema: value(vercel.environment.getSharedEnvVar({
+schema: value(await vercel.environment.getSharedEnvVar({ |
|
Oh I see. I only saw To answer your question regarding calling a CLI or an SDK from env.ts (doesn't have to be Vercel, could be anything), its imo a cleaner and more flexible way than to hardcode that in a package.json script. You could have multiple environments (production, staging, tests, local dev, etc.) with different values, and that would become very messy to handle in package.json. In any case, I think I also wasn't clear with my So you can forget my first suggestion (the Does that make more sense to you? |
|
What would |
|
I think I explained this poorly. What I had in mind is a function that returns dotenv file contents as a string, e.g. That loader determines where the dotenv contents come from. The schema remains the source of truth for what variables exist, whether they are public/private/static, docs, validation, etc. The reason this seems useful to me is that it keeps I’m not sure whether this belongs in core, especially since there are details around precedence, async loading, build-time vs runtime behavior, and whether it should mutate process.env. But that was the shape I meant. loadEnv is probably also the wrong name — it would be more like defineEnvSource, loadDotenv, or something along those lines. |
|
Ah, I think I understand — so basically this, without the pointlessly hard-coded string? export const variables = defineEnvVars({
FOO: {...},
BAR: {...}
});
export const load = async () => `
FOO=123
BAR=456
`;I think it's a candidate for a future addition, though probably not part of this PR |
|
Yes exactly! But yeah agreed that its out of scope for this PR. Really looking forward to this one :) |
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 main, this PR will be updated. # Releases ## @sveltejs/kit@2.63.0 ### Minor Changes - feat: explicit env vars ([#15934](#15934)) ### Patch Changes - fix: remove check for svelte.config.js before running `sync` ([#15946](#15946)) - fix: generate a placeholder tsconfig.json to squelch sync-time warnings ([#15948](#15948)) - fix: allow use of `$app/env/public` in service workers ([#15950](#15950)) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
|
Great! It works with zod4 too. |
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/adapter-auto@8.0.0-next.0 ### Major Changes - breaking: require SvelteKit 3 ([#15506](#15506)) ### Patch Changes - Updated dependencies [[`fa335bd`](fa335bd), [`3031d89`](3031d89), [`cb9d416`](cb9d416), [`caf3a18`](caf3a18), [`4777827`](4777827), [`a2792e2`](a2792e2), [`ba36148`](ba36148), [`48e8710`](48e8710), [`e2f3075`](e2f3075), [`047d6a0`](047d6a0), [`87603d1`](87603d1), [`096962c`](096962c), [`d545970`](d545970), [`e2f3075`](e2f3075), [`d06affc`](d06affc), [`8af47eb`](8af47eb), [`e2f3075`](e2f3075), [`5c4d130`](5c4d130), [`3f11f35`](3f11f35), [`caf3a18`](caf3a18), [`8823037`](8823037), [`1d76212`](1d76212), [`0dc0548`](0dc0548), [`00d81fa`](00d81fa)]: - @sveltejs/kit@3.0.0-next.0 ## @sveltejs/adapter-cloudflare@8.0.0-next.0 ### Major Changes - breaking: upgrade `@cloudflare/workers-types` to 4.20260219.0 ([#15347](#15347)) - breaking: upgrade minimum `wrangler` version to ^4.67.0 ([#15347](#15347)) - breaking: remove `platform.context` in favour of `platform.ctx` ([#15347](#15347)) - breaking: require SvelteKit 3 ([#15506](#15506)) ### Patch Changes - chore: check the `WORKERS_CI` environment variable to determine if we're building for Cloudflare Workers ([#13733](#13733)) - Updated dependencies [[`fa335bd`](fa335bd), [`3031d89`](3031d89), [`cb9d416`](cb9d416), [`caf3a18`](caf3a18), [`4777827`](4777827), [`a2792e2`](a2792e2), [`ba36148`](ba36148), [`48e8710`](48e8710), [`e2f3075`](e2f3075), [`047d6a0`](047d6a0), [`87603d1`](87603d1), [`096962c`](096962c), [`d545970`](d545970), [`e2f3075`](e2f3075), [`d06affc`](d06affc), [`8af47eb`](8af47eb), [`e2f3075`](e2f3075), [`5c4d130`](5c4d130), [`3f11f35`](3f11f35), [`caf3a18`](caf3a18), [`8823037`](8823037), [`1d76212`](1d76212), [`0dc0548`](0dc0548), [`00d81fa`](00d81fa)]: - @sveltejs/kit@3.0.0-next.0 ## @sveltejs/adapter-netlify@7.0.0-next.0 ### Major Changes - chore: use `rolldown` for edge function bundling ([#15432](#15432)) - breaking: write output that conforms to the stable [Netlify Frameworks API](https://docs.netlify.com/build/frameworks/frameworks-api/). ([#15294](#15294)) Deploying and previewing with Netlify CLI now requires [v17.31.0](https://github.com/netlify/cli/releases/tag/v17.31.0) or later. Run `npm i -g netlify-cli@latest` to upgrade. - breaking: require SvelteKit 3 ([#15506](#15506)) - breaking: edge function build target is now `es2022` ([#15432](#15432)) ### Patch Changes - Updated dependencies [[`fa335bd`](fa335bd), [`3031d89`](3031d89), [`cb9d416`](cb9d416), [`caf3a18`](caf3a18), [`4777827`](4777827), [`a2792e2`](a2792e2), [`ba36148`](ba36148), [`48e8710`](48e8710), [`e2f3075`](e2f3075), [`047d6a0`](047d6a0), [`87603d1`](87603d1), [`096962c`](096962c), [`d545970`](d545970), [`e2f3075`](e2f3075), [`d06affc`](d06affc), [`8af47eb`](8af47eb), [`e2f3075`](e2f3075), [`5c4d130`](5c4d130), [`3f11f35`](3f11f35), [`caf3a18`](caf3a18), [`8823037`](8823037), [`1d76212`](1d76212), [`0dc0548`](0dc0548), [`00d81fa`](00d81fa)]: - @sveltejs/kit@3.0.0-next.0 ## @sveltejs/adapter-node@6.0.0-next.0 ### Major Changes - chore: migrate from rollup to rolldown ([#15297](#15297)) - breaking: require SvelteKit 3 ([#15506](#15506)) ### Patch Changes - Updated dependencies [[`fa335bd`](fa335bd), [`3031d89`](3031d89), [`cb9d416`](cb9d416), [`caf3a18`](caf3a18), [`4777827`](4777827), [`a2792e2`](a2792e2), [`ba36148`](ba36148), [`48e8710`](48e8710), [`e2f3075`](e2f3075), [`047d6a0`](047d6a0), [`87603d1`](87603d1), [`096962c`](096962c), [`d545970`](d545970), [`e2f3075`](e2f3075), [`d06affc`](d06affc), [`8af47eb`](8af47eb), [`e2f3075`](e2f3075), [`5c4d130`](5c4d130), [`3f11f35`](3f11f35), [`caf3a18`](caf3a18), [`8823037`](8823037), [`1d76212`](1d76212), [`0dc0548`](0dc0548), [`00d81fa`](00d81fa)]: - @sveltejs/kit@3.0.0-next.0 ## @sveltejs/adapter-static@4.0.0-next.0 ### Major Changes - breaking: require SvelteKit 3 ([#15506](#15506)) ### Patch Changes - Updated dependencies [[`fa335bd`](fa335bd), [`3031d89`](3031d89), [`cb9d416`](cb9d416), [`caf3a18`](caf3a18), [`4777827`](4777827), [`a2792e2`](a2792e2), [`ba36148`](ba36148), [`48e8710`](48e8710), [`e2f3075`](e2f3075), [`047d6a0`](047d6a0), [`87603d1`](87603d1), [`096962c`](096962c), [`d545970`](d545970), [`e2f3075`](e2f3075), [`d06affc`](d06affc), [`8af47eb`](8af47eb), [`e2f3075`](e2f3075), [`5c4d130`](5c4d130), [`3f11f35`](3f11f35), [`caf3a18`](caf3a18), [`8823037`](8823037), [`1d76212`](1d76212), [`0dc0548`](0dc0548), [`00d81fa`](00d81fa)]: - @sveltejs/kit@3.0.0-next.0 ## @sveltejs/adapter-vercel@7.0.0-next.0 ### Major Changes - chore: use `rolldown` for edge function bundling ([#15432](#15432)) - breaking: edge function build target is now `es2022` ([#15432](#15432)) ### Patch Changes - Updated dependencies [[`fa335bd`](fa335bd), [`3031d89`](3031d89), [`cb9d416`](cb9d416), [`caf3a18`](caf3a18), [`4777827`](4777827), [`a2792e2`](a2792e2), [`ba36148`](ba36148), [`48e8710`](48e8710), [`e2f3075`](e2f3075), [`047d6a0`](047d6a0), [`87603d1`](87603d1), [`096962c`](096962c), [`d545970`](d545970), [`e2f3075`](e2f3075), [`d06affc`](d06affc), [`8af47eb`](8af47eb), [`e2f3075`](e2f3075), [`5c4d130`](5c4d130), [`3f11f35`](3f11f35), [`caf3a18`](caf3a18), [`8823037`](8823037), [`1d76212`](1d76212), [`0dc0548`](0dc0548), [`00d81fa`](00d81fa)]: - @sveltejs/kit@3.0.0-next.0 ## @sveltejs/enhanced-img@1.0.0-next.0 ### Major Changes - breaking: require Node 22 or newer ([#12548](#12548)) ### Minor Changes - breaking: require Vite 8 and `vite-plugin-svelte` 7 ([#15542](#15542)) ## @sveltejs/kit@3.0.0-next.0 ### Major Changes - breaking: TypeScript 6 is now the minimum required version ([#15930](#15930)) - breaking: upgrade to cookie v1. Cookie names must now contain only ASCII characters ([#13386](#13386)) - breaking: require Node 22 or newer ([#12548](#12548)) - breaking: remove the `preloadStrategy` option. `modulepreload` will always be used ([#15256](#15256)) - breaking: default the cookie `path` option to `'/'` ([#15398](#15398)) - breaking: remove `@sveltejs/kit/node/polyfills` ([#15430](#15430)) - breaking: add `config.kit.output.linkHeaderPreload` to preload using the `Link` header ([#15939](#15939)) - breaking: require `@sveltejs/vite-plugin-svelte` v7 ([#15371](#15371)) - breaking: remove `createEntries` from the `Builder` object passed to adapter functions ([#15509](#15509)) - breaking: remove the deprecated CSRF `checkOrigin` option in favor of `trustedOrigins` ([#15437](#15437)) - breaking: the `delta` property now only exists for `popstate` navigation events ([#15522](#15522)) - breaking: remove deprecated `pragma` header in version polling for improved CORS support ([#15428](#15428)) - breaking: require Svelte 5.48.0 or newer ([#15371](#15371)) - chore: change `error`, `isHttpError`, `redirect`, and `isRedirect` to refer to public type instead of internal class ([#15250](#15250)) - breaking: require Vite 8. Provides new functionality even for existing Vite 8 users such as faster builds with Vite hook filters and more powerful SvelteKit adapters with the Vite environment API ([#15371](#15371)) - breaking: remove `data-sveltekit-*` option `'off'` in favour of `false` ([#15907](#15907)) ### Minor Changes - feat: resolve paths using the Vite config `root` option instead of `process.cwd()` to better support monorepo configurations such as Vitest workspaces ([#15469](#15469)) - chore: deprecate `Response` helpers in favor of platform-provided alternatives ([#15448](#15448)) - feat: explicit env vars ([#15934](#15934)) ### Patch Changes - fix: remove check for svelte.config.js before running `sync` ([#15946](#15946)) - fix: generate a placeholder tsconfig.json to squelch sync-time warnings ([#15948](#15948)) - chore: remove dependency on kleur ([#12548](#12548)) - chore: remove dependency on `set-cookie-parser` ([#15384](#15384)) - fix: allow use of `$app/env/public` in service workers ([#15950](#15950)) ## @sveltejs/package@3.0.0-next.0 ### Major Changes - breaking: require Node 22 or newer ([#12548](#12548)) ### Patch Changes - chore: remove dependency on kleur ([#12548](#12548)) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
…vars (#15971) When `experimental.explicitEnvironmentVariables` is enabled, `$app/environment` throws and apps import from `$app/env` instead. `$app/env` re-exports `version` from `internal.js` (`export const version = __SVELTEKIT_APP_VERSION__`), but unlike `$app/environment` it never references `import.meta.hot`, so Vite doesn't force its client to load. If `$app/env` is imported before the Vite client has loaded, `version` evaluates while the define is missing and the browser throws: ``` ReferenceError: __SVELTEKIT_APP_VERSION__ is not defined ``` This happens when `$app/env` is imported early, e.g. from `hooks.client.js`. Importing it from a route component is too late to hit it, since the client is already up by then, which is why it's intermittent. I ran into it in a real app after enabling `experimental.explicitEnvironmentVariables`. It came in with #15934, which moved `version` onto the `__SVELTEKIT_APP_VERSION__` define and added `import.meta.hot` to `$app/environment`, but not to the newly split `$app/env`. The fix mirrors `$app/environment`. I left that file's `import.meta.hot` in place to keep this minimal, though it's now redundant with this one. Added a regression test in `options-2`: an early `$app/env` import in `hooks.client.js` plus a load of the page. It fails on `main` (the app never finishes hydrating) and passes with this change. --- ### 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 - [x] This message body should clearly illustrate what problems it solves. - [x] 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: Tee Ming Chew <chewteeming01@gmail.com>
<!-- Explain the goal of the PR, why it is needed, and what has been changed to achieve that goal --> #15934 was created before Kit 2.62 got released, thus its docs updates naturally indicated 2.62 as a target version. However, 2.62 got released before merging this PR (or not including it). As a result, the "since version" is erroneous. This PR fixes this by bumping the numbers everywhere the original PR set them to 2.63, which actually includes the change. --- ### 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 - [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 - [ ] 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 - [x] Please ensure that 'Allow edits from maintainers' is checked. PRs without this option may be closed.
Today, environment variables are implicitly available: anything in
process.envcan be imported directly (as long as the name is a valid identifier) from$env/static/private, or accessed viaenvimported from$env/dynamic/private. Environment variables beginning withpublicPrefixare available from the public counterparts.This is... fine, but there is some room for improvement:
Hto begin importingHeader.svelte, my editor will helpfully suggest that I meantHOMEBREW_CELLARor something else improbableenv.BLAH), which feels weird. If for some reason you use both$env/dynamic/publicand$env/dynamic/privatein the same module, you will need to rename them since you can't have two imports calledenvThis PR presents an explicit alternative. Opt in by adding the following flag to your
svelte.config.js......and creating a
src/env.ts(orsrc/env.js) that exportsvariables:With those variables defined, we can import them via two new modules —
$app/env/privateand$app/env/public. As with existing server-only modules,$app/env/privatecannot be imported into code that can run in the client.Types are inferred from validators, where provided, and inline documentation is attached to the variables:
If environment variables are missing, the app errors on startup (or build, for
staticenv vars).The validators (and indeed the entire
src/envmodule) only ever run on the server. Public variables are sent to the client with the initial server rendered HTML, or (if the initial document is prerendered) by importing a generated module, the same as happens today.The
$app/environmentmodule is aliased as$app/env, to make everything feel a bit more cohesive. The goal is to remove$app/environmentand the four$env/*modules (and the associated configuration) in SvelteKit 3.TODO:
generateEnvModuleforadapter-static%sveltekit.env%with this rather than the existing env vars, where appropriatePlease don't delete this checklist! Before submitting the PR, please make sure you do the following:
Tests
pnpm testand lint the project withpnpm lintandpnpm checkChangesets
pnpm changesetand following the prompts. Changesets that add features should beminorand those that fix bugs should bepatch. Please prefix changeset messages withfeat:,fix:, orchore:.Edits