Make ArkType optional (Built-in Standard Schema) through explicit validator mode

.changeset/every-tips-shout.md

@@ -0,0 +1,24 @@
+---
+"arkenv": minor
+---
+
+#### ArkType is now an optional peer dependency
+
+To achieve a true zero-dependency core, ArkType is now an optional peer dependency.
+
+- **Breaking Change**: The `type` export has been moved from the main `arkenv` entry point to `arkenv/arktype`.
+
+```ts
+// ❌ Before
+import { type } from "arkenv";
+
+// ✅ After
+import { type } from "arkenv/arktype";
+```
+
+- **Explicit Validator Modes**: ArkEnv now supports an explicit `validator` option.
+
+  - **`validator: "arktype"` (default)**: Uses ArkType for validation and coercion. Requires `arktype` to be installed.
+  - **`validator: "standard"`**: Uses Standard Schema validators directly (e.g., Zod, Valibot). Works without ArkType.
+
+Existing usage of `arkenv()` remains unchanged when ArkType is installed. Projects using ArkType features must now explicitly install `arktype` and import ArkType-land helpers from `arkenv/arktype`.

.changeset/tender-books-shout.md

@@ -0,0 +1,5 @@
+---
+"@repo/types": patch
+---
+
+#### Added Standard Schema, helpers

.gitignore

@@ -46,7 +46,7 @@ coverage/
 esbuild-why*.html
 
 # arktype clone
-arktype/
+/arktype/
 
 # explicitly ignored folder
 ignore-me/

apps/playgrounds/bun-react/src/env.ts

@@ -1,4 +1,4 @@
-import { type } from "arkenv";
+import { type } from "arkenv/arktype";
 
 export default type({
 	BUN_PUBLIC_API_URL: "string.url",

apps/playgrounds/solid-start/README.md

@@ -13,7 +13,7 @@ The example uses a single schema definition in `app.config.ts` that defines the
 ```ts title="app.config.ts"
 import arkenvVitePlugin from "@arkenv/vite-plugin";
 import { defineConfig } from "@solidjs/start/config";
-import { type } from "arkenv";
+import { type } from "arkenv/arktype";
 
 // Define the schema
 export const Env = type({

apps/playgrounds/solid-start/app.config.ts

@@ -1,6 +1,6 @@
 import arkenvVitePlugin from "@arkenv/vite-plugin";
 import { defineConfig } from "@solidjs/start/config";
-import { type } from "arkenv";
+import { type } from "arkenv/arktype";
 
 export const Env = type({
 	VITE_TEST: "string",

apps/playgrounds/standard-schema/index.ts

@@ -1,46 +1,45 @@
-import arkenv, { type } from "arkenv";
+import arkenv from "arkenv";
 import * as z from "zod";
 
-const env = arkenv({
-	// ArkType validators (concise TypeScript-like syntax)
-	HOST: "string.host",
-	PORT: "number.port",
-	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
-	DEBUG: "boolean = false",
+const env = arkenv(
+	{
+		// Zod validators (great for complex validation and transformations)
+		DATABASE_URL: z.string().url(),
+		API_KEY: z
+			.string()
+			.min(32)
+			.describe("API key must be at least 32 characters"),
 
-	// Zod validators (great for complex validation and transformations)
-	DATABASE_URL: z.url(),
-	API_KEY: z
-		.string()
-		.min(32)
-		.describe("API key must be at least 32 characters"),
+		// Standard Schema compatible validators
+		MAX_RETRIES: z.coerce.number().int().positive().default(3),
+		TIMEOUT_MS: z.coerce.number().int().min(0).max(30000).default(5000),
 
-	// Mix them together based on your needs
-	MAX_RETRIES: z.number().int().positive().default(3),
-	TIMEOUT_MS: z.number().int().min(0).max(30000).default(5000),
+		// Complex transformations with Zod
+		ALLOWED_ORIGINS: z
+			.string()
+			.transform((str: string) => str.split(","))
+			.pipe(z.array(z.string().url())),
 
-	// Complex transformations with Zod
-	ALLOWED_ORIGINS: z
-		.string()
-		.transform((str: string) => str.split(","))
-		.pipe(z.array(z.url())),
-
-	// Array defaults with ArkType
-	FEATURE_FLAGS: type("string[]").default(() => []),
-});
+		NODE_ENV: z
+			.enum(["development", "production", "test"])
+			.default("development"),
+		DEBUG: z
+			.union([z.boolean(), z.enum(["true", "false", "1", "0"])])
+			.transform((v) => v === true || v === "true" || v === "1")
+			.default(false),
+	},
+	{ validator: "standard" },
+);
 
 // All validators work together seamlessly with full type inference
 console.log({
-	host: env.HOST,
-	port: env.PORT,
 	nodeEnv: env.NODE_ENV,
 	debug: env.DEBUG,
 	databaseUrl: env.DATABASE_URL,
 	apiKey: `${env.API_KEY.substring(0, 8)}...`, // Don't log full API key
 	maxRetries: env.MAX_RETRIES,
 	timeoutMs: env.TIMEOUT_MS,
 	allowedOrigins: env.ALLOWED_ORIGINS,
-	featureFlags: env.FEATURE_FLAGS,
 });
 
 export default env;

apps/playgrounds/vite-legacy/vite.config.ts

@@ -1,6 +1,7 @@
 import arkenvVitePlugin from "@arkenv/vite-plugin";
 import reactPlugin from "@vitejs/plugin-react";
-import arkenv, { type } from "arkenv";
+import arkenv from "arkenv";
+import { type } from "arkenv/arktype";
 import { defineConfig, loadEnv } from "vite";
 import tsconfigPaths from "vite-tsconfig-paths";
 

apps/playgrounds/vite/README.md

@@ -13,7 +13,7 @@ The example uses a single schema definition that's reused for both server-side c
 
 ```ts title="vite.config.ts"
 import arkenvVitePlugin from "@arkenv/vite-plugin";
-import arkenv, { type } from "arkenv";
+import arkenv from "arkenv"; import { type } from "arkenv/arktype";
 import { defineConfig, loadEnv } from "vite";
 
 // Define the schema once

apps/playgrounds/vite/vite.config.ts

@@ -1,6 +1,7 @@
 import arkenvVitePlugin from "@arkenv/vite-plugin";
 import reactPlugin from "@vitejs/plugin-react";
-import arkenv, { type } from "arkenv";
+import arkenv from "arkenv";
+import { type } from "arkenv/arktype";
 import { defineConfig, loadEnv } from "vite";
 import tsconfigPaths from "vite-tsconfig-paths";
 

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

@@ -1,11 +1,13 @@
 ---
 title: Coercion
 description: Environment variables are auto-morphed into typesafe numbers, booleans, and more.
-icon: Updated
 ---
 
 Traditionally, environment variables are always strings by default. ArkEnv **coerces** these strings into their target types based on your schema, so you only have to think about the types you want.
 
+> [!IMPORTANT]
+> Coercion is only available in **ArkType mode** (the default). When using `validator: "standard"`, your Standard Schema validators handle their own parsing and type conversion.
+
 ## Numbers
 
 Any field defined as a `number` or a numeric subtype (like `number.integer` or `number.port`) will be automatically parsed.

apps/www/content/docs/arkenv/how-to/load-environment-variables.mdx

@@ -195,6 +195,111 @@ export const env = arkenv({
 });
 ```
 
+## Configuration options
+
+ArkEnv supports several configuration options to customize its behavior:
+
+### Validator mode
+
+Choose between ArkType (default) or Standard Schema validators:
+
+```typescript title="src/config/env.ts" twoslash
+import arkenv from 'arkenv';
+import { z } from 'zod';
+
+// ArkType mode (default) - requires ArkType to be installed
+const env1 = arkenv({
+  PORT: "number.port",
+  HOST: "string.host",
+});
+
+// Standard mode - works without ArkType
+const env2 = arkenv(
+  {
+    PORT: z.coerce.number().int().min(0).max(65535),
+    DATABASE_URL: z.string().url(),
+  },
+  { validator: "standard" }
+);
+```
+
+### Coercion
+
+Control automatic type conversion (only available in ArkType mode):
+
+```typescript title="src/config/env.ts" twoslash
+import arkenv from 'arkenv';
+
+// Coercion enabled (default)
+const env1 = arkenv({
+  PORT: "number.port", // "3000" becomes 3000
+});
+
+// Coercion disabled
+const env2 = arkenv(
+  {
+    PORT: "number.port",
+  },
+  { coerce: false } // Must be a number; strings (like those from process.env) will fail
+);
+```
+
+> [!NOTE]
+> Since `process.env` values are always strings, using `coerce: false` with numeric or boolean schemas will cause validation to fail unless you provide a custom `env` source containing the expected literal types.
+```
+
+### Custom environment source
+
+Provide a custom environment object:
+
+```typescript title="src/config/env.ts" twoslash
+import arkenv from 'arkenv';
+
+const env = arkenv(
+  {
+    PORT: "number.port",
+  },
+  {
+    env: {
+      PORT: "3000",
+      // ... other variables
+    },
+  }
+);
+```
+
+### Array format
+
+Control how arrays are parsed (only available in ArkType mode):
+
+```typescript title="src/config/env.ts" twoslash
+import arkenv from 'arkenv';
+
+// Comma-separated (default)
+const env1 = arkenv(
+  {
+    TAGS: "string[]",
+  },
+  {
+    env: { TAGS: "web, app, api" },
+    arrayFormat: "comma",
+  }
+);
+
+// JSON format
+const env2 = arkenv(
+  {
+    TAGS: "string[]",
+  },
+  {
+    env: { TAGS: '["web", "app"]' },
+    arrayFormat: "json",
+  }
+);
+```
+
+For more details on configuration options, see the [coercion documentation](/docs/arkenv/coercion) and [Standard Schema integration guide](/docs/arkenv/integrations/standard-schema).
+
 ## Common patterns
 
 ### Configuration factory

apps/www/content/docs/arkenv/how-to/reuse-schemas.mdx

@@ -24,7 +24,8 @@ This might sound like a niche use-case, but it comes up more often than you'd th
 That's where type definitions start making sense: define your schema once with `type()`, and reuse it wherever you need.
 
 ```ts twoslash
-import arkenv, { type } from 'arkenv';
+import arkenv from 'arkenv';
+import { type } from 'arkenv/arktype';
 
 const Env = type({
   HOST: "string.host",

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

@@ -31,7 +31,7 @@ We consider the resulting `env` object "typesafe from editor to runtime": at eve
 
 ### Editor
 
-ArkEnv tells TypeScript about the shape of your environment variables, so you can use the types your schema defines without additional checks or manual type-casts. Your editor will also autocomplete your schema and provide type hints, whether you're using [ArkType](https://arktype.io/), Zod, Valibot, or any other Standard Schema validator. If you're using ArkType, you can take this a step further with [syntax highlighting and inline errors](docs/arkenv/integrations/vscode). This way, writing your schema feels like writing TypeScript.
+ArkEnv tells TypeScript about the shape of your environment variables, so you can use the types your schema defines without additional checks or manual type-casts. Your editor will also autocomplete your schema and provide type hints, whether you're using [ArkType](https://arktype.io/), Zod, Valibot, or any other Standard Schema validator. If you're using ArkType, you can take this a step further with [syntax highlighting and inline errors](/docs/arkenv/integrations/vscode). This way, writing your schema feels like writing TypeScript.
 
 ### Build time