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 [email protected] (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: 96bac89

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

[tobias-electric]

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

Ran these to double check and format the markdown files via Prettier.

[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?