(v1) Internal vs. Published Packages Strategy for Build-time and Runtime Code

.changeset/epg3nspi.md

@@ -0,0 +1,33 @@
+---
+"@arkenv/nextjs": major
+"@arkenv/nuxt": major
+"@arkenv/vite-plugin": major
+"@arkenv/bun-plugin": major
+---
+
+#### Move `arkenv` to peer dependencies in framework plugins
+
+Framework plugins no longer declare `arkenv` as a regular dependency. `arkenv` is now declared as a `peerDependency` with a caret range (`^1.0.0-alpha.1`), ensuring a single shared instance across all plugins and the host application.
+
+This change prevents duplicate instances of `arkenv` in `node_modules`, which could break ArkType structural typing and schema validation at runtime.
+
+Plugins affected:
+
+- `@arkenv/nextjs`
+- `@arkenv/nuxt`
+- `@arkenv/vite-plugin`
+- `@arkenv/bun-plugin`
+
+Before:
+
+```bash
+npm install @arkenv/nextjs
+```
+
+After:
+
+```bash
+npm install arkenv @arkenv/nextjs
+```
+
+**BREAKING CHANGE:** Users must now install `arkenv` alongside the plugin. Previously, `arkenv` was automatically pulled in as a regular dependency.

apps/www/content/docs/arkenv/examples.mdx

@@ -8,31 +8,9 @@ import { SiGithub as GitHub } from "@icons-pack/react-simple-icons";
 
 Use the [ArkEnv CLI](/docs/cli) to bootstrap an example with your favorite tooling.
 
-<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>
-  <Tab value="npm">
-    ```bash
-    npx @arkenv/cli@latest init --example <example-name>
-    ```
-  </Tab>
-
-  <Tab value="pnpm">
-    ```bash
-    pnx @arkenv/cli@latest init --example <example-name>
-    ```
-  </Tab>
-
-  <Tab value="yarn">
-    ```bash
-    yarn dlx @arkenv/cli@latest init --example <example-name>
-    ```
-  </Tab>
-
-  <Tab value="bun">
-    ```bash
-    bunx @arkenv/cli@latest init --example <example-name>
-    ```
-  </Tab>
-</Tabs>
+```npm
+npx @arkenv/cli@latest init --example <example-name>
+```
 
 <include cwd>../../examples/README.md#examples</include>
 

apps/www/content/docs/arkenv/index.mdx

@@ -6,6 +6,7 @@ description: Introducing ArkEnv, an environment variable validator that stays ou
 At its core, ArkEnv is a single export that creates a ready-to-use, typesafe environment variable object:
 
 ```ts twoslash
+// @noErrors
 import arkenv from "arkenv";
 
 const env = arkenv({
@@ -19,7 +20,10 @@ const env = arkenv({
 const host = env.HOST;
 const port = env.PORT;
 const nodeEnv = env.NODE_ENV;
-const debugging = env.DEBUGGING;
+
+// Type "env." to see autocomplete
+const debugging = env.
+//                    ^|
 ```
 
 > ArkEnv defaults to [ArkType](https://arktype.io/) notation, the closest match to TypeScript syntax for editor-to-runtime typesafety. You can also use any [Standard Schema](https://standardschema.dev/schema) validator, including Zod, Valibot, and Typia.

apps/www/content/docs/arkenv/integrations/ai/skills.mdx

@@ -9,31 +9,9 @@ Skills give AI assistants like Claude Code on-demand procedural knowledge about
 
 ## Installation
 
-<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>
-  <Tab value="npm">
-    ```bash
-    npx skills add yamcodes/arkenv
-    ```
-  </Tab>
-
-  <Tab value="pnpm">
-    ```bash
-    pnx skills add yamcodes/arkenv
-    ```
-  </Tab>
-
-  <Tab value="yarn">
-    ```bash
-    yarn dlx skills add yamcodes/arkenv
-    ```
-  </Tab>
-
-  <Tab value="bun">
-    ```bash
-    bunx skills add yamcodes/arkenv
-    ```
-  </Tab>
-</Tabs>
+```npm
+npx skills add yamcodes/arkenv
+```
 
 This installs the ArkEnv skill into your project. Once installed, your AI assistant automatically loads it when working with ArkEnv schemas.
 

apps/www/content/docs/arkenv/options.mdx

@@ -9,9 +9,15 @@ The second argument to `arkenv()` is an optional configuration object.
 All options listed below apply to both `arkenv` (ArkType mode) and `arkenv/standard` (Standard Schema mode).
 :::
 
-## `env`
+## Configuration options
 
-The environment variables to parse. Defaults to `process.env`.
+<AutoTypeTable path="../../packages/arkenv/src/create-env.ts" name="ArkEnvConfig" />
+
+## Examples
+
+### Custom env source
+
+You can pass a custom object instead of `process.env`. This is particularly useful in environments like Cloudflare Workers where variables are passed via a context object, or when testing.
 
 ```ts twoslash
 import arkenv from "arkenv";
@@ -22,9 +28,9 @@ const env = arkenv(
 );
 ```
 
-## `coerce`
+### Disabling coercion
 
-Whether to coerce environment variables to their defined types. Defaults to `true`.
+By default, ArkEnv automatically coerces string environment variables to numbers or booleans if the schema requires it. You can disable this behavior:
 
 ```ts twoslash
 import arkenv from "arkenv";
@@ -37,20 +43,9 @@ const env = arkenv(
 
 See the [coercion docs](/docs/arkenv/coercion) for more details.
 
-## `onUndeclaredKey`
-
-Control how ArkEnv handles environment variables that are not defined in your schema. Defaults to `"delete"`.
+### Custom array format
 
-- `"delete"` — Undeclared keys are allowed on input but stripped from the output.
-- `"ignore"` — Undeclared keys are allowed and preserved in the output.
-- `"reject"` — Undeclared keys will cause validation to fail.
-
-## `arrayFormat`
-
-The format to use for array parsing when coercion is enabled. Defaults to `"comma"`.
-
-- `"comma"` — Strings are split by comma and trimmed.
-- `"json"` — Strings are parsed as JSON.
+When coercion is enabled, you can specify how array strings are parsed.
 
 ```ts twoslash
 import arkenv from "arkenv";
@@ -61,11 +56,9 @@ const env = arkenv(
 );
 ```
 
-## `emptyAsUndefined`
-
-Whether to treat empty strings (`""`) as `undefined` before validation. Defaults to `false`.
+### Empty strings as undefined
 
-When enabled, an environment variable set to an empty value (e.g., `PORT=` in a `.env` file) will be treated as if it were missing, allowing defaults to apply and preventing validation errors for numeric or boolean types.
+When `emptyAsUndefined` is enabled, an environment variable set to an empty value (e.g., `PORT=` in a `.env` file) will be treated as if it were missing. This allows defaults to apply and prevents validation errors for numeric or boolean types.
 
 ```ts twoslash
 import arkenv from "arkenv";

apps/www/content/docs/arkenv/quickstart.mdx

@@ -11,93 +11,63 @@ ArkEnv is tested on [**Next.js** **16.x**](https://github.com/yamcodes/arkenv/tr
 
 The easiest way to get started is with the [ArkEnv CLI](/docs/cli). It automatically configures ArkEnv for your project, installs dependencies, and scaffolds your initial schema.
 
-<Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>
-  <Tab value="npm">
-    ```bash
-    npx @arkenv/cli@latest init
-    ```
-  </Tab>
-
-  <Tab value="pnpm">
-    ```bash
-    pnx @arkenv/cli@latest init
-    ```
-  </Tab>
-
-  <Tab value="yarn">
-    ```bash
-    yarn dlx @arkenv/cli@latest init
-    ```
-  </Tab>
-
-  <Tab value="bun">
-    ```bash
-    bunx @arkenv/cli@latest init
-    ```
-  </Tab>
-</Tabs>
+```npm
+npx @arkenv/cli@latest init
+```
 
 <Accordions>
   <Accordion title="Manual Installation">
-    <Steps>
-      <Step>
-        ### Install ArkEnv
+    ### Install ArkEnv [step] [!toc]
 
-        <Accordions defaultValue="Install ArkEnv + ArkType (recommended) + Plugins (optional)">
-          <Accordion title="Install ArkEnv + ArkType (recommended) + Plugins (optional)">
-            ArkEnv works best when paired with [ArkType](https://arktype.io):
+    <Accordions defaultValue="Install ArkEnv + ArkType (recommended) + Plugins (optional)">
+      <Accordion title="Install ArkEnv + ArkType (recommended) + Plugins (optional)">
+        ArkEnv works best when paired with [ArkType](https://arktype.io):
 
-            ```package-install
-            arkenv arktype
-            ```
+        ```package-install
+        arkenv arktype
+        ```
 
-            If you're using Vite, see [ArkEnv for Vite](/docs/vite-plugin).
+        If you're using Vite, see [ArkEnv for Vite](/docs/vite-plugin).
 
-            If you're using Bun, see [ArkEnv for Bun](/docs/bun-plugin).
-          </Accordion>
+        If you're using Bun, see [ArkEnv for Bun](/docs/bun-plugin).
+      </Accordion>
 
-          <Accordion title="Install ArkEnv only">
-            ```package-install
-            arkenv
-            ```
+      <Accordion title="Install ArkEnv only">
+        ```package-install
+        arkenv
+        ```
 
-            Import from [arkenv/standard](/docs/arkenv/standard) to use ArkEnv without ArkType.
-          </Accordion>
-        </Accordions>
-      </Step>
+        Import from [arkenv/standard](/docs/arkenv/standard) to use ArkEnv without ArkType.
+      </Accordion>
+    </Accordions>
 
-      <Step>
-        ### Configure TypeScript (recommended)
+    ### Configure TypeScript (recommended) [step] [!toc]
 
-        ArkEnv expects **TypeScript >= 5.1** and `strict` mode in your `tsconfig.json`.
+    ArkEnv expects **TypeScript >= 5.1** and `strict` mode in your `tsconfig.json`.
 
-        You're also expected to use a [modern TypeScript module resolution](https://www.typescriptlang.org/tsconfig/#moduleResolution).
+    You're also expected to use a [modern TypeScript module resolution](https://www.typescriptlang.org/tsconfig/#moduleResolution).
 
-        ```json title="tsconfig.json"
-        // [!code word:config]
-        {
-          "compilerOptions": {
-            "strict": true, // [!code focus]
-            "moduleResolution": "bundler" // [!code focus] or "node16" / "nodenext"
-          }
-        }
-        ```
+    ```json title="tsconfig.json"
+    // [!code word:config]
+    {
+      "compilerOptions": {
+        "strict": true, // [!code focus]
+        "moduleResolution": "bundler" // [!code focus] or "node16" / "nodenext"
+      }
+    }
+    ```
 
-        :::note
-        While ArkEnv [can](https://github.com/yamcodes/arkenv/tree/main/examples/basic-js) work with plain JavaScript, TypeScript is strongly recommended for the best experience.
-        :::
-      </Step>
+    :::note
+    While ArkEnv [can](https://github.com/yamcodes/arkenv/tree/main/examples/basic-js) work with plain JavaScript, TypeScript is strongly recommended for the best experience.
+    :::
 
-      <Step>
-        ### Setup ArkType (optional)
+    ### Setup ArkType (optional) [step] [!toc]
 
-        While ArkEnv [works with any Standard Schema validator](/docs/arkenv/integrations/standard-schema), we
-        recommend using ArkType for the ultimate ArkEnv experience.
+    While ArkEnv [works with any Standard Schema validator](/docs/arkenv/integrations/standard-schema), we
+    recommend using ArkType for the ultimate ArkEnv experience.
 
-        Follow the [ArkType setup](https://arktype.io/docs/intro/setup) to complete your configuration. We
-        recommend installing the ArkType syntax highlighting extension if your IDE supports it.
-      </Step>
-    </Steps>
+    Follow the [ArkType setup](https://arktype.io/docs/intro/setup) to complete your configuration. We
+    recommend installing the ArkType syntax highlighting extension if your IDE supports it.
   </Accordion>
 </Accordions>