docs: clarify functionality of $env/* variables

[saibotsivad]

I spent a lot of time trying to understand the `$env/* variables and how they behave, the docs didn't really seem very fleshed out and I was confused. I wrote up a bunch of demo code to make sure I really understood the behaviour, and then realized that a little love in the docs would probably be appreciated.

All sample code has been run locally and validated as correct as of svelte@5.45.6 (using the npx sv create to make a minimal app). Anything that required validation between dev and prod I ran npm run build, editing the .env file as necessary, and then npm run preview to run.

The overall idea

Here's how I broke it down conceptually:

	Runtime	Buildtime
Private	$env/dynamic/private	$env/static/private
Public	$env/dynamic/public	$env/static/public

Private versus public:

• Whether or not it can be imported into client-side code.
• Filtering variables based on the publicPrefix/privatePrefix.

Runtime versus buildtime:

• Whether or not values change based on platform specifics.
• Whether variables make their way into bundled code.

---

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
  • Could not find an open issue about this,
• This message body should clearly illustrate what problems it solves.
• [ ] Ideally, include a test that fails without this PR but passes with it.
  • This PR is documentation only.

Tests

• [ ] Run the tests with pnpm test and lint the project with pnpm lint and pnpm check
  • This PR is documentation only, hopefully I don't need to do this 😅

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:.
  • I don't think this needs to appear in a changelog.

Edits

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 69865cf

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[mahyarmirrashed]

Agreed that it took me a while and trying/testing to fully figure it out. It's a similar concept though (might even be) to Vite's environment variable mechanism. So, if Vite has a page that fully deep dives on it, maybe it's better to link to there as well?

[sacrosanctic]

if Vite has a page that fully deep dives on it, maybe it's better to link to there as well?

sveltekit add's to it, so it needs its own docs

@saibotsivad This looks pretty good. Just a bit verbose.

Idea for maintainers: Instead of 4 pages, we could combine them into one page $env/* where we can describe their similiarities and differences.

[saibotsivad]

Combining them all into a single page would definitely clean up some duplication in the docs.

We would probably want to have redirects from e.g. kit/$env-dynamic-private --> kit/$env-star (or whatever the route would be).

I'm willing to rewrite to merge these docs, if maintainers think that's best, but I'd need coaching on how to do the redirects 😅

[elliott-with-the-longest-name-on-github]

I was trying to figure out why the docs preview deploy isn't working, and finally figured it out -- the script expects your fork to also be named kit 😆

I'm trying to test this out locally instead, will get back to you as soon as I can

[sacrosanctic]

I was trying to figure out why the docs preview deploy isn't working, and finally figured it out -- the script expects your fork to also be named kit 😆

sveltejs/svelte.dev#1712

[saibotsivad]

I was trying to figure out why the docs preview deploy isn't working, and finally figured it out -- the script expects your fork to also be named kit 😆

I don't know if it's easier, but I can re-fork to kit and reopen the PR? 🤷‍♂️ Whatever helps grease the skids.

[elliott-with-the-longest-name-on-github]

Nah, I did the sensible thing and fixed the issue upstream. Merging main now and we should be back on the rails!

[svelte-docs-bot]

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

[elliott-with-the-longest-name-on-github]

Sorry to send 29 comments, there are just some stylistic issues and some too-repetitive content. It looks good, though! Most of these suggestions you can probably just "add to batch" and commit at once, though the link ones you'll have to actually fix

[elliott-with-the-longest-name-on-github]

Suggested change

	| Private | `$env/dynamic/private` | [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private) |
	| Private | [`$env/dynamic/private`](https://svelte.dev/docs/kit/$env-dynamic-private) | [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private) |

[elliott-with-the-longest-name-on-github]

I know this is the current page but visually it's kind of confusing to have the others all be links and this one not

[elliott-with-the-longest-name-on-github]

Suggested change

	- This module (and [`$env/static/private`](https://svelte.dev/docs/kit/$env-static-private)) cannot be imported into client-side code.
	- This module cannot be imported into client-side code

[elliott-with-the-longest-name-on-github]

Suggested change

	For example, suppose the runtime environment variables were set like this:
	For example, given the following runtime environment:

[elliott-with-the-longest-name-on-github]

Suggested change

	If the `publicPrefix` is set to `PUBLIC_` and the `privatePrefix` is not set (the default behaviour):
	With the default `publicPrefix` and `privatePrefix`:

[elliott-with-the-longest-name-on-github]

Add the link here too (on all four pages)

[elliott-with-the-longest-name-on-github]

Suggested change

	- **Only** variables that begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to `PUBLIC_`) are included.
	- **Only** variables that begin with [`config.kit.env.publicPrefix`](https://svelte.dev/docs/kit/configuration#env) (which defaults to `PUBLIC_`) are included

[elliott-with-the-longest-name-on-github]

Suggested change

	For example, suppose the environment variables were set like this during build:
	For example, given the following buildtime environment:

[elliott-with-the-longest-name-on-github]

Suggested change

	Assuming the `publicPrefix` is set to `PUBLIC_` and the `privatePrefix` is not set (the default behaviour), this is what would happen at runtime, even if the environment variables at runtime are different:
	With the default `publicPrefix` and `privatePrefix`:

[elliott-with-the-longest-name-on-github]

Suggested change

	console.log(ENVIRONMENT); // => undefined, throws error during build
	console.log(ENVIRONMENT); // => throws error during build

[elliott-with-the-longest-name-on-github]

Suggested change

	```
	```
	The above values will be the same _even if_ different values for `ENVIRONMENT` or `PUBLIC_BASE_URL` are set at runtime, as they are statically replaced in your code with their build-time values.

[teemingc]

.