feat: add environment variable validation

README.md

@@ -40,6 +40,7 @@
 - ⚙️ EditorConfig - Consistent coding styles across editors and IDEs
 - 🗂 Path Mapping — Import components or images using the `@` prefix
 - 🔐 CSP — Content Security Policy for enhanced security (default minimal policy)
+- 🧳 T3 Env — Type-safe environment variables
 
 ## Quick Start
 
@@ -127,6 +128,12 @@ This starter uses pnpm by default, but this choice is yours. If you'd like to sw
 
 > **Note:** If you use Yarn, make sure to follow these steps from the [Husky documentation](https://typicode.github.io/husky/troubleshoot.html#yarn-on-windows) so that Git hooks do not fail with Yarn on Windows.
 
+### Environment Variables
+
+We use [T3 Env](https://env.t3.gg/) to manage environment variables. Create a `.env.local` file in the root of the project and add your environment variables there.
+
+When adding additional environment variables, the schema in `./src/lib/env/client.ts` or `./src/lib/env/server.ts` should be updated accordingly.
+
 ## License
 
 This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for more information.

next.config.ts

@@ -1,5 +1,8 @@
 import type { NextConfig } from 'next';
 
+import './src/lib/env/client';
+import './src/lib/env/server';
+
 /**
  * CSPs that we're not adding (as it can change from project to project):
  * frame-src, connect-src, script-src, child-src, style-src, worker-src, font-src, media-src, and img-src

package.json

@@ -30,9 +30,11 @@
     ]
   },
   "dependencies": {
+    "@t3-oss/env-nextjs": "0.11.1",
     "next": "15.1.2",
     "react": "19.0.0",
-    "react-dom": "19.0.0"
+    "react-dom": "19.0.0",
+    "zod": "3.24.1"
   },
   "devDependencies": {
     "@commitlint/cli": "19.6.1",

src/lib/env/client.ts

@@ -0,0 +1,22 @@
+import { createEnv } from '@t3-oss/env-nextjs';
+
+export const clientEnv = createEnv({
+  /**
+   * Specify your client-side environment variables schema here. This way you can ensure the app
+   * isn't built with invalid env vars. To expose them to the client, prefix them with
+   * `NEXT_PUBLIC_`.
+   */
+  client: {},
+
+  experimental__runtimeEnv: {},
+  /**
+   * Run `build` or `dev` with `SKIP_ENV_VALIDATION` to skip env validation. This is especially
+   * useful for Docker builds.
+   */
+  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+  /**
+   * Makes it so that empty strings are treated as undefined.
+   * `SOME_VAR: z.string()` and `SOME_VAR=''` will throw an error.
+   */
+  emptyStringAsUndefined: true,
+});

src/lib/env/server.ts

@@ -0,0 +1,11 @@
+import { createEnv } from '@t3-oss/env-nextjs';
+import { z } from 'zod';
+
+export const serverEnv = createEnv({
+  server: {
+    NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  },
+  skipValidation: !!process.env.SKIP_ENV_VALIDATION,
+  emptyStringAsUndefined: true,
+  experimental__runtimeEnv: {},
+});