clarify docs around envs in vite (#196)

Author: theoephraim

.changeset/short-squids-learn.md

@@ -0,0 +1,2 @@
+---
+---

example-monorepo/packages/astro-example/.astro/content-assets.mjs

@@ -5,8 +5,8 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "tsc && vite build",
-    "preview": "vite preview"
+    "build": "APP_ENV=production tsc && vite build",
+    "preview": "APP_ENV=production vite preview"
   },
   "devDependencies": {
     "@varlock/vite-integration": "workspace:*",

example-monorepo/packages/astro-example/.astro/content-modules.mjs

@@ -5,8 +5,8 @@
   "type": "module",
   "scripts": {
     "dev": "vite",
-    "build": "vue-tsc -b && vite build",
-    "preview": "vite preview"
+    "build": "APP_ENV=production vue-tsc -b && vite build",
+    "preview": "APP_ENV=production vite preview"
   },
   "dependencies": {
     "vue": "^3.5.18"

example-monorepo/packages/astro-example/.astro/data-store.json

@@ -114,12 +114,21 @@ To enable type-safety and IntelliSense for your env vars, enable the [`@generate
 
 ## Managing multiple environments
 
-Varlock can load multiple _environment-specific_ `.env` files (e.g., `.env.development`, `.env.preview`, `.env.production`).
-
-By default, Astro relies on Vite's [`MODE` flag](https://vite.dev/guide/env-and-mode.html#modes) to determine which env file(s) to load.
-
-With varlock, instead you set your own environment flag using the [`@currentEnv` root decorator](/reference/root-decorators/#currentEnv), e.g. `APP_ENV`. See the [environments guide](/guides/environments) for more information.
+Varlock can load multiple _environment-specific_ `.env` files (e.g., `.env.development`, `.env.preview`, `.env.production`) by using the [`@currentEnv` root decorator](/reference/root-decorators/#currentenv). **This is different than Astro/Vite's default behaviour, which relies on it's own [`MODE` flag](https://vite.dev/guide/env-and-mode.html#modes).**
+
+Usually this env var will be defaulted to something like `development` in your `.env.schema` file, and you can override it by overriding the value when running commands - for example `APP_ENV=production vite build`. For a JavaScript based project, this will often be done in your `package.json` scripts.
+
+```diff lang="json" title="package.json" add=/APP_ENV=[a-z]+/
+{
+  "scripts": {
+    "dev": "astro dev",
+    "build": "APP_ENV=production astro build",
+    "preview": "APP_ENV=production vite preview",
+  }
+}
+```
 
+In some cases, you could also set the current environment value based on other vars already injected by your CI platform, like the current branch name. See the [environments guide](/guides/environments) for more information.
 
 ## Managing sensitive config values
 

example-monorepo/packages/astro-example/.astro/settings.json

@@ -7,14 +7,13 @@ import ExecCommandWidget from '@/components/ExecCommandWidget.astro';
 
 There are a few different ways to integrate Varlock into a JavaScript / Node.js application.
 
-Some tools/frameworks may require an additional package, or have more specific instructions. The following integrations/guides are available, with more to come soon:
-- [Next.js](/integrations/nextjs)
+Some tools/frameworks may require an additional package, or have more specific instructions. Check the Integrations section in the navigation for more details.
 
 **Want to help us build more integrations? Join our <a href={process.env.PUBLIC_DISCORD_URL}>Discord</a>!**
 
 ## Node.js - `varlock/auto-load`
 
-The best way to integrate varlock into a Node.js application (⚠️ version 22 or higher) is to import the `varlock/auto-load` module. This uses `execSync` to call out to the varlock CLI, sets resolved env vars into `process.env`, and initializes varlock's runtime code, including:
+The best way to integrate varlock into a plain Node.js application (⚠️ version 22 or higher) is to import the `varlock/auto-load` module. This uses `execSync` to call out to the varlock CLI, sets resolved env vars into `process.env`, and initializes varlock's runtime code, including:
 
 - varlock's `ENV` object
 - log redaction (if enabled)
@@ -55,6 +54,18 @@ In `package.json` scripts, calling `varlock` directly will work, as your package
 
 Even when using a deeper integration for your code, you may still need to use `varlock run` when calling external scripts/tools, like database migrations, to pass along resolved env vars.
 
+:::tip[Setting the current environment]
+Varlock can load multiple environment-specific `.env` files (e.g., `.env.development`, `.env.production`) by using the [`@currentEnv` root decorator](/reference/root-decorators/#currentenv) to specify which env var will set the current environment.
+
+If not using the default (usually `development`), you'll want to pass it in as an environment variable when running your command.
+
+```bash
+APP_ENV=production varlock run -- node index.js
+```
+
+See the [environments guide](/guides/environments) for more information about how to set the current environment.
+:::
+
 
 
 ## Front-end frameworks