yamcodes · yamcodes · Sep 14, 2025 · Sep 14, 2025 · Sep 14, 2025 · Sep 14, 2025
diff --git a/.changeset/all-ghosts-worry.md b/.changeset/all-ghosts-worry.md
@@ -0,0 +1,11 @@
+---
+"arkenv": patch
+---
+
+Export `ArkEnvError`
+
+You can now import `ArkEnvError` from `arkenv`:
+
+```ts
+import { ArkEnvError } from "arkenv";
+```
diff --git a/.changeset/some-bikes-film.md b/.changeset/some-bikes-film.md
@@ -0,0 +1,8 @@
+---
+"arkenv": patch
+---
+
+Improve JSDoc
+
+The JSDoc for `arkenv` and `createEnv` is now more descriptive.
+
diff --git a/apps/playgrounds/node/index.ts b/apps/playgrounds/node/index.ts
@@ -1,9 +1,9 @@
 import arkenv from "arkenv";
 
 const env = arkenv({
+	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
 	HOST: "string.host",
 	PORT: "number.port",
-	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
 });
 
 // Automatically validate and parse process.env

diff --git a/apps/www/app/docs/[[...slug]]/page.tsx b/apps/www/app/docs/[[...slug]]/page.tsx
@@ -1,3 +1,4 @@
+import * as Twoslash from "fumadocs-twoslash/ui";
 import { Accordion, Accordions } from "fumadocs-ui/components/accordion";
 import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock";
 import { Step, Steps } from "fumadocs-ui/components/steps";
@@ -55,6 +56,7 @@ export default async function Page(props: {
 										<Pre>{props.children}</Pre>
 									</CodeBlock>
 								),
+								...Twoslash,
 							}}
 						/>
 					</DocsBody>

diff --git a/apps/www/app/globals.css b/apps/www/app/globals.css
@@ -6,6 +6,7 @@
 @import "./styles/theme/inline.css";
 @import "./styles/components/github-alerts.css";
 @import "./styles/base.css";
+@import "fumadocs-twoslash/twoslash.css";
 
 @plugin "tailwindcss-animate";
 @source '../node_modules/fumadocs-ui/dist/**/*.js';

diff --git a/apps/www/app/layout.tsx b/apps/www/app/layout.tsx
@@ -32,6 +32,7 @@ export default function Layout({ children }: { children: ReactNode }) {
 			lang="en"
 			className={`${inter.className} ${jetbrainsMono.variable}`}
 			suppressHydrationWarning
+			data-scroll-behavior="smooth"
 		>
 			<body className="flex flex-col min-h-screen">
 				<RootProvider

diff --git a/apps/www/app/styles/base.css b/apps/www/app/styles/base.css
@@ -21,4 +21,9 @@
 	.fd-steps {
 		padding-left: 2.3rem;
 	}
+
+	/* Twoslash code block max height */
+	.twoslash .fd-scroll-container {
+		max-height: 160px !important;
+	}
 }
diff --git a/apps/www/content/docs/examples.mdx b/apps/www/content/docs/examples.mdx
@@ -10,4 +10,4 @@ description: Explore our collection of examples to get started with ArkEnv
 
 <Cards>
     <Card title="Contributing an example" href="https://github.com/yamcodes/arkenv/tree/main/examples#contributing-examples" description="Contribute an example to the project" />
-</Cards>
+</Cards>
diff --git a/apps/www/content/docs/guides/environment-configuration.mdx b/apps/www/content/docs/guides/environment-configuration.mdx
@@ -3,9 +3,9 @@ title: Loading environment variables
 description: Learn how to manage environment variables across different environments and deployment scenarios
 ---
 
-## Local Development
+## Local development
 
-### Using `.env` Files
+### Using `.env` files
 
 The most common way to manage environment variables during development is using `.env` files:
 
@@ -17,9 +17,9 @@ API_KEY=your-secret-key
 LOG_LEVEL=debug
 ```
 
-### Best Practices for `.env` Files
+### Best practices for `.env` files
 
-1. **Document Required Variables**
+1. **Document required variables**
    Create a `.env.example` file to document required variables:
    ```dotenv title=".env.example"
    DATABASE_HOST=localhost
@@ -29,15 +29,15 @@ LOG_LEVEL=debug
    LOG_LEVEL=info
    ```
 
-2. **Gitignore Configuration**
+2. **Gitignore configuration**
    Add these patterns to your `.gitignore`:
    ```dotenv title=".gitignore"
    .env
    .env.*
    !.env.example
    ```
 
-3. **Environment-Specific Files**
+3. **Environment-specific files**
    Use different files for different environments:
    - `.env.development` - Development settings
    - `.env.test` - Test environment settings
@@ -56,7 +56,7 @@ import * as dotenv from 'dotenv';
 dotenv.config();
 ```
 
-### Framework-Specific Solutions
+### Framework-specific solutions
 
 Many frameworks have built-in support for environment variables:
 
@@ -92,17 +92,17 @@ import { ConfigModule } from '@nestjs/config';
 })
 ```
 
-### Runtime Arguments
+### Runtime arguments
 
 You can also supply variables when running your application:
 
 ```bash
 DATABASE_HOST=localhost DATABASE_PORT=5432 npm start
 ```
 
-## Production Deployment
+## Production deployment
 
-### Cloud Platforms
+### Cloud platforms
 
 #### AWS
 - Use AWS Systems Manager Parameter Store for non-sensitive values
@@ -117,7 +117,7 @@ DATABASE_HOST=localhost DATABASE_PORT=5432 npm start
 - Use Azure Key Vault for sensitive values
 - Configure App Settings in Azure App Service
 
-### Container Environments
+### Container environments
 
 #### Docker
 
@@ -148,13 +148,13 @@ spec:
               key: database-host
 ```
 
-### Traditional Hosting
+### Traditional hosting
 
 - Set environment variables through the hosting platform's dashboard
 - Use deployment scripts to configure environment variables
 - Consider using configuration management tools
 
-## Security Best Practices
+## Security best practices
 
 1. **Never commit sensitive values**
    - Keep `.env` files out of version control
@@ -164,19 +164,19 @@ spec:
    - Don't share sensitive credentials between environments
    - Use environment-specific configurations
 
-3. **Access Control**
+3. **Access control**
    - Limit access to production environment variables
    - Use role-based access control for secrets management
 
 4. **Encryption**
    - Encrypt sensitive values at rest
    - Use secure channels for transmitting secrets
 
-## Validation and Typesafety
+## Validation and typesafety
 
 ArkEnv helps ensure your environment variables are valid:
 
-```typescript title="src/config/env.ts"
+```typescript title="src/config/env.ts" twoslash
 import arkenv from 'arkenv';
 
 export const env = arkenv({
@@ -188,27 +188,17 @@ export const env = arkenv({
   LOG_LEVEL: "'debug' | 'info' | 'warn' | 'error' = 'info'",
 
   // Optional variables
-  "FEATURE_FLAGS?": 'string[]',
-
-  // Custom validation
-  API_URL: (value: string) => {
-    try {
-      new URL(value);
-      return true;
-    } catch {
-      return false;
-    }
-  }
+  "FEATURE_FLAGS?": 'string[]'
 });
 ```
 
-## Common Patterns
+## Common patterns
 
-### Configuration Factory
+### Configuration factory
 
 Create a configuration factory to handle different environments:
 
-```typescript title="src/config/index.ts"
+```typescript title="src/config/index.ts" twoslash
 import arkenv from 'arkenv';
 
 const createConfig = () => {
@@ -230,35 +220,35 @@ const createConfig = () => {
 export const config = createConfig();
 ```
 
-### Feature Flags
+### Feature flags
 
 Use environment variables for feature flags:
 
-```typescript title="src/config/features.ts"
+```typescript title="src/config/features.ts" twoslash
 import arkenv from 'arkenv';
 
 export const env = arkenv({
-  "ENABLE_BETA_FEATURES?": 'boolean = false',
-  "MAINTENANCE_MODE?": 'boolean = false',
-  "ALLOWED_ORIGINS?": 'string[] = []'
+  "ENABLE_BETA_FEATURES": 'boolean = false',
+  "MAINTENANCE_MODE": 'boolean = false',
+  "ALLOWED_ORIGINS": 'string[]'
 });
 ```
 
 ## Troubleshooting
 
-### Common Issues
+### Common issues
 
-1. **Missing Variables**
+1. **Missing variables**
    - Check if `.env` file exists
    - Verify variable names match exactly
    - Ensure variables are loaded before use
 
-2. **Type Errors**
+2. **Type errors**
    - Verify variable types match schema
    - Check for typos in variable names
    - Ensure all required variables are provided
 
-3. **Loading Order**
+3. **Loading order**
    - Load environment variables before importing config
    - Consider using a bootstrap file
    - Check framework-specific loading behavior