Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 2 additions & 5 deletions apps/www/app/(home)/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,8 @@ export default function HomePage() {
<div className="flex flex-col lg:flex-row items-center justify-center px-4 sm:px-6 lg:pl-12 lg:pr-6 max-w-screen-2xl mx-auto w-full gap-4 md:gap-8 lg:gap-12 lg:mt-20">
<div className="flex flex-col items-center lg:items-start text-center lg:text-left lg:flex-[1.4] relative z-20 mt-12 w-full max-w-full">
<div className="lg:mb-6 mb-0">
<AnnouncementBadge
new
href="docs/arkenv/validator-mode#arkenvstandard"
>
Native Standard Schema support
<AnnouncementBadge new href="docs/arkenv/standard#arkenvstandard">
Standard Schema support
</AnnouncementBadge>
</div>
<h1 className="mb-4 mt-6 lg:mt-0 w-full max-w-2xl">
Expand Down
2 changes: 1 addition & 1 deletion apps/www/content/docs/arkenv/coercion.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ 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 only available in **ArkType mode** (the default). When using `arkenv/standard`, your Standard Schema validators handle their own parsing and type conversion.
> Coercion is not available in `arkenv/standard` - use your validator's native coercion instead.

## Numbers

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -199,22 +199,22 @@ export const env = arkenv({

ArkEnv supports several configuration options to customize its behavior:

### Validator mode
### Entry point

Choose between ArkType (default) or Standard Schema validators:
Choose between `arkenv` (requires ArkType) or `arkenv/standard` (ArkType-free):

```typescript title="src/config/env.ts" twoslash
import arkenv from 'arkenv';
import arkenvStandard from 'arkenv/standard';
import { z } from 'zod';

// ArkType mode (default) - requires ArkType to be installed
// arkenv - requires ArkType to be installed
const env1 = arkenv({
PORT: "number.port",
HOST: "string.host",
});

// Standard mode - works without ArkType
// arkenv/standard - works without ArkType
const env2 = arkenvStandard({
PORT: z.coerce.number().int().min(0).max(65535),
DATABASE_URL: z.url(),
Expand All @@ -223,7 +223,7 @@ const env2 = arkenvStandard({

### Coercion

Control automatic type conversion (only available in ArkType mode):
Control automatic type conversion (not available in `arkenv/standard`):

```typescript title="src/config/env.ts" twoslash
import arkenv from 'arkenv';
Expand Down Expand Up @@ -268,7 +268,7 @@ const env = arkenv(

### Array format

Control how arrays are parsed (only available in ArkType mode):
Control how arrays are parsed (not available in `arkenv/standard`):

```typescript title="src/config/env.ts" twoslash
import arkenv from 'arkenv';
Expand Down
57 changes: 5 additions & 52 deletions apps/www/content/docs/arkenv/integrations/standard-schema.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,25 +3,16 @@ title: Standard Schema validators
description: You can use any Standard Schema validator with ArkEnv.
---

ArkEnv supports any validator that implements the [Standard Schema](https://standardschema.dev/) specification.

By default, ArkEnv runs validation through **ArkType**, which natively supports Standard Schema validators like Zod and Valibot. This lets you freely mix ArkType's string DSL with other validation libraries in the same schema.

If you prefer not to install ArkType, ArkEnv also provides a **Standard-only mode** that works with Standard Schema validators directly.

## Supported validators

ArkEnv works with any validator that implements the Standard Schema interface, including:
Any validator that implements the [Standard Schema](https://standardschema.dev/) specification is supported. For example:

- **[Zod](https://zod.dev/)** - TypeScript-first schema validation
- **[Valibot](https://valibot.dev/)** - Modular schema validation
- **[ArkType](https://arktype.io/)** (native) - TypeScript's 1\:1 validator

To read more about Standard Schema, see the [Standard Schema documentation](https://standardschema.dev/).

## Using Standard Schema with ArkType (default)
ArkType works both as a validator and as a wrapper for other validators - all via Standard Schema. This means you can freely mix ArkType, Zod, Valibot, and any other Standard Schema validator in the same schema.

Since ArkType natively supports Standard Schema, you can freely mix ArkType DSL strings with Standard Schema validators in the same schema - no configuration needed.
> [!TIP]
> Want to avoid ArkType as a dependency altogether? Use [`arkenv/standard`](/docs/arkenv/standard) instead.

```package-install
arkenv arktype zod
Expand All @@ -43,46 +34,8 @@ export const env = arkenv({
});
```

This is useful when:

- You want ArkType's concise DSL for simple fields
- You need library-specific features (transforms, refinements) for complex fields
- You're migrating gradually from another validation library

> [!TIP]
> This works with any Standard Schema validator, including Valibot. Just install your preferred validator and use it alongside ArkType DSL strings.

## Using Standard Schema without ArkType

If you don't want ArkType installed, you can run ArkEnv in Standard-only mode using the `arkenv/standard` entry point:

```ts twoslash title="env.ts"
import arkenv from 'arkenv/standard';
import { z } from 'zod';

export const env = arkenv({
PORT: z.coerce.number().int().min(0).max(65535),
DATABASE_URL: z.url(),
DEBUG: z.coerce.boolean().default(false),
});
```

### When to use Standard-only mode

- You want a zero-ArkType runtime path
- You're migrating from another validation library
- You prefer Standard Schema validators exclusively
- You want to minimize bundle size

### Limitations

- **ArkType DSL strings are not supported** (e.g., `"number.port"`, `"string.host"`)
- **ArkType coercion is not available** - validators handle their own parsing

## Need help?

If you run into issues:

1. **In default mode**: Ensure you're using `arktype@>=2.1.28`
1. Use `arktype@>=2.1.28` — or switch to `arkenv/standard` to drop the ArkType dependency entirely
2. Verify your validator library implements Standard Schema 1.0
3. Join our [Discord community](https://discord.gg/zAmUyuxXH9) for help
2 changes: 1 addition & 1 deletion apps/www/content/docs/arkenv/meta.json
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@
"quickstart",
"examples",
"---API---",
"[New][Validator mode](/docs/arkenv/validator-mode)",
"[New][arkenv/standard](/docs/arkenv/standard)",
"coercion",
"---Integrations---",
"...integrations",
Expand Down
2 changes: 1 addition & 1 deletion apps/www/content/docs/arkenv/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ icon: Rocket
```package-install
arkenv arktype
```
ArkEnv works best when [paired with ArkType](/docs/arkenv/validator-mode).
ArkEnv works best when paired with [ArkType](https://arktype.io).
</Accordion>
<Accordion title="Install ArkEnv only">

Expand Down
43 changes: 43 additions & 0 deletions apps/www/content/docs/arkenv/standard.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
---
title: arkenv/standard
description: The ArkType-free entry point for Standard Schema validators.
---

`arkenv/standard` is the ArkType-free entry point. Use it when you want Standard Schema validators (Zod, Valibot, etc.) without pulling in ArkType as a dependency.

> [!TIP]
> Already using ArkType? You can still use Zod, Valibot, and other Standard Schema validators alongside it. See [Standard Schema validators](/docs/arkenv/integrations/standard-schema).

## When to use it

| Feature | `arkenv` | `arkenv/standard` |
| :------ | :------: | :---------------: |
| **ArkType DSL** | ✅ | ❌ |
| **ArkEnv keywords**\* | ✅ | ❌ |
| **Standard Schema** | ✅ | ✅ |
| **Automatic coercion** | ✅ | ❌ |
| **Works without ArkType** | ❌ | ✅ |

\* ArkEnv extends ArkType with custom keywords like `string.host` and `number.port`

✅ Built-in / first-class support

❌ Not supported

> In a new project, prefer `arkenv`. `arkenv/standard` exists for migrations and ArkType-free setups.

## Usage

```ts twoslash
import arkenv from 'arkenv/standard';
import { z } from 'zod';

const env = arkenv({
PORT: z.coerce.number().int().min(0).max(65535),
DATABASE_URL: z.url(),
});
```

## Requirements

A validator that implements Standard Schema (e.g. `zod@>=3.24.0`, `valibot@^1.0.0`).
74 changes: 0 additions & 74 deletions apps/www/content/docs/arkenv/validator-mode.mdx

This file was deleted.

2 changes: 1 addition & 1 deletion apps/www/content/docs/bun-plugin/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -114,7 +114,7 @@ await Bun.build({
> [!IMPORTANT]
> This plugin requires [ArkType](https://arktype.io) to be installed.
>
> For a zero-ArkType setup, use [arkenv/standard](/docs/arkenv/validator-mode) directly in your app code instead.
> 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.

Expand Down
6 changes: 3 additions & 3 deletions apps/www/content/docs/vite-plugin/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ import { z } from "zod";
export default defineConfig({
plugins: [
arkenv({
VITE_API_URL: z.string().url(),
VITE_API_URL: z.url(),
VITE_API_KEY: z.string().min(1),
VITE_DEBUG: "boolean",
}),
Expand All @@ -52,7 +52,7 @@ export default defineConfig({
> [!IMPORTANT]
> This plugin requires [ArkType](https://arktype.io) to be installed.
>
> For a zero-ArkType setup, use [arkenv/standard](/docs/arkenv/validator-mode) directly in your app code instead.
> 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.

Expand All @@ -62,7 +62,7 @@ export default defineConfig({
@arkenv/vite-plugin
```

If you intend to use the default validator mode, you should also install `arktype`:
If you intend to use `arkenv` (requires ArkType), also install `arktype`:

```package-install
arktype
Expand Down
Loading
Loading