Improve plugin docs

apps/playgrounds/vite/README.md

@@ -115,6 +115,6 @@ For more information, see the [@arkenv/vite-plugin documentation](https://arkenv
 
 2. **Automatic Filtering**: The plugin automatically filters the schema to only expose `VITE_*` prefixed variables to the client, preventing server-only variables from leaking into the bundle.
 
-3. **Type Safety**: With the `vite-env.d.ts` setup, `import.meta.env` is fully typesafe with autocomplete and type checking.
+3. **Typesafety**: With the `vite-env.d.ts` setup, `import.meta.env` is fully typesafe with autocomplete and type checking.
 
 4. **Build-Time Validation**: Missing or invalid environment variables will cause the dev server to fail to start and production builds to fail with clear error messages.

apps/playgrounds/vite/src/vite-env.d.ts

@@ -19,3 +19,7 @@ interface ViteTypeOptions {
 // Now import.meta.env is totally typesafe and based on your `Env` schema definition
 // Only VITE_* prefixed variables will be included (PORT is excluded)
 interface ImportMetaEnv extends ImportMetaEnvAugmented {}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv;
+}

apps/www/bin/twoslash-mdx.ts

@@ -14,7 +14,8 @@ const content = fs.readFileSync(mdxPath, "utf8");
 // which contains compilerOptions, extraFiles, etc.
 const options = arktypeTwoslashOptions.twoslashOptions;
 
-const codeBlockRegex = /```(ts|js) twoslash(?:.*)\r?\n([\s\S]*?)\r?\n```/g;
+const codeBlockRegex =
+	/```(ts|tsx|js|jsx) twoslash(?:.*)\r?\n([\s\S]*?)\r?\n```/g;
 let blockIndex = 1;
 
 for (const match of content.matchAll(codeBlockRegex)) {

apps/www/content/docs/bun-plugin/index.mdx

@@ -1,21 +1,25 @@
 ---
 title: Introduction
 icon: Album
+description: The ArkEnv plugin for Bun lets you validate environment variables at build-time and runtime with ArkEnv.
 ---
 
-## What is this?
+> [!IMPORTANT]
+> This plugin requires [ArkType](https://arktype.io) to be installed.
 
-The ArkEnv plugin for Bun lets you validate environment variables at build-time and runtime with ArkEnv.
+## Quickstart
 
-It supports a **simple setup** for most projects, automatically discovering your schema from `./src/env.ts` or `./env.ts`.
+### 1. Installation
 
-## Usage
+```package-install
+@arkenv/bun-plugin arkenv
+```
 
-### Simple setup (recommended)
+### 2. Configure Plugin
 
 The simple setup automatically discovers your schema from `src/env.ts` or `env.ts`. This requires configuration in **both** `bunfig.toml` (for `Bun.serve`) and your build script (for `Bun.build`).
 
-#### 1. Create your schema
+#### Create your schema
 
 ```ts title="src/env.ts" twoslash
 import { type } from "arkenv";
@@ -26,14 +30,14 @@ export default type({
 });
 ```
 
-#### 2. Configure for Bun.serve (dev mode)
+#### Configure for Bun.serve (dev mode)
 
 ```toml title="bunfig.toml"
 [serve.static]
 plugins = ["@arkenv/bun-plugin"]
 ```
 
-#### 3. Configure for Bun.build (build mode)
+#### Configure for Bun.build (build mode)
 
 ```ts title="build.ts"
 import arkenv from "@arkenv/bun-plugin";
@@ -45,11 +49,35 @@ await Bun.build({
 });
 ```
 
-### Advanced setup
+### 3. Add Typesafety
+
+To make `process.env` fully typesafe, see the [Typing process.env](/docs/bun-plugin/typing-process-env) guide to complete your setup.
+
+### 4. Use in your code
+
+You can now use `process.env` with full typesafety and autocompletion throughout your application.
+
+```tsx title="src/App.tsx" twoslash
+// @filename: bun-env.d.ts
+/// <reference types="bun-types" />
+type ProcessEnvAugmented = {
+	BUN_PUBLIC_API_URL: string
+}
+declare namespace NodeJS {
+	interface ProcessEnv extends ProcessEnvAugmented {}
+}
+
+// @filename: App.tsx
+// ---cut---
+const apiUrl = process.env.BUN_PUBLIC_API_URL;
+//      ^?
+```
+
+## Custom schema location
 
 If you need to customize the schema location or prefer explicit configuration:
 
-#### For Bun.build
+### For Bun.build
 
 Pass your schema directly to the plugin function:
 
@@ -69,7 +97,7 @@ await Bun.build({
 });
 ```
 
-#### For Bun.serve
+### For Bun.serve
 
 Create a custom plugin file and reference it in `bunfig.toml`:
 
@@ -90,48 +118,42 @@ export default arkenv(Env);
 plugins = ["./plugins/arkenv.ts"]
 ```
 
-### Using Standard Schema validators (Zod, Valibot)
+## Using Standard Schema validators (Zod, Valibot)
 
 This plugin uses ArkType for validation, which natively supports Standard Schema. You can freely mix ArkType DSL strings with Zod or Valibot validators in the same schema - no extra configuration needed.
 
-```ts title="build.ts"
-import arkenv from "@arkenv/bun-plugin";
+> [!NOTE]
+> When using external validators like Zod or Valibot, you must install them separately. For example, to use the `z` symbol from `"zod"` shown below, run `npm install zod` (or use `valibot` instead).
+
+```ts title="src/env.ts" twoslash
 import { type } from "arkenv";
 import { z } from "zod";
 
-await Bun.build({
-  entrypoints: ["./app.tsx"],
-  outdir: "./dist",
-  plugins: [
-    arkenv(type({
-      BUN_PUBLIC_API_URL: z.url(),
-      BUN_PUBLIC_DEBUG: "boolean",
-    }))
-  ],
+export default type({
+  BUN_PUBLIC_API_URL: z.string().url(),
+  BUN_PUBLIC_DEBUG: "boolean",
 });
 ```
 
-> [!IMPORTANT]
-> This plugin requires [ArkType](https://arktype.io) to be installed.
->
-> For a zero-ArkType setup, use [arkenv/standard](/docs/arkenv/standard) directly in your app code instead.
->
-> See [Standard Schema validators](/docs/arkenv/integrations/standard-schema) for details.
+```tsx title="src/App.tsx" twoslash
+// @filename: bun-env.d.ts
+/// <reference types="bun-types" />
+type ProcessEnvAugmented = {
+	BUN_PUBLIC_API_URL: string
+	BUN_PUBLIC_DEBUG: boolean
+}
+declare namespace NodeJS {
+	interface ProcessEnv extends ProcessEnvAugmented {}
+}
+
+// @filename: App.tsx
+// ---cut---
+const apiUrl = process.env.BUN_PUBLIC_API_URL;
+//      ^?
+```
 
 ## Features
 
 - **Static Analysis**: Automatically replaces `process.env.VARIABLE` with validated values during the build.
 - **Typesafety**: Ensures your code only accesses variables defined in your schema.
-- **Secure Defaults**: Only exposes variables prefixed with `BUN_PUBLIC_` to the client bundle. `NODE_ENV` is also exposed when defined in your schema. You can customize this prefix by setting the `env` option in your `Bun.build()` configuration (e.g., `env: "MY_PUBLIC_*"` to use `MY_PUBLIC_` instead). See [Bun's bundler documentation](https://bun.sh/docs/bundler#env) for more details.
-
-## Installation
-
-```package-install
-@arkenv/bun-plugin arkenv
-```
-
-If you intend to use the default validator, you should also install `arktype`:
-
-```package-install
-arktype
-```
+- **Secure Defaults**: Only exposes variables prefixed with `BUN_PUBLIC_` to the client bundle. `NODE_ENV` is also exposed when defined in your schema. You can customize this prefix by setting the `env` option in your `Bun.build()` configuration.

apps/www/content/docs/bun-plugin/typing-process-env.mdx

@@ -9,6 +9,9 @@ With ArkEnv, this can be typesafe with the one-time setup below. After this, eac
 
 ## Setup
 
+> [!TIP]
+> This guide is the final step to complete the [Simple setup](/docs/bun-plugin) from the introduction page.
+
 > [!IMPORTANT]
 > You must have the core `arkenv` package installed as a dependency in your project. See [ArkEnv quickstart](/docs/arkenv/quickstart) for instructions.
 
@@ -60,7 +63,7 @@ The `ProcessEnvAugmented` type:
 
 1. Extracts the inferred type from your schema (the result of `type()` from arkenv)
 2. Filters to only include variables matching the Bun prefix (defaults to `"BUN_PUBLIC_"`) and `NODE_ENV`
-3. Makes them available on `process.env` with full type safety
+3. Makes them available on `process.env` with full typesafety
 
 Server-only variables (like `PORT`) are automatically excluded from the client bundle and won't appear in the augmented `process.env` type.
 

apps/www/content/docs/vite-plugin/arkenv-in-viteconfig.mdx

@@ -5,13 +5,14 @@ icon: Wrench
 
 import { Globe } from "lucide-react";
 
+> [!NOTE]
+> This is an **advanced setup** for when you need to access environment variables *inside* your `vite.config.ts` (e.g., to set `server.port`). For standard application usage, see the [Introduction](/docs/vite-plugin).
 
 Vite doesn't automatically load `.env*` files when evaluating your `vite.config.ts` - those variables are only available later in your application code via `import.meta.env`. If you need environment variables in your config (like setting `server.port` or conditionally enabling plugins), you'll need to load them manually using Vite's `loadEnv` helper.
 
 > [!IMPORTANT]
 > You must have the core `arkenv` package installed as a dependency in your project. See [ArkEnv quickstart](/docs/arkenv/quickstart) for instructions.
 
-
 Here's how to validate those variables with ArkEnv. The key is defining your schema *once* with ArkEnv's `type()` and reusing it for both server-side config variables and client-exposed `VITE_*` variables:
 
 ```ts title="vite.config.ts" twoslash

apps/www/content/docs/vite-plugin/index.mdx

@@ -1,26 +1,78 @@
 ---
 title: Introduction
 icon: Album
+description: The ArkEnv plugin for Vite lets you validate environment variables at build-time with ArkType.
 ---
 
-## What is this?
+> [!IMPORTANT]
+> This plugin requires [ArkType](https://arktype.io) to be installed.
+
+## Quickstart
 
-The ArkEnv plugin for Vite lets you validate environment variables at build-time with ArkEnv.
+### 1. Installation
+
+```package-install
+@arkenv/vite-plugin arkenv
+```
+
+### 2. Configure Plugin
+
+Define your schema as an exported constant in `vite.config.ts`. This allows the schema to be imported for typesafety in other files.
 
 ```ts title="vite.config.ts" twoslash
 import arkenv from "@arkenv/vite-plugin";
+import { type } from "arkenv";
 import { defineConfig } from "vite";
 
+export const Env = type({
+	PORT: "number.port",
+	VITE_MY_VAR: "string"
+});
+
 export default defineConfig({
-  plugins: [
-    arkenv({
-      PORT: "number.port",
-      VITE_MY_VAR: "string",
-    }),
-  ],
+	plugins: [arkenv(Env)]
 });
 ```
 
+### 3. Add Typesafety
+
+To make `import.meta.env` fully typesafe, add the following to `src/vite-env.d.ts`:
+
+```ts title="src/vite-env.d.ts"
+/// <reference types="vite/client" />
+
+type ImportMetaEnvAugmented = import("@arkenv/vite-plugin").ImportMetaEnvAugmented<
+	typeof import("../vite.config").Env
+>;
+
+interface ImportMetaEnv extends ImportMetaEnvAugmented {}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv;
+}
+```
+
+### 4. Use in your code
+
+You can now use `import.meta.env` with full typesafety and autocompletion throughout your application.
+
+```tsx title="src/App.tsx" twoslash
+// @filename: vite-env.d.ts
+/// <reference types="vite/client" />
+type ImportMetaEnvAugmented = {
+	VITE_MY_VAR: string
+}
+interface ImportMetaEnv extends ImportMetaEnvAugmented {}
+interface ImportMeta {
+	readonly env: ImportMetaEnv
+}
+
+// @filename: App.tsx
+// ---cut---
+const apiUrl = import.meta.env.VITE_MY_VAR;
+//      ^?
+```
+
 With this setup, if any environment variable is missing or invalid, your dev server won't start and your production build will fail with an error:
 
 ```bash title="Terminal"
@@ -29,43 +81,56 @@ ArkEnvError: Errors found while validating environment variables
   PORT must be an integer between 0 and 65535 (was "hello")
 ```
 
+> [!TIP]
+> For more details on advanced typing options, see [Typing import.meta.env](/docs/vite-plugin/typing-import-meta-env).
+
 ## Using Standard Schema validators (Zod, Valibot)
 
 This plugin uses ArkType for validation, which natively supports Standard Schema. You can freely mix ArkType DSL strings with Zod or Valibot validators in the same schema - no extra configuration needed.
 
-```ts title="vite.config.ts"
-import { defineConfig } from "vite";
+> [!NOTE]
+> When using Standard Schema validators, you must install the validator package separately. For example, the code below imports `z` from `"zod"` and uses `type({ ... })` with Zod validators - install with `npm install zod` (or use `valibot` instead).
+
+```ts title="vite.config.ts" twoslash
 import arkenv from "@arkenv/vite-plugin";
+import { type } from "arkenv";
+import { defineConfig } from "vite";
 import { z } from "zod";
 
+export const Env = type({
+	VITE_API_URL: z.string().url(),
+	VITE_API_KEY: z.string().min(1),
+	VITE_DEBUG: "boolean"
+});
+
 export default defineConfig({
-  plugins: [
-    arkenv({
-      VITE_API_URL: z.url(),
-      VITE_API_KEY: z.string().min(1),
-      VITE_DEBUG: "boolean",
-    }),
-  ],
+	plugins: [arkenv(Env)]
 });
 ```
 
-> [!IMPORTANT]
-> This plugin requires [ArkType](https://arktype.io) to be installed.
->
-> For a zero-ArkType setup, use [arkenv/standard](/docs/arkenv/standard) directly in your app code instead.
->
-> See [Standard Schema validators](/docs/arkenv/integrations/standard-schema) for details.
-
-## Installation
-
-```package-install
-@arkenv/vite-plugin
+```tsx title="src/App.tsx" twoslash
+// @filename: vite-env.d.ts
+/// <reference types="vite/client" />
+type ImportMetaEnvAugmented = {
+	VITE_API_URL: string
+	VITE_API_KEY: string
+	VITE_DEBUG: boolean
+}
+interface ImportMetaEnv extends ImportMetaEnvAugmented {}
+interface ImportMeta {
+	readonly env: ImportMetaEnv
+}
+
+// @filename: App.tsx
+// ---cut---
+const apiUrl = import.meta.env.VITE_API_URL;
+//      ^?
 ```
 
-If you intend to use `arkenv` (requires ArkType), also install `arktype`:
+For advanced workflows, see [using ArkEnv in Vite config](/docs/vite-plugin/arkenv-in-viteconfig).
 
-```package-install
-arktype
-```
+## Features
 
-For some workflows (including [using ArkEnv in Vite config](/docs/vite-plugin/arkenv-in-viteconfig) and [typing import.meta.env](/docs/vite-plugin/typing-import-meta-env)), a dedicated `arkenv` installation is needed. See [ArkEnv quickstart](/docs/arkenv/quickstart) for more instructions.
+- **Static Analysis**: Automatically replaces `import.meta.env.VARIABLE` with validated values during the build.
+- **Typesafety**: Ensures your code only accesses variables defined in your schema.
+- **Secure Defaults**: Only exposes variables prefixed with `VITE_` to the client bundle. `NODE_ENV` is also exposed when defined in your schema.