feat: make runtimeEnv optional in Next.js and default to `process.e…

…nv` (#75)

.changeset/curly-beers-eat.md

@@ -0,0 +1,7 @@
+---
+"@t3-oss/env-nextjs": minor
+---
+
+introduce a new `experimental__runtimeEnv` that only requires manual destruction of client side variables.
+
+next.js 13.4.4 dropped the static analysis of serverside environment variables, which means that the manual destruction is no longer necessary for serverside variables

docs/package.json

@@ -16,7 +16,7 @@
     "class-variance-authority": "^0.4.0",
     "clsx": "^1.2.1",
     "lucide-react": "0.176.0",
-    "next": "^13.4.1",
+    "next": "^13.4.4",
     "next-themes": "^0.2.1",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",

docs/src/app/docs/nextjs/page.mdx

@@ -32,11 +32,16 @@ export const env = createEnv({
   client: {
     NEXT_PUBLIC_PUBLISHABLE_KEY: z.string().min(1),
   },
+  // If you're using Next.js < 13.4.4, you'll need to specify the runtimeEnv manually
   runtimeEnv: {
     DATABASE_URL: process.env.DATABASE_URL,
     OPEN_AI_API_KEY: process.env.OPEN_AI_API_KEY,
     NEXT_PUBLIC_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY,
   },
+  // For Next.js >= 13.4.4, you only need to destructure client variables:
+  // experimental__runtimeEnv: {
+  //   NEXT_PUBLIC_PUBLISHABLE_KEY: process.env.NEXT_PUBLIC_PUBLISHABLE_KEY,
+  // }
 });
 ```
 

examples/nextjs/app/env.mjs

@@ -8,8 +8,8 @@ export const env = createEnv({
   client: {
     NEXT_PUBLIC_GREETING: z.string(),
   },
-  runtimeEnv: {
-    SECRET: process.env.SECRET,
+
+  experimental__runtimeEnv: {
     NEXT_PUBLIC_GREETING: process.env.NEXT_PUBLIC_GREETING,
   },
 });

examples/nextjs/package.json

@@ -14,7 +14,7 @@
     "@types/react": "18.0.38",
     "@types/react-dom": "18.0.11",
     "eslint": "^8.39.0",
-    "next": "^13.4.1",
+    "next": "^13.4.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "typescript": "^5.0.4",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3-oss/env-root",
-  "packageManager": "pnpm@8.3.1",
+  "packageManager": "pnpm@8.6.3",
   "private": true,
   "type": "module",
   "scripts": {

packages/nextjs/index.ts

@@ -9,35 +9,65 @@ import {
 const CLIENT_PREFIX = "NEXT_PUBLIC_" as const;
 type ClientPrefix = typeof CLIENT_PREFIX;
 
-interface Options<
+type Options<
   TServer extends Record<string, ZodType>,
   TClient extends Record<`${ClientPrefix}${string}`, ZodType>
-> extends Omit<
-    StrictOptions<ClientPrefix, TServer, TClient> &
-      ServerClientOptions<ClientPrefix, TServer, TClient>,
-    "runtimeEnvStrict" | "runtimeEnv" | "clientPrefix"
-  > {
-  /**
-   * Manual destruction of `process.env`. Required for Next.js.
-   */
-  runtimeEnv: StrictOptions<ClientPrefix, TServer, TClient>["runtimeEnvStrict"];
-}
+> = Omit<
+  StrictOptions<ClientPrefix, TServer, TClient> &
+    ServerClientOptions<ClientPrefix, TServer, TClient>,
+  "runtimeEnvStrict" | "runtimeEnv" | "clientPrefix"
+> &
+  (
+    | {
+        /**
+         * Manual destruction of `process.env`. Required for Next.js < 13.4.4.
+         */
+        runtimeEnv: StrictOptions<
+          ClientPrefix,
+          TServer,
+          TClient
+        >["runtimeEnvStrict"];
+        experimental__runtimeEnv?: never;
+      }
+    | {
+        runtimeEnv?: never;
+        /**
+         * Can be used for Next.js ^13.4.4 since they stopped static analysis of server side `process.env`.
+         * Only client side `process.env` is statically analyzed and needs to be manually destructured.
+         */
+        experimental__runtimeEnv: Record<
+          {
+            [TKey in keyof TClient]: TKey extends `${ClientPrefix}${string}`
+              ? TKey
+              : never;
+          }[keyof TClient],
+          string | boolean | number | undefined
+        >;
+      }
+  );
 
 export function createEnv<
   TServer extends Record<string, ZodType> = NonNullable<unknown>,
   TClient extends Record<
     `${ClientPrefix}${string}`,
     ZodType
   > = NonNullable<unknown>
->({ runtimeEnv, ...opts }: Options<TServer, TClient>) {
+>(opts: Options<TServer, TClient>) {
   const client = typeof opts.client === "object" ? opts.client : {};
   const server = typeof opts.server === "object" ? opts.server : {};
 
+  const runtimeEnv = opts.runtimeEnv
+    ? opts.runtimeEnv
+    : {
+        ...process.env,
+        ...opts.experimental__runtimeEnv,
+      };
+
   return createEnvCore<ClientPrefix, TServer, TClient>({
     ...opts,
     client,
     server,
     clientPrefix: CLIENT_PREFIX,
-    runtimeEnvStrict: runtimeEnv,
+    runtimeEnv,
   });
 }

packages/nextjs/test/smoke.test.ts

@@ -78,6 +78,48 @@ test("runtimeEnv enforces all keys", () => {
   });
 });
 
+test("new experimental runtime option only requires client vars", () => {
+  ignoreErrors(() => {
+    createEnv({
+      server: { BAR: z.string() },
+      client: { NEXT_PUBLIC_BAR: z.string() },
+      // @ts-expect-error - NEXT_PUBLIC_BAR is missing
+      experimental__runtimeEnv: {},
+    });
+    createEnv({
+      server: { BAR: z.string() },
+      client: { NEXT_PUBLIC_BAR: z.string() },
+      experimental__runtimeEnv: {
+        // @ts-expect-error - BAR should not be specified
+        BAR: "bar",
+      },
+    });
+  });
+
+  process.env = {
+    BAR: "bar",
+    NEXT_PUBLIC_BAR: "foo",
+  };
+
+  const env = createEnv({
+    server: { BAR: z.string() },
+    client: { NEXT_PUBLIC_BAR: z.string() },
+    experimental__runtimeEnv: {
+      NEXT_PUBLIC_BAR: process.env.NEXT_PUBLIC_BAR,
+    },
+  });
+
+  expectTypeOf(env).toEqualTypeOf<{
+    BAR: string;
+    NEXT_PUBLIC_BAR: string;
+  }>();
+
+  expect(env).toMatchObject({
+    BAR: "bar",
+    NEXT_PUBLIC_BAR: "foo",
+  });
+});
+
 describe("return type is correctly inferred", () => {
   test("simple", () => {
     const env = createEnv({