Merge pull request #1169 from yamcodes/dev

Author: yamcodes

.changeset/standard-json-schema-coercion.md

@@ -0,0 +1,21 @@
+---
+"arkenv": minor
+---
+
+#### Add Standard JSON Schema coercion to `arkenv/standard`
+
+Introduce opt-out type coercion for standard mode (`arkenv/standard`). This coercion only works if the validator is a standard JSON Schema compliant validator (e.g., Zod, Valibot, or custom schemas that implement the `StandardJSONSchemaV1` interface). This automatically enables coercion for environment variables without relying on ArkType's runtime footprint.
+
+If you need to disable coercion, explicitly pass `{ coerce: false }` in your configuration:
+
+```ts
+import arkenv from "arkenv/standard";
+import { z } from "zod";
+
+const env = arkenv(
+  { PORT: z.number() },
+  { coerce: false }
+);
+```
+
+BREAKING CHANGE: Coercion is now enabled by default in `arkenv/standard`. This will automatically coerce environment variables to their expected types (e.g., strings containing numbers, booleans, or dates will be converted to their respective types) based on the JSON Schema of your validators. It's unlikely to affect you unless you were relying on validation failing for uncoerced string inputs, or have custom schemas that expect raw strings instead of coerced values.

.github/workflows/sync-pr.yml

@@ -39,6 +39,8 @@ jobs:
 
             It tracks all commits on `dev` that have not yet been merged into `main`, keeping the two branches in sync after every push to `dev`.
 
+            🌍 **Preview the latest dev documentation**: https://arkenv-dev.vercel.app
+
             > [!NOTE]
             > This PR is opened and managed by **arkenv-bot**. It is skipped by Pullfrog and other bot-aware workflows.
         run: |
@@ -67,7 +69,7 @@ jobs:
             gh pr create \
               --base main \
               --head dev \
-              --title "chore: sync dev → main" \
+              --title "Sync `dev` → `main`" \
               --body "$PR_BODY" \
               --label "maintenance"
             echo "✅ Sync PR created."

apps/www/components/page/cli-command.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { Toaster } from "~/components/ui/toaster";
 import { CLICommand } from "./cli-command";
 
@@ -19,10 +19,6 @@ describe("CLICommand", () => {
 		});
 	});
 
-	afterEach(() => {
-		vi.unstubAllGlobals();
-	});
-
 	it("should render with syntax highlighting spans", () => {
 		render(<CLICommand />);
 		expect(screen.getByText("npx")).toBeInTheDocument();

apps/www/components/page/copy-button.integration.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { beforeEach, describe, expect, it, vi } from "vitest";
 import { Toaster } from "~/components/ui/toaster";
 import { CopyButton } from "./copy-button";
 
@@ -22,10 +22,6 @@ describe("CopyButton + useToast + Toaster integration", () => {
 		});
 	});
 
-	afterEach(() => {
-		vi.unstubAllGlobals();
-	});
-
 	it("should show toast when copy succeeds", async () => {
 		const user = userEvent.setup();
 		mockWriteText.mockResolvedValue(undefined);

apps/www/components/ui/search-toggle.test.tsx

@@ -11,7 +11,6 @@ vi.mock("fumadocs-ui/contexts/search", () => ({
 describe("SearchToggle", () => {
 	afterEach(() => {
 		cleanup();
-		vi.restoreAllMocks();
 		vi.unstubAllGlobals();
 	});
 

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

@@ -5,9 +5,15 @@ description: Environment variables are auto-morphed into typesafe numbers, boole
 
 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 not available in `arkenv/standard` - use your validator's native coercion instead.
-:::
+:::note
+Coercion in [arkenv/standard](/docs/arkenv/standard) only works with:
+
+- [Zod](https://zod.dev) (v4.2+)
+- [Valibot](https://valibot.dev) (v1.2+ via `@valibot/to-json-schema`)
+- [Zod Mini](https://zod.dev)
+- [stnl](https://github.com/re-utils/stnl)
+- Any validator compliant with [Standard JSON Schema v1](https://standardschema.dev/json-schema#what-schema-libraries-support-this-spec)
+  :::
 
 ## Numbers
 

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

@@ -14,13 +14,15 @@ Already using ArkType? You can still use Zod, Valibot, and other Standard Schema
 | Feature                   | `arkenv` | `arkenv/standard` |
 | :------------------------ | :------: | :---------------: |
 | **ArkType DSL**           |     ✅    |         ❌         |
-| **ArkEnv keywords**\*     |     ✅    |         ❌         |
+| **ArkEnv keywords**¹      |     ✅    |         ❌         |
 | **ArkEnv plugins**        |     ✅    |         ❌         |
-| **Automatic coercion**    |     ✅    |         ❌         |
+| **Automatic coercion**    |     ✅    |         ✅²        |
 | **Standard Schema**       |     ✅    |         ✅         |
 | **Works without ArkType** |     ❌    |         ✅         |
 
-\* ArkEnv extends ArkType with custom keywords like `string.host` and `number.port`
+¹ ArkEnv extends ArkType with custom keywords like `string.host` and `number.port`
+
+² Only works with Standard JSON Schema validators like Zod 4, Zod Mini and Valibot - see [Coercion](/docs/arkenv/coercion)
 
 ✅ Built-in / first-class support
 

apps/www/hooks/use-copy-command.test.ts

@@ -26,7 +26,6 @@ describe("useCopyCommand", () => {
 	});
 
 	afterEach(() => {
-		vi.unstubAllGlobals();
 		vi.clearAllMocks();
 		vi.useRealTimers();
 	});

apps/www/lib/twoslash-options.ts

@@ -34,6 +34,7 @@ export const arktypeTwoslashOptions: ArkTypeTwoslashOptions = {
 				arkenv: [path.join(root, "packages/arkenv/src/index.ts")],
 				"arkenv/standard": [path.join(root, "packages/arkenv/src/standard.ts")],
 				"arkenv/core": [path.join(root, "packages/arkenv/src/core.ts")],
+				"@/*": [path.join(root, "packages/arkenv/src/*")],
 				"@arkenv/nextjs": [path.join(root, "packages/nextjs/src/index.ts")],
 				"@arkenv/nextjs/server": [
 					path.join(root, "packages/nextjs/src/server.ts"),

apps/www/lib/utils/github.test.ts

@@ -56,8 +56,6 @@ describe("github utilities", () => {
 		});
 
 		it("should use fallback URL when no URL is configured", () => {
-			vi.unstubAllEnvs();
-
 			const result = breakDownGithubUrl();
 
 			expect(result).toEqual({
@@ -147,8 +145,6 @@ describe("github utilities", () => {
 		});
 
 		it("should use fallback URL when no URL is configured", () => {
-			vi.unstubAllEnvs();
-
 			const result = getLinkTitleAndHref("test.md");
 
 			expect(result).toEqual({