Going Full Static
Too long to read
- Upgrade nuxt to
2.13.0
- Set
target: 'static'
in yournuxt.config.js
- Run
nuxt build && nuxt export
instead ofnuxt generate
- That's it ✨
Bonus: you can run nuxt serve
to run a local server serving your generated static application.
Table of Contents
- Too long to read
- Table of Contents
- History
- Current issues
- New config option:
target
- New command:
nuxt export
- New command:
nuxt serve
- Preview mode
- Commands
- Notes
History
Nuxt had the static generation feature with nuxt generate
since v0.3.2 (November 2016), since then we have improved it in multiple ways but never achieved full static generation. Today I am excited to announce that full static export is now possible with Nuxt 2.13.
Current issues
nuxt generate
is mostly pre-rendering, when you navigate client-side, asyncData
and fetch
are called, making a request to your API. A lot of users asked to support a "full static" mode, meaning to not call these 2 hooks on navigation, since the next page has been already pre-rendered.
Also, the developer experience is not optimal:
- You have access to
req
orres
on SSR but not when runningnuxt generate
process.static
istrue
only when runningnuxt generate
, making it slow to develop Nuxt modules or plugins for static generation- You have to specify all your dynamic routes in
generate.routes
, making it harder since you don't have access to nuxt modules there. - You cannot test the SPA fallback in development, the fallback is a client-only version of your Nuxt application that loads when hitting a 404 page
nuxt generate
runsnuxt build
by default, making it slower to generate your website if only your content changed
Note that it was possible to have full static support with nuxt-payload-extractor module but it was more verbose to use and had limitations.
target
New config option: To improve the user experience as well as telling Nuxt that you want to export your application to static hosting, we are introducing a target
option in your nuxt.config.js
:
export default {
target: 'static' // default: 'server'
}
Running nuxt dev
with the static target will improve the developer experience:
- Remove
req
&res
from context - Fallback to client-side rendering on 404, errors and redirects (see SPA fallback)
$route.query
will always be equal to{}
on server-side renderingprocess.static
istrue
We are also exposing process.target
for modules author to add logic depending on the user target.
nuxt export
New command: To avoid introducing a breaking change for nuxt generate
, we are introducing a new command called nuxt export
: export your Nuxt app to static HTML in a dist/
directory.
⚠️ You need to run nuxt build
before calling nuxt export
Crazy fast static applications
nuxt export
will pre-render all your pages to HTML and save a payload file in order to mock asyncData
and fetch
on client-side navigation, this means no more HTTP calls to your API on client-side navigation. By extracting the page payload to a js file, it also reduces the HTML size served as well as preloading it (from the in the header) for optimal performance.
We also improved the smart prefetching when doing full static, it will also fetch the payloads, making navigation instant 👀
Crawler integrated
On top of that, it also has a crawler inside, detecting every relative link and generating it:
If you want to exclude a bunch of routes, use the generate.exclude. You can keep using generate.routes to add extra routes that the crawler could not detect.
To disable the crawler, set generate.crawler: false
in your nuxt.config.js
Faster re-deploy
By separating nuxt build
and nuxt export
, we are opening a new range of improvements: pre-render your pages only if you content has changed, this means: no Wepack build → faster redeployments.
nuxt serve
New command: Once you statically generated your Nuxt app into dist/
, use nuxt serve
to start a production HTTP server and serve your static app, supporting SPA Fallback.
This command is perfect to locally test your static application before pushing to your favourite static hosting provider.
Preview mode
We do support live preview out of the box to keep calling your API:
// plugins/preview.client.js
export default async function ({ query, enablePreview }) {
if (query.preview) {
enablePreview()
}
}
It will automatically refresh the page data (calling nuxtServerInit
, asyncData
and fetch
).
When the preview mode is activated, asyncData
and fetch
original methods will be called.
Commands
You can now run different commands depending of the target
:
server
nuxt dev
: Start the development servernuxt build
: Bundle your Nuxt application for productionnuxt start
: Start the production server
static
nuxt dev
: Start the development server (static aware)nuxt build
: Bundle your Nuxt application for production (static aware)nuxt export
: Export your application to static HTML indist/
directorynuxt serve
: Serve your production application fromdist/
Notes
- We added
export
key innuxt.config.js
which is currently an alias ofgenerate
, it will take over for Nuxt 3 nuxt generate
is being deprecated (but still working without any breaking change now) and will be removed for Nuxt 3- We added
export
hooks that are slightly different thangenerate
hooks to improve module possibilities
What to do next
- To learn more about how to move from @nuxtjs/dotenv to runtime config check out this article.
- Subscribe to the newsletter to not miss the upcoming articles and resources.