Add type safety to environment variables

Author: RamiroG8k

.env.example

@@ -0,0 +1,5 @@
+# Client
+NEXT_PUBLIC_VERCEL_URL="http://localhost:3000"
+
+# Server
+NODE_ENV="development"

declarations.d.ts

@@ -0,0 +1,16 @@
+import z from 'zod';
+import { clientSchema, serverSchema } from '@/env/schema.mjs';
+
+declare module '*.svg' {
+    import React from 'react';
+    const SVG: React.VFC<React.SVGProps<SVGSVGElement>>;
+    export default SVG;
+};
+
+type EnvSchemaType = z.infer<typeof clientSchema> & z.infer<typeof serverSchema>;
+
+declare global {
+    namespace NodeJS {
+        interface ProcessEnv extends EnvSchemaType {}
+    }
+};

next.config.mjs

@@ -1,3 +1,5 @@
+import './src/env/index.mjs';
+
 /** @type {import('next').NextConfig} */
 const nextConfig = {};
 

package.json

@@ -3,25 +3,26 @@
   "version": "0.1.0",
   "private": true,
   "scripts": {
-    "dev": "next dev",
+    "start:local": "next dev",
+    "start:build": "next start",
     "build": "next build",
-    "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint --fix"
   },
   "dependencies": {
-    "react": "^18",
-    "react-dom": "^18",
-    "next": "14.1.0"
+    "next": "14.1.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "zod": "^3.22.4"
   },
   "devDependencies": {
-    "typescript": "^5",
-    "@types/node": "^20",
-    "@types/react": "^18",
-    "@types/react-dom": "^18",
-    "autoprefixer": "^10.0.1",
-    "postcss": "^8",
-    "tailwindcss": "^3.3.0",
-    "eslint": "^8",
-    "eslint-config-next": "14.1.0"
+    "@types/node": "^20.11.5",
+    "@types/react": "^18.2.48",
+    "@types/react-dom": "^18.2.18",
+    "autoprefixer": "^10.4.17",
+    "eslint": "^8.56.0",
+    "eslint-config-next": "14.1.0",
+    "postcss": "^8.4.33",
+    "tailwindcss": "^3.4.1",
+    "typescript": "^5.3.3"
   }
 }

pnpm-lock.yaml

@@ -0,0 +1,19 @@
+import { formatErrors } from './format.mjs';
+import { clientEnv, clientSchema } from './schema.mjs';
+
+const _clientEnv = clientSchema.safeParse(clientEnv);
+
+if (_clientEnv.success === false) {
+  console.error('❌ Invalid environment variables:\n', ...formatErrors(_clientEnv.error.format()));
+  throw new Error('Invalid environment variables');
+}
+
+// Validate client-side env are exposed to the client
+for (const key of Object.keys(_clientEnv.data)) {
+  if (!key.startsWith('NEXT_PUBLIC_')) {
+    console.warn('❌ Invalid public environment variable name:\n', key);
+    throw new Error('Invalid public environment variable name');
+  }
+}
+
+export const env = _clientEnv.data;

src/env/client.mjs

@@ -0,0 +1,9 @@
+export const formatErrors = (
+    /** @type { import('zod').ZodFormattedError<Map<string, string>, string> } */
+    errors
+  ) =>
+    Object.entries(errors)
+      .map(([name, value]) => {
+        if (value && '_errors' in value) return `${name}: ${value._errors.join(', ')}\n`;
+      })
+      .filter(Boolean);

src/env/format.mjs

@@ -0,0 +1,6 @@
+import { env as client } from './client.mjs';
+import { env as server } from './server.mjs';
+
+const env = { ...client, ...server };
+
+export default env;

src/env/index.mjs

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+
+export const serverSchema = z.object({
+	NODE_ENV: z.enum(['development', 'production']).default('development')
+});
+
+export const clientSchema = z.object({
+	NEXT_PUBLIC_VERCEL_URL: z.string().url()
+});
+
+/**
+ * @type {{ [k in keyof z.infer<typeof clientSchema>]: z.infer<typeof clientSchema>[k] | undefined }}
+ */
+export const clientEnv = {
+	NEXT_PUBLIC_VERCEL_URL: process.env.NEXT_PUBLIC_VERCEL_URL
+};

src/env/schema.mjs

@@ -0,0 +1,19 @@
+import { formatErrors } from './format.mjs';
+import { serverSchema } from './schema.mjs';
+
+const _serverEnv = serverSchema.safeParse(process.env);
+
+if (_serverEnv.success === false) {
+  console.error('❌ Invalid environment variables:\n', ...formatErrors(_serverEnv.error.format()));
+  throw new Error('Invalid environment variables');
+}
+
+// Validate server-side env are not exposed to the client
+for (const key of Object.keys(_serverEnv.data)) {
+  if (key.startsWith('NEXT_PUBLIC_')) {
+    console.warn('❌ You are exposing a server-side env:\n');
+    throw new Error('You are exposing a server-side env');
+  }
+}
+
+export const env = _serverEnv.data;

src/env/server.mjs

@@ -12,15 +12,13 @@
     "isolatedModules": true,
     "jsx": "preserve",
     "incremental": true,
-    "plugins": [
-      {
-        "name": "next"
-      }
-    ],
+    "baseUrl": ".",
+    "plugins": [{ "name": "next" }],
     "paths": {
       "@/*": ["./src/*"]
     }
   },
   "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
+  "exclude": ["node_modules"],
+  "files": ["declarations.d.ts"]
 }