Server-only code and environment variables

A secret key that stays on the server

The tea shop asks its supplier how many cups of each tea are left. The supplier gave the shop a key, a secret string like a password, and only answers requests that carry it. Anyone who has the key can ask the supplier as if they were the shop. In Server Components in Next.js, a Server Component read that key, and the browser got only the stock. Three things keep it that way: a line that stops server code from reaching the browser, environment variables that hold the key outside your code, and care about what your components render and pass.

The key lives in an environment variable: a named setting that a running program gets from outside its code. Node.js, which runs Next.js on the server, puts them in process.env. A .env file at the top of the project is where you write them while you work: Next.js reads it into process.env when it starts. This example is a real Next.js 16.4.3 project, built with next build and run with next start:

1import "server-only";2 3// A stand-in for the supplier's stock service. A real one would send the key with each request.4export async function getStock(id: string) {5  const key = process.env.SUPPLIER_KEY;6  if (!key) return null;7  const stock: Record<string, number> = { green: 12, mint: 0, lemon: 5 };8  return stock[id];9}

Click .env in the file tree: line 2 sets SUPPLIER_KEY to sk_tea_7Hq2xP, and line 1 is a comment. lib/supplier.ts is shared code beside app, so it has no address. Line 1, import "server-only", marks it as code for the server only. Line 5 reads the key, line 6 gives up without one, and lines 7 and 8 stand in for the supplier's answer. In app/page.tsx, line 4 waits for getStock("green"), and line 8 shows the result.

Open the Terminal tab. The line - Environments: .env, near the top, says Next.js loaded the file. The page built as ○ /. The Network tab has two responses. The first is the page's HTML: the visible page shows 12 in stock and no key. The second is the page's RSC payload, which the recording asked for with the rsc: 1 header: the description of what the Server Components rendered, with the props for any Client Components. On a first visit, Next.js sends that same payload inside the HTML response, in inline scripts. It holds 12, and no key. The recording also searched the JavaScript files the page loads: neither sk_tea_7Hq2xP nor the name SUPPLIER_KEY is in them.

server-only and client-only

Nothing stops another file from importing lib/supplier.ts. If a Client Component imports it, the module becomes client code too, the way Composing Server and Client Components showed for components. Try it: here the supplier's module is imported by the page, then by a Client Component, then by the same Client Component with the server-only line in place.

1import "server-only";2 3// A stand-in for the supplier's stock service. A real one would send the key with each request.4export async function getStock(id: string) {5  const key = process.env.SUPPLIER_KEY;6  if (!key) return null;7  const stock: Record<string, number> = { green: 12, mint: 0, lemon: 5 };8  return stock[id];9}

What happened in each version:

• Imported by the page: the page is a Server Component, so the module stays on the server. This is the overview's example.
• Imported by a Client Component, without server-only: the build passes. StockBadge calls getStock in an Effect, in the browser. The recording found the name SUPPLIER_KEY in the page's JavaScript, but not the key: in the browser, process.env.SUPPLIER_KEY has no value, so getStock returns null and the page says Stock unknown. Nothing logged an error. The secret didn't leak, but the module's code did, and the page quietly stopped working.
• With server-only: the build stops. The recording printed two messages for line 1. The second says it plainly: 'server-only' cannot be imported from a Client Component module. It should only be used from a Server Component. (The first one mentions the Pages Router, which this app doesn't use.) The import trace under it lists ./app/stock-badge.tsx [Client Component Browser]: the file to fix.

So import "server-only" turns a quiet mistake into a build error that names the file. The client-only line does the opposite, for code that only works in the browser, like code that uses localStorage:

1import { rememberTea } from "@/lib/recent";2 3export default function GreenTeaPage() {4  rememberTea("green");5  return (6    <main>7      <h1>Green tea</h1>8    </main>9  );10}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ... > Build error occurredError: Turbopack build failed with 2 errors:./lib/recent.ts:1:1Error: You're importing a component that imports client-only. It only works in a Client Component but none of its parents are marked with "use client", so they're Server Components by default.    Learn more: https://nextjs.org/docs/app/building-your-application/rendering> 1 | import "client-only";    | ^^^^^^^^^^^^^^^^^^^^^  2 |  3 | // Remembers the teas this visitor looked at, in the browser's localStorage.  4 | export function rememberTea(id: string) { Ecmascript file had an error Import trace:  Server Component:    ./lib/recent.ts    ./app/page.tsx ./lib/recent.ts:1:1Error: 'client-only' cannot be imported from a Server Component module> 1 | import "client-only";    | ^^^^^^^^^^^^^^^^^^^^^  2 |  3 | // Remembers the teas this visitor looked at, in the browser's localStorage.  4 | export function rememberTea(id: string) { It should only be used from a Client Component. Import trace:  Server Component:    ./lib/recent.ts    ./app/page.tsx     at ignore-listed frames

Line 1 of app/page.tsx imports rememberTea from lib/recent.ts, whose line 1 is import "client-only", and line 4 calls it while the page renders, on the server, where there's no localStorage. The build stops: 'client-only' cannot be imported from a Server Component module.

In Next.js you don't have to install either package. Next.js handles both imports itself and doesn't use the packages' own code: the recorded project's package.json is the one create-next-app writes, and it lists neither. If your linter complains about a package that isn't installed, install it with npm install server-only.

.env files and their load order

A project can have several .env files: one for every environment, one for each kind of environment, and private copies of each. Here the tea shop has five, and four variables. Each value says which file it's from.

1export default function Home() {2  return (3    <main>4      <h1>Tea shop</h1>5      <p>{process.env.WELCOME}</p>6      <p>{process.env.CURRENCY}</p>7      <p>{process.env.SALE}</p>8      <p>{process.env.SUPPORT}</p>9    </main>10  );11}

Lines 5 to 8 of app/page.tsx show WELCOME, CURRENCY, SALE and SUPPORT. Click through the .env files in the tree, then open the Browser tab. Each variable came from a different file:

• WELCOME is in all four files the build reads, and came from .env.production.local.
• CURRENCY is in .env.local, .env.production and .env, and came from .env.local: EUR.
• SALE came from .env.production. .env.development says Everything free, but the build never read it.
• SUPPORT is only in .env, so it came from there.

For each variable, Next.js looks in a fixed order and stops at the first place that has it. The order depends on NODE_ENV, a variable that says which kind of environment this is. Unless it's already set, Next.js sets it to development for next dev and to production for next build and next start. Test runners set it to test. The Terminal tab's first lines show the files the build loaded, in that order: - Environments: .env.production.local, .env.local, .env.production, .env. Each row is one place, from first to last:

A variable already set in the real environment wins over every file: one your shell sets, or one your host sets for the server. That's how a hosting service gives the production server its secrets without any file. With NODE_ENV set to test, .env.local is skipped, so tests get the same values on every machine.

NEXT_PUBLIC_ variables are inlined at build

Some values have to reach the browser. The shop counts visits with an analytics service, and the browser sends the shop's analytics id with each one. That id isn't a secret. Give a variable a name that starts with NEXT_PUBLIC_, and Next.js inlines it: during next build, in the code that goes to the browser, it replaces process.env.NEXT_PUBLIC_ANALYTICS_ID with the value itself, as text.

1"use client";2 3export default function Stats() {4  return <footer>Visits counted for {process.env.NEXT_PUBLIC_ANALYTICS_ID}</footer>;5}

The .env file now has two variables: SUPPLIER_KEY and NEXT_PUBLIC_ANALYTICS_ID. Line 4 of app/stats.tsx, a Client Component, reads the second. The page shows Visits counted for tea-stats-204, on the server and again in the browser, and Chrome logged no error. The recording searched the page's JavaScript and found tea-stats-204, but not the name NEXT_PUBLIC_ANALYTICS_ID: the name was replaced. It didn't find sk_tea_7Hq2xP. A variable without the prefix is never copied in.

Next.js's docs promise this replacement for process.env.NEXT_PUBLIC_… written out directly, so write it that way. A name that can't be known during the build, like process.env[variable] with the name passed in as a prop, isn't replaced, and has no value in the browser. Server code can read NEXT_PUBLIC_ variables too: on the server they're ordinary environment variables, and a server-only module that reads one sends nothing to the browser. Next.js collects them in getNextPublicEnvironmentVariables, which makes a replacement for each variable whose name starts with NEXT_PUBLIC_.

Build-time and runtime variables

Inlining happens during the build, so a NEXT_PUBLIC_ value is fixed when next build runs. Changing it afterwards changes nothing until you build again. Server variables are read when the code that uses them runs. With Cache Components on, as new apps have it and every example here does, Next.js prerenders during the build every part of a page that doesn't wait for a request, so that can be during the build too. Try two versions of a home page that shows WELCOME, with the same .env:

1export default function Home() {2  return (3    <main>4      <h1>Tea shop</h1>5      <p>{process.env.WELCOME}</p>6    </main>7  );8}

$ next build▲ Next.js 16.4.3 (Turbopack)- Environments: .env- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

The first version reads WELCOME while the page renders, and nothing in it waits for a request. So the build renders it and saves the HTML: ○ /, prerendered as static content. The value is in that saved page, and Cache-Control: s-maxage=31536000 lets caches keep it for a year. Change WELCOME on the server after the build, and visitors still get the old value. The second version calls connection() from next/server first, which waits for a real request. Now the build can't read WELCOME for that part, so it builds ◐ /: the shell with Loading…, and WELCOME read for each request, from the running server's environment. Its Network tab shows Cache-Control: private, no-cache, no-store….

This matters when one build runs in several places, like a staging server and the real one. Next.js's docs suggest reading such values on the server, at request time, and sending the browser what it needs. cookies() and headers() wait for a request too; Request-time APIs teaches them.

Spotting a leaked secret

server-only and the prefix guard the code and the JavaScript. They don't guard what your components do with a value. Here are four ways the supplier's key gets out, and one fixed version. Before you open each one, guess where the key will be: in the visible page, in the RSC payload, or in the JavaScript. The Network tab opens on each version's RSC payload; the HTML is the first response.

1import { getStock } from "@/lib/supplier";2 3export default async function GreenTeaPage() {4  const stock = await getStock("green");5  return (6    <main>7      <h1>Green tea</h1>8      <p>{stock} in stock</p>9      <p>Debug: key {process.env.SUPPLIER_KEY}</p>10    </main>11  );12}

#1:"$Sreact.fragment"
2:"/_next/static/chunks/1tq6ppe__m8m-.js"
3:I[39756,["$2"],"default"]
4:I[37457,["$2"],"default"]
8:I[97367,["$2"],"OutletBoundary"]
9:"$Sreact.suspense"
c:"ViewportBoundary"
d:I[97367,["$2"],"$c"]
f:"MetadataBoundary"
10:I[97367,["$2"],"$f"]
13:I[68027,["$2"],"default",1]
5:X
b:X
6:[["children",{"s":"__PAGE__","h":514,"d":{"r":["$","$1","c",{"children":["$L7",null,["$","$L8",null,{"children":["$","$9",null,{"name":"Next.MetadataOutlet","children":"$@a"}]}]]}],"p":true,"v":"$b"}}]]
12:X
14:X
15:X
0:{"P":null,"c":["",""],"q":"","i":false,"t":{"t":{"s":"","h":530,"d":{"r":["$","$1","c",{"children":[[["$","script","script-0",{"src":"/_next/static/chunks/1tq6ppe__m8m-.js","async":true,"nonce":"$undefined"}]],["$","html",null,{"lang":"en","children":["$","body",null,{"children":["$","$L3",null,{"parallelRouterKey":"children","error":"$undefined","errorStyles":"$undefined","errorScripts":"$undefined","template":["$","$L4",null,{}],"templateStyles":"$undefined","templateScripts":"$undefined","notFound":[[["$","title",null,{"children":"404: This page could not be found."}],["$","div",null,{"style":{"fontFamily":"system-ui,\"Segoe UI\",Roboto,Helvetica,Arial,sans-serif,\"Apple Color Emoji\",\"Segoe UI Emoji\"","height":"100vh","textAlign":"center","display":"flex","flexDirection":"column","alignItems":"center","justifyContent":"center"},"children":["$","div",null,{"children":[["$","style",null,{"dangerouslySetInnerHTML":{"__html":"body{color:#000;background:#fff;margin:0}.next-error-h1{border-right:1px solid rgba(0,0,0,.3)}@media (prefers-color-scheme:dark){body{color:#fff;background:#000}.next-error-h1{border-right:1px solid rgba(255,255,255,.3)}}"}}],["$","h1",null,{"className":"next-error-h1","style":{"display":"inline-block","margin":"0 20px 0 0","padding":"0 23px 0 0","fontSize":24,"fontWeight":500,"verticalAlign":"top","lineHeight":"49px"},"children":404}],["$","div",null,{"style":{"display":"inline-block"},"children":["$","h2",null,{"style":{"fontSize":14,"fontWeight":400,"lineHeight":"49px","margin":0},"children":"This page could not be found."}]}]]}]}]],[]],"forbidden":"$undefined","unauthorized":"$undefined"}]}]}]]}],"p":true,"v":"$5"},"c":"$Q6"},"h":{"r":["$","$1","h",{"children":[null,["$","$Ld",null,{"children":"$Le"}],["$","$L10",null,{"children":[["$","div",null,{"hidden":true,"children":["$","$9",null,{"name":"Next.Metadata","children":"$L11"}]}],null]}],null]}],"p":true,"v":"$12"}},"m":"$undefined","G":["$13",[]],"S":true,"r":"$14","s":"$15","a":"$@16","l":"$undefined","p":"$undefined","d":"$undefined","b":"Mzbuc8ht6qo9g2YWRiFbn","u":"$@17"}
15:300
7:["$","main",null,{"children":[["$","h1",null,{"children":"Green tea"}],["$","p",null,{"children":[12," in stock"]}],["$","p",null,{"children":["Debug: key ","sk_tea_7Hq2xP"]}]]}]
e:[["$","meta","0",{"charSet":"utf-8"}],["$","meta","1",{"name":"viewport","content":"width=device-width, initial-scale=1"}]]
a:null
11:[["$","title","0",{"children":"Tea shop"}]]
15:C
12:C
14:C
b:C
5:C
17:false
16:null

Where the key ended up:

• Rendered by a Server Component. A Server Component's code stays on the server, but its output doesn't: the visible page says Debug: key sk_tea_7Hq2xP, and the RSC payload carries the same text. A debug line like this is easy to forget.
• Passed in a prop. The badge shows only Supplied by Green Hills, but props for a Client Component travel whole. The visible page has no key, but the RSC payload has "key":"sk_tea_7Hq2xP" in it. On a first visit, that payload is inside the HTML response, in inline scripts: anyone who views the page's source can find it.
• Read in a Client Component. In the browser, process.env.SUPPLIER_KEY has no value, so it can seem harmless. But the build also renders Client Components on the server, where it has one: the visible page says Debug: key sk_tea_7Hq2xP. The RSC payload doesn't have it: for a Client Component with no props, the payload only points at the component's code. Then React runs the component in the browser, where it expects the same result as the server's HTML. It gets a different one, and reports error #418, a hydration mismatch.
• Renamed NEXT_PUBLIC_SUPPLIER_KEY, so the browser could call the supplier itself. It works, and the build copies the key into the JavaScript, where anyone can read it.
• Fixed: line 7 passes only name="Green Hills". The recordings found the key nowhere.

Each row is one version, and whether the recording found the key in each place. The visible page is what the browser shows. The RSC payload was recorded with rsc: 1; on a first visit it also arrives inside the HTML response.

The fix is always the same: decide what the browser needs, and send only that. For the stock, that's a number. Next.js's data security guide goes further: keep every read of secrets and private data in one server-only module, a data access layer, which returns only the fields a page needs (Authorization and the data access layer).

The Building real apps stage comes back to security.

Checking the tea shop before you deploy

Before you deploy the shop, check the three places a secret can show up. Take the first characters of each secret, like sk_tea_, and search for them:

• The HTML response. Open each page, view its source, and search. On a first visit, the RSC payload is in the response's inline scripts, so this checks the visible page, rendered values and props together.
• The RSC payload of a navigation. In the browser's developer tools, open the Network panel, click a link, and search the responses whose type is text/x-component.
• The JavaScript. After next build, search the files the browser downloads, which are under .next/static. This is the same search the recordings in this lesson made:

npm run build
grep -rl "sk_tea_" .next/static

Line 1 builds the app. Line 2 searches every file under .next/static and prints the names of those that contain sk_tea_. No output means no file has it. Then sort the shop's settings: which ones may get the prefix?

Common mix-ups

• "A Client Component can't leak a server variable, because it has no value in the browser." No. The build also renders Client Components on the server, where the variable has a value, and the recorded visible page had the key in it.
• "A file without an address, like lib/supplier.ts, is safe." No. A Client Component that imports it sends its code to the browser. import "server-only" turns that into a build error.
• "Only what a component shows is sent." No. Props for a Client Component are sent whole, in the RSC payload, including fields it never shows.
• "NEXT_PUBLIC_ values are read when the page loads." No. They're copied into the JavaScript during next build, and stay that way until the next build.
• ".env.local always wins." No. During next build, .env.production.local comes before it, and a variable set in the real environment wins over every file.
• "You must install server-only for it to work." No. Next.js handles the import itself. Install the package only if your linter asks for it.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

# .env.local
WELCOME=Welcome (from .env.local)
CURRENCY=EUR (from .env.local)

# .env.production
WELCOME=Welcome (from .env.production)
CURRENCY=USD (from .env.production)
SALE=Two for one (from .env.production)

# .env
WELCOME=Welcome (from .env)
CURRENCY=USD (from .env)
SALE=No sale today (from .env)
SUPPORT=help@tea.example (from .env)

"use client";

export default function Stats() {
  return <footer>Visits counted for {process.env.NEXT_PUBLIC_ANALYTICS_ID}</footer>;
}

"use client";

import { useEffect, useState } from "react";
import { getStock } from "@/lib/supplier";

export default function StockBadge() {
  const [stock, setStock] = useState<number | null>(null);
  useEffect(() => {
    getStock("green").then(setStock);
  }, []);
  return <p>{stock === null ? "Stock unknown" : `${stock} in stock`}</p>;
}

import { getStock } from "@/lib/supplier";
import StockBadge from "./stock-badge";

export default async function GreenTeaPage() {
  const stock = await getStock("green");
  return (
    <main>
      <h1>Green tea</h1>
      <StockBadge stock={stock} />
    </main>
  );
}

import SupplierBadge from "./supplier-badge";

export default function GreenTeaPage() {
  const supplier = { name: "Green Hills", key: process.env.SUPPLIER_KEY };
  return (
    <main>
      <h1>Green tea</h1>
      <SupplierBadge supplier={supplier} />
    </main>
  );
}

import SupplierBadge from "./supplier-badge";

export default function GreenTeaPage() {
  return (
    <main>
      <h1>Green tea</h1>
      <SupplierBadge name="Green Hills" />
    </main>
  );
}

"use client";

export default function Stats({ variable }: { variable: string }) {
  return <footer>Visits counted for {process.env[variable] ?? "nobody"}</footer>;
}

"use client";

export default function Stats() {
  return <footer>Visits counted for {process.env.NEXT_PUBLIC_ANALYTICS_ID}</footer>;
}

import { rememberTea } from "@/lib/recent";

export default function GreenTeaPage() {
  rememberTea("green");
  return (
    <main>
      <h1>Green tea</h1>
    </main>
  );
}

"use client";

import { useEffect } from "react";
import { rememberTea } from "@/lib/recent";

export default function Remember({ id }: { id: string }) {
  useEffect(() => {
    rememberTea(id);
  }, [id]);
  return null;
}

Check your understanding

For each question, ask where the code runs, when the value is read, and what reaches the browser.

Key takeaways

• Secrets go in environment variables without a prefix, read by modules that start with import "server-only". A Client Component that imports such a module stops the build.
• import "client-only" guards browser-only code the same way. Next.js handles both imports without the packages installed.
• Next.js reads .env files from the top folder and stops at the first place that has a variable: the real environment, then .env.production.local, .env.local, .env.production and .env during a build.
• NEXT_PUBLIC_ values are copied into the code that goes to the browser during next build. Write process.env.NEXT_PUBLIC_… directly. They're public and fixed until the next build.
• A page prerendered as ○ keeps the server values it read during the build. Read them after connection(), inside Suspense, to get each request's value.
• A secret leaks through the visible page, the RSC payload (which also arrives inside the HTML response) or the JavaScript. Look in all three, and send the browser only what it needs.

Coming next: CSS in Next.js, the first lesson of the Styling, assets and metadata stage: global styles, CSS Modules and Sass, and how Next.js orders and splits your CSS.