Next.js 16 — npx create-next-app Installed 3,400 Dependencies: Why?

You ran npx create-next-app@latest my-app, waited 47 seconds, and now you have 3,400 packages in node_modules. For a "Hello World" app. If that feels wrong, you're not crazy — it is wrong. But it's also intentional.

Next.js 16 ships with a complete build toolchain baked in: Webpack (or Turbopack), SWC for transpilation, PostCSS for CSS processing, ESLint for linting, and a dozen Babel plugins for compatibility. Each of those tools pulls in its own dependencies, and those pull in more. The result is a dependency tree that looks like a fractal.

This article walks through every major dependency group in a fresh Next.js 16 install. You'll learn what each package does, which ones you actually need, and how to strip your project down to the essentials for production. By the end, you'll understand why 3,400 packages isn't necessarily bad — but you'll also know how to audit every single one.

We'll cover the project structure, the build pipeline, the dev server, and the production optimizations. You'll never run npm install blind again.

What Actually Happens When You Run create-next-app

When you type npx create-next-app@latest my-app, you're not just scaffolding files. You're invoking a CLI that downloads the latest Next.js starter template, then runs npm install (or yarn/pnpm) to resolve the dependency tree. The template itself is tiny — about 12 files. But the dependency tree it pulls in is massive because Next.js is a meta-framework that bundles its entire toolchain.

The package.json that ships with the starter lists about 15 top-level dependencies. But each of those has its own dependencies, and those have more. The tree fans out exponentially. next itself depends on @next/env, @next/swc, postcss, cssnano, styled-jsx, and 80+ other packages. eslint-config-next alone pulls in @typescript-eslint/parser, eslint-plugin-react, eslint-plugin-react-hooks, eslint-plugin-import, and 40+ transitive deps.

The real shocker: 40% of those packages are never loaded at runtime. They exist only for build-time linting, type checking, or edge cases you'll never hit.

# Count total packages
npm ls --depth=0 --all 2>/dev/null | wc -l

# Find largest packages by disk size
du -sh node_modules/* | sort -rh | head -20

# Check for duplicate versions
npm ls react
npm ls next

# See why a package was installed
npm explain eslint-config-next

The Project Structure — What Every Folder Actually Does

After scaffolding, you get app/, public/, next.config.js, tailwind.config.ts, tsconfig.json, and postcss.config.mjs. The app/ directory is where you'll live — it's the App Router, the filesystem-based routing layer introduced in Next.js 13 and fully stabilized in 16. Every file inside app/ becomes a route, an API handler, or a layout.

The public/ folder serves static assets at the root URL. next.config.js is your escape hatch for Webpack/Turbopack config, image optimization settings, and redirects. tailwind.config.ts controls Tailwind's content scanning — and misconfiguring it is the #1 cause of 12MB CSS files (covered in Article 5).

What beginners miss: layout.js and page.js are not optional. Every route segment needs a page.js. Every shared UI needs a layout.js. If you delete layout.js from the root, your entire app returns 404. The filesystem is not a suggestion — it's the contract.

# Create a new Next.js 16 app with Turbopack
npx create-next-app@latest my-app --turbo --typescript --tailwind --eslint --app --src-dir --import-alias "@/*"

# Check what you actually installed
cd my-app
npm ls --depth=0 2>/dev/null

# Count total packages
npm ls --depth=0 --all 2>/dev/null | wc -l

The Build Pipeline — Webpack vs Turbopack vs SWC

Next.js 16 ships with two build engines: Webpack (default) and Turbopack (opt-in via --turbo). Webpack has been the backbone of Next.js since v6, but it's old — first released in 2012. It processes JavaScript through loaders and plugins, and it's incredibly flexible. That flexibility comes at a cost: 400+ packages just for the Webpack ecosystem.

Turbopack is the Rust-based successor. It's 10x faster at cold starts and 4x faster at HMR (hot module replacement). But it's not a drop-in replacement — some Webpack plugins don't work with Turbopack yet. If you use @next/mdx, custom Webpack loaders, or next-compose-plugins, you're stuck on Webpack.

SWC (Speedy Web Compiler) is the Rust-based transpiler that replaced Babel in Next.js 13+. It's 20x faster at transforming JSX and TypeScript. But SWC doesn't support all Babel plugins — if you rely on babel-plugin-macros or custom Babel transforms, you'll need to opt out of SWC entirely.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // Enable Turbopack (replaces Webpack)
  // No config needed — just use --turbo flag
  
  // If you need custom Webpack (opts out of Turbopack):
  webpack: (config, { isServer }) => {
    config.resolve.fallback = {
      ...config.resolve.fallback,
      fs: false,
      net: false,
      tls: false,
    }
    return config
  },
}

export default nextConfig

The 12 Files You Actually Get — And What Each One Does

After scaffolding, you get: app/layout.tsx, app/page.tsx, app/globals.css, app/favicon.ico, next.config.js (or .ts), tailwind.config.ts, postcss.config.mjs, tsconfig.json, package.json, next-env.d.ts, .eslintrc.json, and README.md. That's it. Twelve files. But each one has a specific job that beginners often misunderstand.

app/layout.tsx is the root layout — it wraps every page in your app. It's required. Without it, Next.js throws a 500 error on every route. The <html> and <body> tags go here. app/page.tsx is your index route — it maps to /. Add app/about/page.tsx and you get /about. No config, no router setup, no BrowserRouter wrapper.

globals.css is imported in the root layout and applies globally. tailwind.config.ts tells Tailwind which files to scan for class names. If you add files outside the configured content paths, Tailwind won't generate those classes — and you'll wonder why bg-red-500 doesn't work.

// This is the root layout — required, wraps every page
// Only the root layout should contain <html> and <body>

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body className="antialiased">
        {children}
      </body>
    </html>
  )
}

The package.json — What Each Dependency Actually Does

Your scaffolded package.json lists next, react, react-dom, and a few dev dependencies. But next alone pulls in 80+ packages. Let's break down the major groups.

next itself is a meta-package that depends on: @next/env (environment variable loading), @next/swc-* (Rust-based transpiler binaries for each OS), postcss (CSS processing), cssnano (CSS minification), styled-jsx (built-in CSS-in-JS), and sharp (image optimization, macOS only). Each of those has its own tree.

react and react-dom are clean — they pull in almost nothing. But @types/react and @types/react-dom (if you use TypeScript) add 12 more packages. tailwindcss pulls in postcss, postcss-import, postcss-nesting, autoprefixer, and cssnano — many of which are already installed by Next.js. This duplication is why npm dedupe can save 200+ packages.

{
  "name": "my-app",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev --turbo",
    "build": "next build",
    "start": "next start",
    "lint": "next lint"
  },
  "dependencies": {
    "next": "^16.0.0",
    "react": "^19.0.0",
    "react-dom": "^19.0.0"
  },
  "devDependencies": {
    "typescript": "^5.5.0",
    "@types/node": "^20.0.0",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "tailwindcss": "^4.0.0",
    "eslint": "^9.0.0"
  }
}

The Hidden Cost of TypeScript Types

If you scaffold with --typescript, you get @types/react, @types/react-dom, @types/node, and typescript itself. These are dev dependencies — they don't ship to production. But they still take up disk space and install time. @types/react alone is 2MB of type definitions. typescript is 45MB.

The real cost is in CI. Every CI pipeline installs dev dependencies by default. If you're not using npm ci --production or NODE_ENV=production, you're installing TypeScript and all type definitions in your production build step. That's 50MB+ of unnecessary downloads.

Pro tip: Use next build which automatically strips TypeScript from the production bundle. But the type-checking step still runs during build — and it requires typescript to be installed. If you want to skip type-checking in CI, set ignoreBuildErrors: true in next.config.js and run tsc --noEmit as a separate CI step.

# Multi-stage build — don't copy devDependencies to production
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --only=production

FROM node:20-alpine AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/public ./public
COPY --from=builder /app/package.json ./package.json
COPY --from=deps /app/node_modules ./node_modules
EXPOSE 3000
CMD ["npm", "run", "start"]

The Lockfile — Your Only Source of Truth

package-lock.json (or yarn.lock / pnpm-lock.yaml) is the most important file in your project that you'll never read. It pins every single dependency to an exact version, including transitive dependencies. Without it, two developers running npm install on the same package.json could get different trees — and one of them will hit a bug that the other can't reproduce.

Next.js 16's lockfile is typically 8,000-12,000 lines. That's not a bug — it's npm being precise. Every entry includes the resolved URL, integrity hash, and dependency tree. If you delete package-lock.json and reinstall, you'll get different minor versions of everything, and something will break.

Commit your lockfile. Never add it to .gitignore. If you use npm ci in CI (which you should), it reads the lockfile and installs exact versions. npm install ignores the lockfile and resolves fresh — which is why CI builds break on Monday after a package published a breaking change on Sunday.

# Good (CI): respects lockfile, fails if lockfile is out of sync
npm ci

# Bad (CI): ignores lockfile, resolves fresh — can break builds
npm install

# Fastest CI install with caching
npm ci --prefer-offline --no-audit --no-fund

The Dev Server — What Happens When You Run next dev

When you run next dev, Next.js starts a development server on port 3000. But behind the scenes, it's doing a lot more. It compiles your code on-the-fly using SWC (or Babel if configured), starts a file watcher, and sets up Hot Module Replacement (HMR). HMR means when you edit a file, only that module is replaced — not the whole page.

With Turbopack (next dev --turbo), HMR is nearly instant. Changes to React components reflect in under 50ms. Without Turbopack, Webpack's HMR takes 200-500ms for the same change. The difference is noticeable when you're iterating on UI — 50ms feels instant, 500ms feels like a delay.

But here's the catch: Turbopack doesn't support all Webpack features. If your next.config.js has a custom webpack function, Turbopack is disabled. If you use next-compose-plugins, Turbopack is disabled. If you use @next/mdx with a custom loader, Turbopack is disabled. Read the Turbopack compatibility table before migrating.

# Start dev server with Turbopack (fast HMR)
npm run dev -- --turbo

# Start dev server with Webpack (compatible with custom loaders)
npm run dev

# Check if Turbopack is active
# Look for "✓ Ready in 1.2s" (Turbopack) vs "ready started server on 0.0.0.0:3000" (Webpack)

The Production Build — What next build Actually Produces

When you run next build, Next.js compiles your app into a .next folder. This folder contains: server/ (server-side rendered pages and API routes), static/ (client-side JavaScript chunks), chunks/ (shared code), standalone/ (if output: 'standalone' is configured), and build-manifest.json (maps routes to chunks).

The build process: 1) SWC transpiles all TypeScript/JSX to JavaScript, 2) Webpack/Turbopack bundles everything into chunks, 3) Next.js generates static pages (if using generateStaticParams), 4) The output is optimized with tree-shaking and minification.

What beginners don't realize: next build also runs type-checking. If you have TypeScript errors, the build fails. This is intentional — you shouldn't ship code with type errors. But if you're migrating a large codebase, you can set typescript.ignoreBuildErrors: true in next.config.js to skip type-checking during build and run tsc --noEmit separately.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // Skip type-checking during build (run tsc separately)
  typescript: {
    ignoreBuildErrors: true,
  },
  
  // Skip ESLint during build (run lint separately)
  eslint: {
    ignoreDuringBuilds: true,
  },
  
  // Standalone output for Docker
  output: 'standalone',
}

export default nextConfig

Environment Variables — The @next/env Package

Next.js includes @next/env to load .env.local, .env.development, .env.production, and .env files. The priority order is: .env.local > .env.development/.env.production > .env. Variables are loaded at build time and inlined into the client bundle if prefixed with NEXT_PUBLIC_.

This is a common source of confusion: variables without NEXT_PUBLIC_ prefix are only available on the server. If you try to access process.env.API_KEY in a client component, it'll be undefined. The NEXT_PUBLIC_ prefix tells the bundler to inline the value at build time — which means it's baked into the JavaScript bundle. Anyone who reads your source code can see it.

Never put secrets in NEXT_PUBLIC_ variables. They're visible in the browser's DevTools. Use server-only environment variables for API keys, database URLs, and auth secrets. Access them only in Server Components, API routes, or Server Actions.

// Server-side: access secret env vars safely
export async function GET() {
  const apiKey = process.env.API_KEY // Only available on server
  const dbUrl = process.env.DATABASE_URL // Only available on server
  
  // This would be undefined in a client component:
  // console.log(process.env.API_KEY) // undefined in browser
  
  return Response.json({ status: 'ok' })
}

The Public Folder — Static Assets and the Root URL

The public/ folder maps to the root URL of your site. A file at public/logo.png is served at /logo.png. A file at public/images/hero.jpg is served at /images/hero.jpg. This is the only way to serve static files in Next.js — you can't put images in app/ and expect them to be served.

But there's a trap: files in public/ are copied as-is during build. They're not optimized, not hashed, and not compressed. If you put a 5MB hero image in public/, it ships as 5MB. Use next/image for optimization instead — it generates multiple sizes, serves WebP/AVIF, and lazy-loads by default.

Another trap: public/ is served at the root, not at /public/. A file at public/images/logo.png is at /images/logo.png, not /public/images/logo.png. Beginners often link to /public/images/logo.png and get a 404.

import Image from 'next/image'

export default function Home() {
  return (
    <div>
      {/* public/hero.jpg → /hero.jpg */}
      {/* next/image optimizes this automatically */}
      <Image
        src="/hero.jpg"
        alt="Hero image"
        width={1200}
        height={600}
        priority // Load above the fold
        quality={85}
      />
    </div>
  )
}

The Config Files — next.config.js, tailwind.config.ts, tsconfig.json

next.config.js (or .ts in Next.js 16) is your escape hatch. It's where you configure image domains, redirects, headers, Webpack, and experimental features. The default config is empty — Next.js works without any configuration. But you'll quickly need to add images.remotePatterns for external images, redirects for URL changes, and headers for security policies.

tailwind.config.ts controls which files Tailwind scans for class names. The default content array includes ./app/*/.{js,ts,jsx,tsx} and ./components/*/.{js,ts,jsx,tsx}. If you add files outside these paths (e.g., in lib/ or utils/), Tailwind won't generate those classes. This is the #1 cause of "my Tailwind class doesn't work" — the class is correct, but Tailwind never scanned the file.

tsconfig.json is generated by Next.js and extends next.config.ts's types. The key settings: moduleResolution: "bundler" (required for Next.js 16), jsx: "preserve" (SWC handles JSX, not TypeScript), and paths with @/ mapping to ./src/ or ./*. Never manually edit the compilerOptions section that Next.js manages — it gets overwritten on every build.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  // Image optimization — allow external images
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'images.unsplash.com',
      },
      {
        protocol: 'https',
        hostname: 'cdn.example.com',
      },
    ],
  },
  
  // Redirects (permanent or temporary)
  async redirects() {
    return [
      {
        source: '/old-page',
        destination: '/new-page',
        permanent: true,
      },
    ]
  },
  
  // Security headers
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          { key: 'X-Frame-Options', value: 'DENY' },
          { key: 'X-Content-Type-Options', value: 'nosniff' },
          { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
        ],
      },
    ]
  },
}

export default nextConfig

The First Page — From Scaffold to Production

Your first page is app/page.tsx. It's a Server Component by default — meaning it runs on the server, sends only HTML to the client, and never ships JavaScript. This is the most important concept in Next.js 16: every component is a Server Component unless you add 'use client'.

Server Components can be async — you can await a database query or a fetch() call directly in the component body. No useEffect, no useState, no loading states. The component renders on the server, the HTML is sent to the client, and the JavaScript for that component is zero bytes.

But Server Components can't use hooks, event handlers, or browser APIs. If you need useState, useEffect, onClick, or window access, you need a Client Component. The boundary is explicit: add 'use client' at the top of the file. Everything below that boundary runs on the client.

// This is a Server Component (no 'use client' directive)
// It runs on the server, sends HTML to the client
// Zero JavaScript shipped for this component

export default async function Home() {
  // Direct fetch — no useEffect, no loading state
  const data = await fetch('https://api.example.com/posts', {
    next: { revalidate: 60 } // ISR: revalidate every 60 seconds
  })
  const posts = await data.json()

  return (
    <main>
      <h1>My Blog</h1>
      {posts.map((post: any) => (
        <article key={post.id}>
          <h2>{post.title}</h2>
          <p>{post.body}</p>
        </article>
      ))}
    </main>
  )
}

The node_modules Rabbit Hole — What You Can Safely Delete

Not everything in node_modules is needed. Dev dependencies (devDependencies in package.json) are only used during development and build. They're not included in the production bundle, but they're still installed on disk. You can safely delete: @types/ (type definitions), eslint and all eslint-plugin- packages, typescript itself, prettier, husky, and lint-staged.

But there's a catch: some packages are both dev and production dependencies depending on how you use them. tailwindcss is a dev dependency — it's only used at build time. But postcss is a dependency of tailwindcss, and postcss is also a dependency of next. So even if you remove tailwindcss, postcss stays because next needs it.

The best tool for auditing this is npm ls --depth=0 --production. This shows only the packages that will be installed with --production flag. Compare it to npm ls --depth=0 (all packages) to see what's dev-only. If you see a package in the full list but not in the production list, it's safe to remove from dependencies and move to devDependencies.

# See what ships to production
npm ls --depth=0 --production 2>/dev/null

# See all installed packages (including dev)
npm ls --depth=0 2>/dev/null

# Remove dev dependencies from node_modules
npm prune --production

# Check disk usage of remaining packages
du -sh node_modules/* | sort -rh | head -10

The First Deploy — What You Need to Know Before Shipping

Before you deploy, there are three things you must configure: environment variables, image optimization, and the build command. Environment variables for production go in .env.production (or your hosting platform's dashboard). Never commit .env.local — it's in .gitignore by default, but double-check.

Image optimization requires configuring remotePatterns in next.config.js if you're loading images from external domains. Without this, next/image will refuse to serve external images in production. The error message is clear: "The requested resource isn't a valid image." But beginners often miss it because it works in development.

The build command for production is next build && next start. On Vercel, this happens automatically. On other platforms (AWS, Railway, Fly.io), you need to configure the build command and start command explicitly. The output: 'standalone' option creates a minimal .next/standalone folder with only the files needed to run the app — perfect for Docker.

import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  output: 'standalone', // Minimal production output
  
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
      },
    ],
  },
  
  // Skip type-checking during build (run tsc separately)
  typescript: {
    ignoreBuildErrors: true,
  },
}

export default nextConfig

The Scripts — dev, build, start, and lint

The scaffolded package.json includes four scripts: dev, build, start, and lint. dev starts the development server with HMR. build creates the production bundle. start serves the production bundle. lint runs ESLint across your codebase.

But there's a hidden script: next telemetry. Next.js collects anonymous usage data by default. Run npx next telemetry disable to opt out. It's not malicious — Vercel uses it to prioritize features — but you should know it's on by default.

Another hidden command: next info. This prints your system information (OS, Node version, npm version, Next.js version) — useful for debugging and bug reports. Run it before filing an issue on GitHub.

# Get system info for bug reports
npx next info

# Disable telemetry
npx next telemetry disable

# Check telemetry status
npx next telemetry status

# Run lint
npm run lint

The First Edit — Adding a Second Page

To add a second page, create app/about/page.tsx. That's it. The route /about now exists. No router config, no route registration, no BrowserRouter wrapper. The filesystem IS the router. This is the fundamental mental shift from React Router to Next.js.

But there's a subtlety: nested routes need nested folders. app/blog/[slug]/page.tsx creates /blog/:slug. The [slug] is a dynamic segment — you access it via params in the component props. For catch-all routes, use [...slug] (matches one or more segments) or [[...slug]] (matches zero or more).

Group routes use (groupName) folders — they don't affect the URL path. app/(marketing)/about/page.tsx still maps to /about. This is useful for organizing routes without changing URLs. Parallel routes use @slotName folders for rendering multiple pages in the same layout (e.g., a dashboard with independent feed and sidebar).

// Dynamic route: /blog/hello-world → params.slug = "hello-world"

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  
  const post = await getPost(slug)
  
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  )
}

The First Bug — Why Your Page Returns 404

The most common beginner bug: you create app/blog/page.tsx but the route returns 404. The cause is almost always one of: missing layout.js in a parent segment, a typo in the folder name, or a file named page.tsx instead of page.tsx (yes, the extension matters).

Next.js requires every route segment to have a page.js (or page.tsx) file. If you create app/blog/ but only put a layout.tsx there without a page.tsx, the route returns 404. The layout wraps the page — it doesn't replace it.

Another common issue: case sensitivity. app/Blog/page.tsx and app/blog/page.tsx are different routes on Linux (case-sensitive filesystem) but the same on macOS (case-insensitive by default). This causes "works on my machine" bugs. Always use lowercase for folder names.

# Find any uppercase characters in app/ folder names
# Add this to your CI pipeline
find app -type d | grep -E '[A-Z]' && echo "ERROR: Uppercase folder names found in app/" && exit 1

The First Optimization — Reducing Your Dependency Count

You can reduce your dependency count from 3,400 to ~800 without losing any functionality. Here's how: 1) Use --turbo flag (removes Webpack and its 400 plugins), 2) Remove eslint-config-next and use a minimal ESLint config, 3) Remove @next/bundle-analyzer if you're not using it, 4) Use npm dedupe to collapse duplicate versions, 5) Switch to pnpm which uses a content-addressable store and hard links.

But don't optimize prematurely. 3,400 packages on disk is not a performance problem — it's a disk space and CI time problem. The production bundle is tree-shaken. Only the code you actually import ends up in the browser. The 3,400 packages in node_modules are just sitting there, taking up space, not affecting your users.

The real cost is CI time, disk space on your build server, and the attack surface for supply-chain vulnerabilities. Every package in node_modules is a potential vector for npm audit warnings. With 3,400 packages, you'll have at least 5-10 moderate-severity advisories on day one.

# Audit all dependencies
npm audit

# Audit only production dependencies
npm audit --production

# Fix vulnerabilities automatically (may break things)
npm audit fix

# See why a specific package is installed
npm explain <package-name>

The Hidden Files — next-env.d.ts, .next, and Gitignore

next-env.d.ts is a TypeScript declaration file that Next.js generates and manages. It references Next.js's type definitions. Never edit it — Next.js overwrites it on every build. If you delete it, TypeScript will complain about missing types for next/image, next/link, and other Next.js APIs.

.next/ is the build output directory. It's generated by next build and next dev. It contains compiled code, cached SWC transforms, and static files. Never commit it. The default .gitignore from create-next-app includes .next/, node_modules/, and .env.local.

But there's a missing entry: .env.local files. The default .gitignore only ignores .env.local, not .env.development.local or .env.production.local. Add .local to catch all local env files.

# dependencies
/node_modules
/.pnp
.pnp.js

# testing
/coverage

# next.js
/.next/
/out/

# production
/build

# misc
.DS_Store
*.pem

# debug
npm-debug.log*
yarn-debug.log*
yarn-error.log*

# local env files
.env*.local  # ← Add this line! Default only ignores .env.local

# vercel
.vercel

# typescript
*.tsbuildinfo
next-env.d.ts

The First Week — What to Learn and What to Ignore

In your first week with Next.js, focus on: the filesystem router (app/ directory), Server Components vs Client Components, data fetching in Server Components, and the build pipeline. Ignore: middleware (you don't need it yet), route handlers (API routes), parallel routes, intercepting routes, and Partial Prerendering (PPR).

The most common mistake beginners make is treating Next.js like React with a router. It's not. Next.js is a framework that makes assumptions about how you build. The filesystem is the router. Server Components are the default. Data fetching happens in the component, not in useEffect. If you fight these assumptions, you'll have a bad time.

Embrace the conventions: put pages in app/, put shared UI in components/, put utilities in lib/, put types in types/. This structure scales from 1 page to 1,000 pages without refactoring.

import type { Metadata } from 'next'
import './globals.css'

export const metadata: Metadata = {
  title: 'My App',
  description: 'Built with Next.js 16',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  )
}

The First Production Build — What to Expect

Your first next build will take 30-60 seconds. It compiles all your pages, generates static pages, optimizes images, and produces the output in .next/. The build output shows you: which routes are static vs dynamic, how large each page's JavaScript is, and whether any pages failed to compile.

Static routes (no dynamic data) are pre-rendered at build time. Dynamic routes (using cookies(), headers(), searchParams, or fetch() with cache: 'no-store') are rendered on each request. The build output marks each route with a symbol: ● for static, λ for dynamic, ○ for ISR (Incremental Static Regeneration).

If you see λ on a page you expected to be static, check if it uses headers(), cookies(), searchParams, or fetch() with cache: 'no-store'. Any of these force dynamic rendering. To make a page static, remove those dependencies or use generateStaticParams to pre-render specific paths.

// Pre-render all blog posts at build time
export async function generateStaticParams() {
  const posts = await fetch('https://api.example.com/posts')
    .then(res => res.json())
  
  return posts.map((post: { slug: string }) => ({
    slug: post.slug,
  }))
}

export default async function BlogPost({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  const post = await getPost(slug)
  
  return <article>{post.title}</article>
}