Static export option in NextJS - Deep Dive

Overview - Static export option

What is it?

The static export option in Next.js lets you create a website where all pages are pre-built into simple HTML files. This means the site can be served without a server running code for each visitor. It is useful for sites that don't need to change content on the fly and want fast loading times.

Why it matters

Without static export, every page request might need server processing, which can slow down the site and increase hosting costs. Static export solves this by generating all pages ahead of time, making the site faster and easier to host anywhere, even on simple file servers or CDNs.

Where it fits

Before learning static export, you should understand basic Next.js pages and routing. After mastering static export, you can explore dynamic rendering methods like server-side rendering and incremental static regeneration for more complex needs.

Mental Model

Core Idea

Static export turns your Next.js app into a set of ready-made HTML files that can be served instantly without server processing.

Think of it like...

It's like baking all your cookies in advance and packing them in boxes, so when someone wants a cookie, you just hand them a box instead of baking one fresh each time.

Next.js App
  │
  ├─ Pages with React Components
  │
  ├─ Static Export Process
  │     └─ Pre-builds HTML files for each page
  │
  └─ Output: Static HTML + Assets
        └─ Ready to serve from any static host

Build-Up - 7 Steps

1

Foundation

Understanding Static Websites

Concept: Learn what static websites are and how they differ from dynamic ones.

A static website consists of fixed HTML files that do not change on the server. When you visit a static site, the server simply sends these files to your browser. Dynamic websites generate pages on the fly using server code, which can be slower and require more resources.

Result

You understand that static sites are fast and simple because they serve pre-made files.

Knowing the difference between static and dynamic sites helps you appreciate why static export can improve performance and hosting simplicity.

2

Foundation

Next.js Pages and Routing Basics

Concept: Learn how Next.js creates pages and handles navigation.

In Next.js, each file in the 'pages' folder becomes a route on your website. For example, 'pages/about.js' becomes '/about'. Next.js uses React components to build these pages, which can be rendered in different ways.

Result

You can create simple pages and navigate between them in a Next.js app.

Understanding pages and routing is essential before deciding how to render or export them.

3

Intermediate

How Static Export Works in Next.js

🤔Before reading on: do you think static export runs your React code on the server for each visitor or just once during build? Commit to your answer.

Concept: Static export pre-renders all pages at build time into HTML files.

When you run 'next export', Next.js builds your app and generates static HTML for every page. This happens once during build, not on each user visit. The output is a folder with HTML files and assets that can be served by any static hosting service.

Result

You get a folder with ready-to-serve HTML files for all pages.

Understanding that static export happens once at build time explains why sites load faster and need no server code.

4

Intermediate

Configuring Static Export in next.config.js

🤔Before reading on: do you think you need to change your code to enable static export, or just configure Next.js? Commit to your answer.

Concept: Static export is enabled by setting 'output' to 'export' in Next.js config.

In your 'next.config.js' file, add 'output: "export"'. This tells Next.js to prepare your app for static export. You then run 'next build' and 'next export' commands to generate the static files. No code changes are strictly required if your pages are compatible.

Result

Next.js builds and exports your app as static files ready for deployment.

Knowing that static export is mostly a configuration step helps you quickly switch between rendering modes.

5

Intermediate

Limitations of Static Export

🤔Before reading on: do you think static export supports server-side code like API routes or getServerSideProps? Commit to your answer.

Concept: Static export does not support server-side rendering or API routes.

Static export only works with pages that can be fully rendered at build time. Features like 'getServerSideProps' or API routes require a server and are not compatible. You must use 'getStaticProps' or static content for your pages.

Result

You understand which Next.js features work with static export and which do not.

Knowing these limits prevents deployment errors and helps you choose the right rendering method.

6

Advanced

Using getStaticProps for Static Export

🤔Before reading on: do you think getStaticProps runs on the client or during build? Commit to your answer.

Concept: 'getStaticProps' fetches data at build time for static pages.

When you export statically, Next.js runs 'getStaticProps' during build to fetch any data your page needs. This data is then baked into the HTML. This allows dynamic content to appear on static pages without server code at runtime.

Result

Your static pages can include dynamic data fetched once at build time.

Understanding 'getStaticProps' is key to making static export useful for data-driven sites.

7

Expert

Static Export Internals and Edge Cases

🤔Before reading on: do you think static export can handle dynamic routes without extra setup? Commit to your answer.

Concept: Static export requires explicit paths for dynamic routes and careful asset handling.

For dynamic routes (like '/posts/[id]'), you must provide all possible paths in 'getStaticPaths' so Next.js can generate HTML for each. Also, static export copies assets but does not handle server-only features. Misconfigurations can cause missing pages or broken links.

Result

You can statically export complex apps with dynamic routes by providing all paths and avoiding server-only code.

Knowing these internals helps avoid common pitfalls and enables advanced static export setups.

Under the Hood

Static export works by running the Next.js build process to render every page component into HTML strings using React's server rendering. It collects all pages, including dynamic routes specified by the developer, and writes static HTML files to an output folder. No server code remains; the site is purely static files.

Why designed this way?

Next.js was designed to support multiple rendering modes. Static export was added to allow developers to deploy sites easily on static hosts without servers. This design trades runtime flexibility for speed and simplicity, fitting use cases where content changes infrequently.

┌─────────────────────┐
│ Next.js App Source  │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Build Process       │
│ - Render pages to   │
│   HTML strings      │
│ - Run getStaticProps│
│ - Generate paths    │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Output Folder       │
│ - Static HTML files │
│ - Assets (CSS, JS)  │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│ Static Hosting      │
│ - Serve files       │
│ - No server code    │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does static export support API routes in Next.js? Commit to yes or no.

Common Belief: Static export can handle API routes because Next.js supports them.

Reality: Static export does not support API routes since it produces only static files without server code.

Why it matters: Trying to use API routes with static export leads to broken functionality and deployment failures.

Quick: Can you use getServerSideProps with static export? Commit to yes or no.

Common Belief: You can use getServerSideProps with static export because it fetches data for pages.

Reality: getServerSideProps requires a server at runtime and is incompatible with static export.

Why it matters: Using getServerSideProps causes build errors or missing pages when exporting statically.

Quick: Does static export automatically handle all dynamic routes without extra setup? Commit to yes or no.

Common Belief: Static export automatically generates all dynamic routes without extra configuration.

Reality: You must explicitly specify all dynamic routes in getStaticPaths for static export to generate them.

Why it matters: Missing paths cause pages to be absent in the exported site, leading to broken links.

Quick: Is static export slower than server-side rendering for each page request? Commit to yes or no.

Common Belief: Static export is slower because it pre-builds pages and serves static files.

Reality: Static export is faster at runtime because pages are pre-built and served instantly without server processing.

Why it matters: Misunderstanding this can lead to choosing slower rendering methods unnecessarily.

Expert Zone

1

Static export requires careful handling of dynamic routes; forgetting to list all paths in getStaticPaths breaks the site silently.

2

Assets like images and fonts must be referenced correctly to be included in the export; relative paths can cause missing files.

3

Static export disables some Next.js features like API routes and middleware, so hybrid apps need careful architecture.

When NOT to use

Static export is not suitable for apps needing real-time data, user authentication, or server-side logic. Use server-side rendering (getServerSideProps) or incremental static regeneration instead.

Production Patterns

In production, static export is used for marketing sites, blogs, and documentation where content changes rarely. It is combined with CDNs for global fast delivery and often paired with client-side JavaScript for interactivity.

Connections

Content Delivery Networks (CDNs)

Static export outputs files that CDNs serve efficiently worldwide.

Understanding static export helps you leverage CDNs to deliver content fast and reliably.

Jamstack Architecture

Static export is a core technique in Jamstack, which builds fast, secure sites from static files and APIs.

Knowing static export deepens your grasp of Jamstack principles and modern web architecture.

Manufacturing Assembly Lines

Static export pre-builds pages like an assembly line pre-builds products before shipping.

This connection shows how pre-building work improves efficiency and consistency in both web and manufacturing.

Common Pitfalls

#1 Trying to use getServerSideProps with static export.

Wrong approach:

export async function getServerSideProps() {
return { props: { time: Date.now() } };
}

Correct approach:

export async function getStaticProps() {
return { props: { time: Date.now() } };
}

Root cause:

Misunderstanding that getServerSideProps requires a server at runtime, which static export does not provide.

#2 Not specifying all dynamic routes in getStaticPaths.

Wrong approach:

export async function getStaticPaths() {
return { paths: [], fallback: false };
}

Correct approach:

export async function getStaticPaths() {
return { paths: [
{ params: { id: '1' } },
{ params: { id: '2' } }
], fallback: false };
}

Root cause:

Assuming Next.js guesses dynamic routes automatically during static export.

#3 Referencing assets with incorrect paths causing missing files after export.

Wrong approach:

// when images are not in public folder

Correct approach:

// move images to public folder and use /images/logo.png

Root cause:

Not understanding how Next.js handles static assets and public folder during export.

Key Takeaways

Static export in Next.js pre-builds your entire site into static HTML files served without a server.

It improves performance and hosting simplicity but does not support server-side features like API routes or getServerSideProps.

You must configure dynamic routes explicitly and use getStaticProps to fetch data at build time.

Static export fits well for sites with mostly fixed content, enabling fast delivery via static hosts and CDNs.

Understanding its limits and internals helps you choose the right rendering method for your app's needs.