Add playground-to-example sync infrastructure

.github/workflows/sync-examples.yml

@@ -0,0 +1,41 @@
+name: sync-examples
+
+on:
+  pull_request:
+    paths:
+      - "apps/playgrounds/**"
+      - "examples/**"
+      - "bin/sync-examples.js"
+  push:
+    branches: ["main"]
+    paths:
+      - "apps/playgrounds/**"
+      - "examples/**"
+      - "bin/sync-examples.js"
+
+permissions:
+  contents: read
+
+jobs:
+  check-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build packages
+        run: pnpm build:packages
+
+      - name: Check examples sync
+        run: pnpm sync:examples:check

apps/playgrounds/bun-react/package.json

@@ -22,5 +22,11 @@
 		"@types/react": "catalog:",
 		"@types/react-dom": "catalog:",
 		"rimraf": "catalog:"
-	}
+	},
+	"arkenvExamples": [
+		{
+			"name": "with-bun-react",
+			"packageManager": "bun"
+		}
+	]
 }

apps/playgrounds/bun/package.json

@@ -4,10 +4,9 @@
 	"type": "module",
 	"private": true,
 	"scripts": {
-		"dev": "bun --watch .",
-		"start": "bun .",
-		"build": "bun build . --outdir=dist",
-		"preview": "bun dist",
+		"dev": "bun --watch run index.ts",
+		"start": "bun run index.ts",
+		"build": "bun build index.ts --outdir ./dist",
 		"fix": "pnpm -w run fix",
 		"clean": "rimraf dist node_modules"
 	},
@@ -19,5 +18,11 @@
 		"@types/bun": "catalog:",
 		"rimraf": "catalog:",
 		"typescript": "catalog:"
-	}
+	},
+	"arkenvExamples": [
+		{
+			"name": "with-bun",
+			"packageManager": "bun"
+		}
+	]
 }

apps/playgrounds/js/README.md

@@ -0,0 +1,77 @@
+# ArkEnv basic example (plain JavaScript)
+
+This example shows how to use ArkEnv in a basic Node.js application.
+
+
+## What's inside?
+
+The example demonstrates:
+- Setting up environment variables with ArkEnv
+- Using default values
+- Runtime-validated environment configuration
+
+## Getting started
+
+### Prerequisites
+
+Make sure you have [Node.js](https://nodejs.org) installed. We recommend using [nvm](https://github.com/nvm-sh/nvm) to install it.
+
+### Quickstart
+
+1. #### Install dependencies
+    ```bash
+    npm install
+    ```
+
+2. #### Start the development server with hot reloading enabled
+    ```bash
+    npm run dev
+    ```
+    :white_check_mark: You will see the environment variables printed in the console.
+
+### Adding environment variables
+
+With the development server running (if it isn't - just run `npm run dev`), let's see how to add a new environment variable. For this example, we'll add a new environment variable called `MY_ENV_VAR`.
+
+1. #### Define the new environment variable in the schema as a _required_ string
+    ```javascript
+    // index.js
+    const env = arkenv({
+        // other definitions...
+        MY_ENV_VAR: "string"
+    });
+    ```
+
+2. #### Notice the development server will show an error
+    ```bash
+    ArkEnvError: Errors found while validating environment variables
+      MY_ENV_VAR must be a string (was missing)
+    ```
+    This is **good**! It means the environment variable is required and the type is enforced. Let's see how to fix it. For this example, we will define the environment variable [with a `.env` file](https://arkenv.js.org/docs/arkenv/how-to/load-environment-variables#using-env-files).
+
+3. #### Copy the `.env.example` file to `.env`
+
+    To keep the development server running, run this command in a new terminal window:
+    ```bash
+    cp .env.example .env
+    ```
+
+4. #### Add a new environment variable to the `.env` file
+    ```bash
+    echo "MY_ENV_VAR=new_value" >> .env
+    ```
+
+    Notice the development server will once again print the existing environment variables.
+
+5. #### Add the following line to the `index.js` file
+    ```javascript
+    console.log(env.MY_ENV_VAR);
+    ```
+    You will see the new environment variable printed in the console.
+
+    **Congratulations!** :tada: You've just added a new environment variable and printed its value.
+
+### Next steps
+
+- [ArkEnv docs](https://arkenv.js.org/docs/arkenv)
+- [ArkType docs](https://arktype.io/)

apps/playgrounds/js/index.js

@@ -0,0 +1,17 @@
+import arkenv from "arkenv";
+
+const env = arkenv({
+	HOST: "string.host",
+	PORT: "number.port",
+	NODE_ENV: "'development' | 'production' | 'test' = 'development'",
+});
+
+// Automatically validate and parse process.env
+// TypeScript knows the ✨exact✨ types!
+const host = env.HOST;
+const port = env.PORT;
+const nodeEnv = env.NODE_ENV;
+
+console.log({ host, port, nodeEnv });
+
+export default env;

apps/playgrounds/js/package.json

@@ -0,0 +1,28 @@
+{
+	"name": "js-playground",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"start": "node --env-file .env index.js",
+		"dev": "node --watch --env-file .env index.js",
+		"dev:example": "node --watch --env-file .env.example index.js",
+		"fix": "pnpm -w run fix",
+		"clean": "rimraf dist node_modules"
+	},
+	"dependencies": {
+		"arkenv": "workspace:*",
+		"arktype": "catalog:"
+	},
+	"engines": {
+		"node": "24"
+	},
+	"stackblitz": {
+		"startCommand": "npm install && npm run dev:example"
+	},
+	"arkenvExamples": [
+		{
+			"name": "basic-js",
+			"packageManager": "npm"
+		}
+	]
+}

apps/playgrounds/js/tsconfig.json

@@ -0,0 +1,12 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "Bundler",
+		"esModuleInterop": true,
+		"strict": true,
+		"skipLibCheck": true,
+		"forceConsistentCasingInFileNames": true,
+		"outDir": "./dist"
+	}
+}

apps/playgrounds/node/README.md

@@ -1,6 +1,77 @@
-# Playground
+# ArkEnv basic example
 
-A free TypeScript playground for testing ArkEnv.
+This example shows how to use ArkEnv in a basic Node.js application.
 
-> [!TIP]
-> This app uses `workspace:*` for the package version, allowing you to test your local changes. You must build the package after making changes.
+
+## What's inside?
+
+The example demonstrates:
+- Setting up environment variables with ArkEnv
+- Using default values
+- Typesafe environment configuration
+
+## Getting started
+
+### Prerequisites
+
+Make sure you have [Node.js](https://nodejs.org) installed. We recommend using [nvm](https://github.com/nvm-sh/nvm) to install it.
+
+### Quickstart
+
+1. #### Install dependencies
+    ```bash
+    npm install
+    ```
+
+2. #### Start the development server with hot reloading enabled
+    ```bash
+    npm run dev
+    ```
+    :white_check_mark: You will see the environment variables printed in the console.
+
+### Adding environment variables
+
+With the development server running (if it isn't - just run `npm run dev`), let's see how to add a new environment variable. For this example, we'll add a new environment variable called `MY_ENV_VAR`.
+
+1. #### Define the new environment variable in the schema as a _required_ string
+    ```typescript
+    // index.ts
+    const env = arkenv({
+        // other definitions...
+        MY_ENV_VAR: "string"
+    });
+    ```
+
+2. #### Notice the development server will show an error
+    ```bash
+    ArkEnvError: Errors found while validating environment variables
+      MY_ENV_VAR must be a string (was missing)
+    ```
+    This is **good**! It means the environment variable is required and the type is enforced. Let's see how to fix it. For this example, we will define the environment variable [with a `.env` file](https://arkenv.js.org/docs/arkenv/how-to/load-environment-variables#using-env-files).
+
+3. #### Copy the `.env.example` file to `.env`
+
+    To keep the development server running, run this command in a new terminal window:
+    ```bash
+    cp .env.example .env
+    ```
+
+4. #### Add a new environment variable to the `.env` file
+    ```bash
+    echo "MY_ENV_VAR=new_value" >> .env
+    ```
+
+    Notice the development server will once again print the existing environment variables.
+
+5. #### Add the following line to the `index.ts` file
+    ```typescript
+    console.log(env.MY_ENV_VAR);
+    ```
+    You will see the new environment variable printed in the console.
+
+    **Congratulations!** :tada: You've just added a new environment variable and printed its value.
+
+### Next steps
+
+- [ArkEnv docs](https://arkenv.js.org/docs/arkenv)
+- [ArkType docs](https://arktype.io/)

apps/playgrounds/node/package.json

@@ -3,8 +3,10 @@
 	"private": true,
 	"type": "module",
 	"scripts": {
-		"dev": "tsx watch --env-file .env index.ts",
 		"start": "tsx --env-file .env index.ts",
+		"dev": "tsx watch --env-file .env index.ts",
+		"dev:example": "tsx watch --env-file .env.example index.ts",
+		"build": "tsc",
 		"fix": "pnpm -w run fix",
 		"clean": "rimraf dist node_modules"
 	},
@@ -16,6 +18,19 @@
 	"devDependencies": {
 		"@types/node": "catalog:",
 		"rimraf": "catalog:",
-		"tsx": "catalog:"
-	}
+		"tsx": "catalog:",
+		"typescript": "catalog:"
+	},
+	"engines": {
+		"node": "24"
+	},
+	"stackblitz": {
+		"startCommand": "npm install && npm run dev:example"
+	},
+	"arkenvExamples": [
+		{
+			"name": "basic",
+			"packageManager": "npm"
+		}
+	]
 }