Build Configuration — Targets, Polyfills and Env Vars
IntermediateWhich browsers you compile for, what gets polyfilled, and how configuration reaches the client without leaking secrets.
Overview
Two build settings have real consequences. The compile target decides how much of your modern syntax is rewritten into older equivalents — set it too low and you ship larger, slower code to browsers that never needed it. And environment variables on the frontend are not secrets: anything the client can read is inlined into the bundle at build time and visible to anyone who opens DevTools. Frameworks make this explicit with a required prefix, and the prefix exists precisely because people leaked keys before it did.
Targets and Polyfills
Syntax gets transpiled; missing APIs need a polyfill. They are different problems with different fixes.
// browserslist drives the target
"browserslist": ["> 0.5%", "last 2 versions", "not dead"]
// Transpiling handles SYNTAX
const x = a?.b ?? c
// becomes, for an old target:
var x = (a === null || a === void 0 ? void 0 : a.b) ?? c
// Polyfills handle MISSING APIs — rewriting syntax cannot invent
// Array.prototype.at or structuredClone; those need runtime code.
import 'core-js/actual/array/at'
// A lower target means more rewriting, which means a bigger, slower
// bundle for everybody. In 2026, ES2022 is a safe baseline unless
// you have a documented legacy requirement.
"target": "ES2022"
// Check support before using a feature — caniuse.com, or the
// compatibility table at the bottom of every MDN page.Environment Variables
The prefix rule, and why it exists.
# .env.local — never committed
DATABASE_URL=postgres://... # server only
JWT_SECRET=... # server only
NEXT_PUBLIC_API_URL=https://api... # inlined into the browser bundle
// Server component / route handler — full access
process.env.DATABASE_URL
// Client component — only the prefixed ones exist
process.env.NEXT_PUBLIC_API_URL // fine
process.env.JWT_SECRET // undefined, by design
// Vite uses the same idea with a different prefix
import.meta.env.VITE_API_URL
// The rule: NEXT_PUBLIC_ / VITE_ means "I accept that this is public".
// It is substituted at BUILD time, so changing it needs a rebuild,
// and it lives in the shipped JavaScript forever.
// Never public: API secrets, database URLs, service tokens,
// anything a paid third party bills you for.Source Maps and Modes
Debuggable stack traces in production, without publishing your source.
// Minified production error, without a source map:
// TypeError: e.map is not a function at t (main.a3f8.js:1:48210)
// With one: the original file, line and variable names.
// Upload maps to your error tracker; do not serve them publicly
// (they are your readable source)
productionBrowserSourceMaps: false // Next default — not served
// Sentry/Rollbar upload the maps at build time instead.
// Dev vs prod differ in more than minification
process.env.NODE_ENV === 'production'
// React strips dev warnings, drops PropTypes checks and uses the
// fast build — which is why a bug can appear only in production.
// So test the production build locally before shipping:
npm run build && npm startKey Points to Remember
- 1Transpiling rewrites syntax; polyfills add missing runtime APIs — a low target inflates the bundle for everyone
- 2browserslist drives the target, and ES2022 is a reasonable modern baseline
- 3NEXT_PUBLIC_ and VITE_ variables are inlined at build time and are permanently public
- 4Secrets belong only in unprefixed server-side variables — a prefixed one is visible in DevTools
- 5Upload source maps to your error tracker rather than serving them, and test the production build locally
Interview Questions
Sign in to ask AriaWhat is the difference between transpiling and polyfilling?
Why does Next.js require a NEXT_PUBLIC_ prefix for client-side environment variables?
Why might a bug appear only in the production build?
Ask Aria about Build Configuration — Targets, Polyfills and Env Vars
Your personal AI tutor — ask anything about this concept
Revision Status
Personal Notes
Sign in to save personal notes for this topic.
Discussion
Sign in to join the discussion.