Understanding static HTML export in Next.js

Next.js is renowned in the React world for being a great tool for dynamic applications because of its range of features and rendering methods, allowing it to handle pretty much anything you throw at it.

But, one of the lesser-known and underutilized features (that you have to dig into the “Advanced Features” section of the documentation to find out about) is static HTML export.

Static HTML is exactly what it sounds like: a series of HTML files that are, well, static. They don’t require servers or other special products/services to run or be usable. The only job the server is required to do is host the files for others to consume, nothing more.

Next.js makes exporting static HTML from an application easy, ridiculously easy in fact. In this article, we’ll take a look into why would we want to export static HTML from a Next.js application and how we can do it. Here, we’ll cover:

• Why use static HTML?
• SEO benefits
• Improved First Paint times
• Code portability
• Using static HTML export in Next.js
• Supported features in Next.js static HTML export
• Unsupported features in Next.js static HTML export

So, let’s get started!

Why use static HTML?

There are three key reasons you might want to opt for using static HTML: SEO benefits, improved First Paint times, and code portability. Let’s take a deeper look at each of these.

SEO benefits

When you host static HTML files, all of the content is already pre-generated into the HTML that will be sent to the user. This means that when SEO crawlers visit your site to index content, they can easily see all of the available content and work their way through it.

If we compared this to a traditional React application that uses client-side rendering and the content isn’t pregenerated into static HTML files, the SEO crawler wouldn’t be able to access the content in the HTML, meaning it can’t index your site.

This is why it is heavily recommended from an SEO perspective to use static-site generation (SSG) over client-side rendering when possible. Static HTML is always better for SEO.

Improved First Paint times

Another benefit of having your content already generated into static HTML is there’s no rendering required either on the server at request time or by the client once it receives the code. This means the content is displayed (or, painted) to the user faster.

This is often referred to as the First Paint time, but, why is this important? Besides faster websites giving better user experiences for your users, the First Paint time is another factor that plays into your site’s overall SEO score, so the faster your website paints, the better your SEO.

Code portability

Finally, as we touched on earlier, you don’t need any special equipment to run static HTML files. They can be hosted anywhere and don’t require an active Node.js server running to handle things like server-side rendering (SSR) or redirects.

This means that with static HTML, you have less reliance on a particular service or equipment with increased flexibility, giving you the host your code wherever you wish.

Using static HTML export in Next.js

As promised earlier, let’s take a look at how we can export static HTML from a Next.js application and how easy it is to do.

Next.js has a built-in command for exporting static HTML from an application; this command is next export.

When you run this command, Next.js builds an HTML version of your application from pregenerated static files and copies them into the correct directory, ready for you to take away and use as you please.

You may now wonder, how do I pregenerate the static files? Well, this is where the next build command comes in.

next build creates the HTML files for next export to bundle. When you call next build, getStaticProps and getStaticPaths generates an HTML file for each page in your pages directory. Note that if you have dynamic routes set up, more pages will be created as required.

Because next export and next build are so closely linked, a common approach to handling the generation of static HTML in a Next.js application is to amend the build command inside the package.json file. By default, it looks like this:

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

But, we can amend it to handle both generating and exporting the static HTML. To do this, change your build script from above to look like this:

"scripts": {
  "build": "next build && next export",
},
<

Now, when we call the build script, the HTML builds, exports, and is ready for to use.

Supported features in Next.js static HTML export

When building a static site and exporting static HTML from a Next.js application, you may expect there to be some restrictions (and, there are).

But, the majority of the core Next.js features that you may want/need to build a static site are supported, even when exporting to static HTML.

These features include the following:

• Using dynamic routes when using getStaticPaths
• Prefetching with next/link
• Preloading JavaScript
• Dynamic imports
• Any styling options (such as CSS Modules or styled-jsx)
• Client-side data fetching
• getStaticProps
• getStaticPaths
• Image optimization using a custom loader

As you can see, many of the common features you use in Next.js, such as dynamic routes, preloading, prefetching links, and client-side data fetching, are still supported when exporting static HTML from a Next.js application.

Unsupported features in Next.js static HTML export

However, it’s not all sunshine and rainbows, unfortunately. Because we export our application to static HTML files, we lose any of the features that require a Node.js server to run or any dynamic logic that cannot complete during the build process when exporting the files.

This includes features like the following:

• Image optimization (default loader)
• Internationalized routing
• API routes
• Rewrites
• Redirects
• Headers
• Middleware
• Incremental static regeneration
• fallback: true
• getServerSideProps

Conclusion

So, that’s it! Throughout this article, we looked at all things static HTML export-related in Next.js from what it is to why we would want to use it to the features that are and aren’t supported using it.

Overall, static HTML export is a great feature within Next.js; it allows us to build sites with the perks of Next.js and React as a whole, but still get the speed and SEO benefits of hosting our website with static HTML files.

I hope you found this article all about static HTML export in Next.js helpful. If you did, please consider following me over on Twitter, where I post helpful and actionable tips and content on the JavaScript ecosystem and web development as a whole.

Or, if Twitter isn’t your thing, visit my blog for more of my content.