What Happens When You Run npm run build in a Next.js Project?

If you've built a site with Next.js, you've probably typed npm run build without fully knowing what goes on under the hood. In this post, let's demystify what happens when you run this command in a Next.js app — especially with the App Router introduced in Next.js 13+.

📦 What Does npm run build Do?

This command runs the production build script defined in your package.json:

"scripts": {
  "build": "next build"
}

Under the hood, next build compiles your Next.js app into an optimized production version, ready to be deployed. This process includes transpilation, bundling, minification, static generation, and more.

🚀 Step-by-Step: What Happens Internally

1. TypeScript and ESLint Checking

If you use TypeScript or have linting enabled, Next.js will validate your code first. This ensures you're not shipping broken or untyped logic to production.

✓ Linting and TypeScript passed

2. Transpilation with Babel

Your JavaScript (or TypeScript) is compiled using Babel. This converts your modern React code (like JSX or ES6+) into browser-compatible JavaScript.

3. Tree Shaking and Dead Code Elimination

Next.js removes unused imports, functions, and components. This reduces your bundle size and improves performance. Dead code won't be included in the final output.

4. Static Generation (SSG)

For pages using generateStaticParams or getStaticProps, Next.js pre-renders them to HTML during the build. This means they load instantly for the user.

Generating static pages...
✓ /about
✓ /blog/[slug]
✓ /

5. Server-Side Rendering (SSR)

Pages that use getServerSideProps or are marked dynamic (like dashboards) won't be pre-rendered. They're bundled into server functions that run on-demand.

With the App Router, this is handled using server components and special rendering logic.

6. Image Optimization

Next.js scans your usage of the component and prepares optimized image loaders, like for AVIF/WebP formats. This improves Core Web Vitals.

7. Route Generation (App Router)

With the App Router, Next.js scans your app/ directory and generates routes based on folders like:

app/
├─ page.tsx       → /
├─ about/page.tsx → /about
├─ blog/[slug]/page.tsx → /blog/[slug]

Layouts and templates are also optimized at build time to reduce client-side rendering overhead.

8. Middleware and Edge Function Compilation

If you're using middleware.ts or edge functions, Next.js compiles them separately for deployment to platforms like Vercel or Netlify.

9. Build Output Summary

After all the above, you'll see a summary like:

Pages:
+ /              (Static)
+ /about         (Static)
+ /dashboard     (Server)
+ /api/hello     (API Route)

First Load JS shared by all:
  - _app.js
  - _document.js
  - commons.js

📁 Output Directory

After the build, you'll see a .next/ folder with:

• static/ – compiled JS, CSS, assets
• server/ – server-side pages and functions
• cache/ – build cache to speed up future builds

🏁 Final Thoughts

Running npm run build is not just about minifying your code. It's a full production optimization pipeline that prepares your app for performance, SEO, and scalability.

If you're deploying to platforms like Vercel or Netlify, this build output is what gets shipped.

🔥 Ready to Try?

Next time you run npm run build, watch the terminal closely — you’ll see your app transform into something production-grade, one file at a time.

Have questions about build optimization or how to debug build errors? Leave a comment below or hit me up on X (@slatebytes)!

Powered by Froala Editor