Server memory
Server memory
One app process should fit in about 120 MB of private memory, so that ten of them run on a 4 GB server and leave room for a build. Most of what a process holds is not live data: it is the code of every package it imported, kept whole. The rules here keep that small.
Where the memory goes
Measured 2026-11-14 on the production build (Bun 1.4, RssAnon from
/proc/<pid>/status, after 360 mixed requests). Only about 60 MB is the
JavaScript heap; the rest is module code.
| Change | At boot | After traffic |
|---|---|---|
| Before | 82 MB | 152 MB |
| Email packages narrowed and loaded on first send, S3 SDK loaded on first use | 55 MB | 129 MB |
| UI libraries bundled into the server build | 55 MB | 116 MB |
Sentry on @sentry/core, loaded only with a DSN | 56 MB | 105 MB (108 MB with a DSN) |
What a package costs to import on its own, whole:
| Package | RAM |
|---|---|
@react-email/components (barrel) | 37 MB |
the ten @react-email/* component packages the templates use | 2 MB |
@react-email/render | 12 MB |
better-auth | 27 MB |
@sentry/tanstackstart-react, @sentry/node, @sentry/bun | 24 to 30 MB |
@sentry/core | 7 MB |
lucide-react | 18 MB |
@aws-sdk/client-s3 | 14 MB |
@aws-sdk/s3-presigned-post | 14 MB |
motion/react | 14 MB |
nodemailer | 10 MB |
radix-ui | 9 MB |
date-fns | 9 MB |
bun --smol changes nothing here (151 vs 152 MB): the heap is not the
problem.
Why imports cost so much
The process runs two module graphs.
- The Vite server build (
dist/server): routes, pages, server functions. Packages inssr.noExternal(vite.config.ts) are bundled and tree-shaken; every other package is a runtime import, loaded whole fromnode_modules. server/start.tsand what it imports (@/features/jobs/workers,@/server/auth, the reconcilers): plain TypeScript run by Bun, never bundled, never tree-shaken. Every top-level import in that chain is loaded whole at boot, in every process.
Both graphs share one copy of a package only while it stays external.
Rules
-
No barrel package in code that
server/start.tsreaches. Import the narrow package:@react-email/button, not@react-email/components(which also pulls in Tailwind and a syntax highlighter). -
A heavy SDK that most requests never use is a dynamic import at the point of use.
sendEmailimports@react-email/renderandresendwhen it sends;getS3Client()imports the AWS SDK when called, and is async for that reason.nodemailerloads only on the SMTP path. -
A UI library used only by pages goes in
ssr.noExternal, so the server build keeps only the exports the pages use. -
A package that the
server/start.tschain also imports stays out ofssr.noExternal. Bundled there and imported raw here, it would be in memory twice. That covers React, the TanStack packages,better-auth,drizzle-orm,stripeandzod. -
Sentry on the server is
@sentry/core, loaded only with a DSN.src/server/sentry.server.tsbuilds a client from it (errors only, no tracing).@sentry/node,@sentry/bunand@sentry/tanstackstart-reactall cost 24 MB or more, and the last was loaded in every process, DSN or not, through a top-level import insrc/start.ts. The@sentry/*packages are inssr.noExternalso the pages'ErrorBoundaryimport does not load the browser SDK whole.
Measuring
make check-boot fails when the server's private memory, read as soon as it
accepts connections, is over its budget (BOOT_MEMORY_BUDGET_MB in
tests/boot-smoke.ts: 115 MB against about 91 MB measured), so a new
top-level import of something heavy shows up in CI. To see what one package
costs:
// mem.ts, run with: NODE_ENV=production bun mem.ts <package>
import fs from 'node:fs';
const anon = () =>
Number(/RssAnon:\s+(\d+)/.exec(fs.readFileSync('/proc/self/status', 'utf8'))?.[1]) / 1024;
const before = anon();
await import(process.argv[2]);
console.log(`+${(anon() - before).toFixed(1)} MB`);
Not done
better-auth(27 MB) is needed by every authenticated request.