A Plain Array of Strings Took Down Every Signed-In Page
Bakery Buddy has a small, boring file now: five lines of decline reasons, the presets behind the "Decline" button on an inquiry. There's nothing interesting about the list itself. Where it used to live is the whole story.
A line Next.js draws that your tools can't see
Next.js's App Router splits every file into one of two worlds. A server component runs only on the server and can import anything it wants. A `'use client'` component ships into the browser bundle along with everything it imports. The rule that matters is about crossing between them.
A server component is allowed to render a client component. That's most of the app: a page imports `OrdersListView`, which has `'use client'` at the top, and that's fine, because rendering a component just means handing JSX to the browser.
What a server component can't do is import a plain value out of a file that starts with `'use client'`, a constant, a function, anything that isn't a component. In a production build, the exports of a client file stop being the values you wrote. They become client reference proxies, markers telling the bundler "render this on the client," and a proxy is not the value standing in for it.
Twenty minutes was long enough
The decline reasons array first lived inside `dispatchOrderAction.ts`. That's a server file, and it's a server file for a reason: it imports `requireBakery`, which resolves who's asking and which bakery they belong to, which imports the staff-impersonation code, which imports `next/headers`.
`DeclineOrderModal`, the client component with the actual "Decline" button, needed that same list of reasons to fill its dropdown. So it imported it, directly, from `dispatchOrderAction.ts`.
That single import dragged the whole chain into the browser bundle, from `dispatchOrderAction` to `requireBakery` to the impersonation code to `next/headers`, a module that only exists on the server and has no business anywhere near a browser. Every signed-in page in the app started returning the same 500, two errors stacked on top of each other: "You're importing a module that depends on next/headers," and underneath it, Clerk's own "'server-only' cannot be imported from a Client Component."
The array lived in that file for about twenty minutes before anyone noticed. `npx tsc --noEmit` passed the whole time. `eslint --max-warnings 0` passed too. Both of those check that the code is valid and the types line up, and the code was valid, and the types did line up. Neither one knows what a bundler does with an import once it decides where that code is going to run. The only thing that caught it was opening a page in a real browser and watching it fail.
The same rule, broken the other way around first
This wasn't the first time Bakery Buddy hit this line. It's the second half of a rule that already had a scar on the other side.
Earlier, a server page seeding the first page of the Orders table imported two plain values straight out of `OrdersListView`, a `'use client'` component: a list of default status filters, and a function that builds a cache key. The build was clean. The types checked out. In production, spreading that status list threw "is not iterable," because the array wasn't an array anymore once it crossed out of a client file's exports, it was a reference proxy with nothing to spread. The Customers page had the identical shape of bug, throwing "Attempted to call customersSignature() from the server but customersSignature is on the client." Both pages went down in production at the same time.
Same underlying rule, pointed in the opposite direction. Instead of a client file pulling server-only code into the browser, a server file was reaching into a client file for a value that had already stopped being a value the moment that file got its client directive.
A rule of thumb that catches most of it
The fix both times was the same: move the shared value into a third kind of file, one with no `'use client'` at the top and no server-only imports either, so both sides can import it safely. `ordersListKey.ts`, `customersListKey.ts`, and now `declineReasons.ts` all exist for exactly this reason, and all three carry a comment at the top saying so, aimed at whoever opens that file next.
There's a rough heuristic worth keeping in your head while you're writing the import, before you need the comment: if the thing you're importing isn't PascalCase, isn't a component, a server-to-client import of it is very likely a bug. A component is the one thing a server component is allowed to pull out of a client file, because rendering one doesn't require running its code anywhere but the browser. A constant, a function, a plain array, none of those are components, and none of them survive the crossing as the thing you actually wrote.
What actually catches this
Nothing about a type checker or a linter inspects which bundle an import ends up in. That's a property of the bundler's import graph, not the type system, and a build can be completely green while that graph is wrong. The only check that exercises it is loading a real page in a real browser and reading the error it throws, and when it happens, the error is specific enough to read the whole import chain back out of: it names every hop, from the file you're looking at to the one that doesn't belong there.
A page that needs a login first is slower to check this way than it has to be. Bakery Buddy keeps a few public, no-session routes on purpose, the bakery websites, the invoice-token pages, and those are a faster way to exercise the server-client boundary than signing in every single time.
See what's actually running behind every signed-in page on Bakery Buddy.
Frequently Asked Questions
What actually broke?
A client component, DeclineOrderModal, imported a plain array of decline-reason strings directly out of a server file, dispatchOrderAction.ts. That server file imports requireBakery, which imports staff-impersonation code, which imports next/headers. The single import dragged that entire chain into the browser bundle, and every signed-in page in the app returned a 500 referencing next/headers and Clerk's server-only restriction.
How can a type-safe, lint-clean change break every page?
Next.js's App Router decides at build time which code belongs in the server bundle and which belongs in the browser bundle, based on 'use client' directives and the import graph that follows from them. Neither npx tsc --noEmit nor eslint checks which bundle an import lands in. The code was valid and the types matched; the problem was entirely about where that code was going to run, which is a property the type system doesn't model.
Hadn't this happened before, in the other direction?
Yes. Earlier, a server page importing plain values (a status-filter list and a cache-key function) directly out of OrdersListView, a client component, took down /orders and /customers in production. Those exports had become client reference proxies rather than real values, so spreading the array threw 'is not iterable.' It's the same rule: a server component can render a client component, but it can't import a plain value out of one, any more than a client component can import a plain value out of a server-only one.
What's the actual fix, and how do you catch it going forward?
Move the shared value into a module with no 'use client' directive and no server-only imports, so both the server and client side can import it safely; ordersListKey.ts, customersListKey.ts, and declineReasons.ts all exist for exactly this. As a rule of thumb, importing a non-component value across the server/client line is almost always a bug. The only reliable check is loading the real page in a browser, since this class of failure lives in the bundler's import graph, not in anything a build or a typecheck inspects.
I build Bakery Buddy for my wife Lindsay's cake studio, Marin Cake Studio, and this is the bug that taught me a green build and a clean type check don't know where your code is actually going to run.
Ready to put this into practice?
Join the Waitlist