Merge branch 'v1' into 1199-distribution-implement-standard-mode-packaging-strategy

Author: yamcodes

.agents/docs/CONTEXT.md

@@ -63,8 +63,8 @@ The main goal is to provide a developer-friendly way to validate and type-check
 
 **Naming Conventions:**
 
-- **Files**: kebab-case (`create-env.ts`)
-- **Functions**: camelCase (`createEnv`)
+- **Files**: kebab-case (`arkenv.ts`)
+- **Functions**: camelCase (`arkenvInternal`, `myFunction`)
 - **Types**: PascalCase (`ArkEnvError`)
 - **Constants**: UPPER_SNAKE_CASE for environment variables
 
@@ -95,7 +95,7 @@ The main goal is to provide a developer-friendly way to validate and type-check
 **Package Architecture:**
 
 - **Core Package** (`arkenv`):
-  - Main export: `createEnv` function (also exported as default `arkenv`)
+  - Main export: `arkenv` function (also exported as default export)
   - Uses ArkType's `scope` system for type validation
   - Custom types: `string.host`, `number.port`, `boolean`
   - Error handling via `ArkEnvError` class
@@ -200,7 +200,7 @@ pnpm run test:e2e                     # E2E tests
 - **Vite**: Integrated via `@arkenv/vite-plugin`. Validates environment variables at build-time and inlines `import.meta.env` variables for **client-side** (browser) usage.
 - **Next.js**: Integrated via `@arkenv/nextjs`. Provides two layout patterns:
   - **3-File Layout (Strict)**: Uses separate environment files for client, server, and shared scopes (`env/client.ts`, `env/server.ts`, and `env/internal/shared.ts`) for compile-time locking of secrets from browser bundles using package conditional exports (`react-server` vs. `default`) and `server-only`.
-  - **Unified 1-File Layout**: Uses a single `env.ts` schema file. In Next.js, client-side environment variables must be statically destructured in a `runtimeEnv` block to allow static inlining by the Next.js compiler. To automate this, `@arkenv/nextjs/config` exposes a `withArkEnv` wrapper for `next.config.js` that performs static analysis on `env.ts` to locate `client` and `shared` keys, then automatically generates a tailored `createEnv` factory in `generated/env.gen.ts` that pre-fills `runtimeEnv`. It enforces strict client-side prefixing (`NEXT_PUBLIC_`) and prevents server secrets from leaking to client components.
+  - **Unified 1-File Layout**: Uses a single `env.ts` schema file. In Next.js, client-side environment variables must be statically destructured in a `runtimeEnv` block to allow static inlining by the Next.js compiler. To automate this, `@arkenv/nextjs/config` exposes a `withArkEnv` wrapper for `next.config.js` that performs static analysis on `env.ts` to locate `client` and `shared` keys, then automatically generates a tailored `arkenv` factory in `generated/env.gen.ts` that pre-fills `runtimeEnv`. It enforces strict client-side prefixing (`NEXT_PUBLIC_`) and prevents server secrets from leaking to client components.
 - **Bun fullstack dev server**:
   - **Bun.serve**: An HTTP server runtime that integrates with Bun's built-in bundler to scan HTML files, trigger on-demand bundling, and serve resulting assets. It does not perform bundling itself; rather, it coordinates with Bun's bundler (configured via `@arkenv/bun-plugin` in `bunfig.toml`) to inline environment variables (e.g., using a `PUBLIC_` prefix) via static replacement. Primarily used for **client-side** bundling integration.
   - **Bun.build**: Bun's programmatic bundling API. Integrated via `@arkenv/bun-plugin` in the `Bun.build` plugins array. Used for custom build scripts targeting the browser in a fullstack context.
@@ -218,7 +218,7 @@ pnpm run test:e2e                     # E2E tests
 
 - Uses `const` type parameters for better type inference
 - Leverages ArkType's `type.infer` and `type.validate` utilities
-- Typesafe environment object returned from `createEnv`
+- Typesafe environment object returned from `arkenv`
 
 **Error Handling:**
 

.agents/platforms/.cursor/rules/arktype.mdc

@@ -22,7 +22,7 @@ Define environment variable schemas using ArkType syntax:
 ```typescript
 import { type } from "arktype";
 
-const env = createEnv({
+const env = arkenv({
   HOST: "string.host", // Custom host type
   PORT: "number.port", // Custom port type
   NODE_ENV: "'development' | 'production' | 'test'", // Union type
@@ -49,7 +49,7 @@ import { $ } from "./scope";
 ## Type Inference
 
 - Use `type.infer` to extract TypeScript types from schemas
-- The return type of `createEnv` is inferred from the schema
+- The return type of `arkenv` is inferred from the schema
 - No manual type definitions needed
 
 ## Error Handling

.agents/platforms/.cursor/rules/coding-guidelines.mdc

@@ -48,8 +48,8 @@ This project uses [Biome](https://biomejs.dev/) for formatting and linting. The
 
 ## Naming Conventions
 
-- **Files**: Use kebab-case for files (`create-env.ts`)
-- **Functions**: Use camelCase (`createEnv`)
+- **Files**: Use kebab-case for files (`arkenv-internal.ts`)
+- **Functions**: Use camelCase (`arkenv`, `myFunction`)
 - **Types**: Use PascalCase (`ArkEnvError`)
 - **Constants**: Use UPPER_SNAKE_CASE for environment variables and constants
 

.agents/platforms/.cursor/rules/test-patterns.mdc

@@ -33,7 +33,7 @@ alwaysApply: true
 - Fast execution (< 100ms per test)
 - Mocked external dependencies (clipboard, network, etc.)
 - Focused on single unit behavior
-- Co-locate with source: `create-env.ts` → `create-env.test.ts`
+- Co-locate with source: `arkenv.ts` → `arkenv.test.ts`
 
 ### Integration Tests (`*.integration.test.ts` or `*.integration.test.tsx`)
 **What:** Test how multiple units (components, hooks, functions) work together without mocking their interactions.
@@ -45,8 +45,8 @@ alwaysApply: true
 - State synchronization across boundaries
 
 **Examples:**
-- `custom-types.integration.test.ts` - Tests `createEnv` + `scope` + custom types working together
-- `error.integration.test.ts` - Tests error propagation through `createEnv` + `formatErrors` + `ArkEnvError`
+- `custom-types.integration.test.ts` - Tests `arkenv` + `scope` + custom types working together
+- `error.integration.test.ts` - Tests error propagation through `arkenv` + `formatErrors` + `ArkEnvError`
 - `copy-button.integration.test.tsx` - Tests `CopyButton` + `useToast` + `Toaster` as a complete flow
 - `heading.integration.test.tsx` - Tests `Heading` + `useIsMobile` responding to viewport changes
 - `toaster.integration.test.tsx` - Tests `useToast` hook + `Toaster` component state synchronization
@@ -98,12 +98,12 @@ alwaysApply: true
 
 ```typescript
 import { describe, expect, it } from "vitest";
-import { createEnv } from "./create-env";
+import arkenv from "./arkenv";
 
-describe("createEnv", () => {
+describe("arkenv", () => {
   it("should validate string env variables", () => {
     process.env.TEST_STRING = "hello";
-    const env = createEnv({
+    const env = arkenv({
       TEST_STRING: "string",
     });
     expect(env.TEST_STRING).toBe("hello");

.agents/platforms/copilot-instructions.md

@@ -56,14 +56,14 @@ The project uses modern tooling:
 
 The core package provides:
 
-1. **`createEnv(schema)`** - Main function to create validated environment objects. Also available as the default export, typically imported as `arkenv`.
+1. **`arkenv(schema)`** - Main function to create validated environment objects. Exposed as default export, and also as named export `arkenv`.
 2. **Built-in validators** - Common validators like `host`, `port`, `url`, etc.
 3. **ArkType integration** - Uses ArkType for schema definition and validation
 4. **Type inference** - Full TypeScript type inference from schemas
 
 ### Key files
 
-- `src/create-env.ts` - Core `createEnv` implementation
+- `src/arkenv.ts` - Core `arkenv` implementation
 - `src/types.ts` - Built-in type validators (host, port, url, etc.)
 - `src/errors.ts` - Error handling and formatting
 - `src/utils.ts` - Utility functions
@@ -113,7 +113,7 @@ The project uses three types of tests:
 
 Tests are located alongside source files with `.test.ts` suffix:
 
-- `create-env.test.ts` - Tests for main `createEnv` functionality
+- `arkenv.test.ts` - Tests for main `arkenv` functionality
 - `types.test.ts` - Tests for built-in validators
 - `errors.test.ts` - Tests for error handling
 - `utils.test.ts` - Tests for utility functions
@@ -131,7 +131,7 @@ Tests are located alongside source files with `.test.ts` suffix:
 
 **Examples:**
 
-- `custom-types.integration.test.ts` - Tests `createEnv` + `scope` + custom types working together
+- `custom-types.integration.test.ts` - Tests `arkenv` + `scope` + custom types working together
 - `error.integration.test.ts` - Tests error propagation through validation pipeline
 - `copy-button.integration.test.tsx` - Tests `CopyButton` + `useToast` + `Toaster` flow
 - `heading.integration.test.tsx` - Tests `Heading` + `useIsMobile` responsive behavior

.changeset/pre.json

@@ -17,5 +17,5 @@
 		"@arkenv/nextjs": "0.0.7",
 		"@arkenv/vite-plugin": "0.1.1"
 	},
-	"changesets": ["init-v1", "unify-coercion"]
+	"changesets": ["init-v1", "rename-create-env-to-arkenv", "unify-coercion"]
 }

.changeset/rename-create-env-to-arkenv.md

@@ -0,0 +1,31 @@
+---
+"arkenv": major
+"@arkenv/nextjs": major
+---
+
+#### Rename `createEnv` function to `arkenv`
+
+**BREAKING CHANGE**: Rename the primary environment variable validation function from `createEnv` to `arkenv` across all packages in the ecosystem, and expose it as both the default export and a named export.
+
+Update all usages:
+
+```ts
+// Before
+import { createEnv } from "arkenv";
+
+export const env = createEnv({
+  NODE_ENV: "'development' | 'production' | 'test'",
+});
+
+// After
+import arkenv from "arkenv";
+// or: import { arkenv } from "arkenv";
+
+export const env = arkenv({
+  NODE_ENV: "'development' | 'production' | 'test'",
+});
+```
+
+Migration Steps:
+- Replace all imports and invocations of `createEnv` with `arkenv`.
+- Update config generators and plugins (Next.js config templates, Vite plugin, Bun plugin) to use `arkenv`.

apps/playgrounds/nextjs-strict/env/generated/env.gen.ts

@@ -7,11 +7,11 @@
  * @see https://arkenv.js.org
  */
 
-import { createEnv as coreCreateEnv } from "@arkenv/nextjs/client";
+import { arkenv as coreArkenv } from "@arkenv/nextjs/client";
 
 export { type } from "@arkenv/nextjs/client";
 
-export function createEnv<
+export function arkenv<
 	const TSchema extends Record<string, any> = {},
 	const TExtends extends readonly unknown[] = [],
 >(
@@ -22,7 +22,7 @@ export function createEnv<
 		extends?: [...TExtends];
 	},
 ) {
-	return coreCreateEnv<TSchema, TExtends>(
+	return coreArkenv<TSchema, TExtends>(
 		schema as any,
 		{
 			...options,
@@ -34,5 +34,4 @@ export function createEnv<
 	);
 }
 
-const arkenv = createEnv;
 export default arkenv;

apps/playgrounds/nextjs/generated/env.gen.ts

@@ -8,11 +8,11 @@
  */
 
 import type { Infer } from "@arkenv/nextjs";
-import { createEnv as coreCreateEnv } from "@arkenv/nextjs";
+import { arkenv as coreArkenv } from "@arkenv/nextjs";
 
 export { type } from "@arkenv/nextjs";
 
-export function createEnv<
+export function arkenv<
 	const TServer extends Record<string, any> = {},
 	const TClient extends Record<string, any> = {},
 	const TShared extends Record<string, any> = {},
@@ -23,7 +23,7 @@ export function createEnv<
 	};
 	shared?: TShared;
 }): Readonly<Infer<TServer & TClient & TShared>> {
-	return coreCreateEnv({
+	return coreArkenv({
 		...options,
 		runtimeEnv: {
 			NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
@@ -32,5 +32,4 @@ export function createEnv<
 	} as any) as any;
 }
 
-const arkenv = createEnv;
 export default arkenv;

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

@@ -100,7 +100,7 @@ Coercion works recursively: even variables inside a JSON object are coerced to t
 
 ## How it works
 
-ArkEnv uses a unified pre-coercion model shared across both `arkenv` and `arkenv/standard`. When you call `createEnv()` (or `arkenv()`):
+ArkEnv uses a unified pre-coercion model shared across both `arkenv` and `arkenv/standard`. When you call `arkenv()`:
 
 1. **Introspection**: ArkEnv extracts the JSON Schema of your defined schema. For `arkenv` (ArkType), it introspects the schema (with a fallback to handle unjsonifiable parts of the schema like custom morphs or predicates). For `arkenv/standard` (e.g., Zod, Valibot), it extracts JSON Schema using the validator's standard metadata.
 2. **Paths Identification**: It computes the exact paths requiring coercion (using `findCoercionPaths`) to identify target non-string types like numbers, booleans, arrays, or objects.