Add prerender-spa-plugin into your Vue application with zero configuration.
Looking for a co-maintainer: I'm continuing to maintain this project, hoever I still would like help on some of the issues, and generally to help me keep this plugin going as it's getting more and more popular. If you think you can help, file and issue for maintainship!
Support requests: Vue has a Discord server and I often lurk in there. And while there is a support label in the Issues, GitHub isn't the place for support requests and should be directed to me in the Vue Land Discord server.
Add prerendering to your Vue application with:
vue add prerender-spaor by searching for prerender-spa in the Vue UI plugins.
You'll be asked a few questions, detailed below, to which the default answers are the most common options.
The main option to fit to your needs is the list of routes to pre-render. Specify them as a comma-separated list:
? Which routes to pre-render? (list them separated by a comma) /,/about,/contact? Which routes to pre-render? (list them separated by a comma) /Specify a list of routes to pre-render. By default only the index page is pre- rendered, which should cover most SPAs. If your project uses vue-router, you can specify a list of routes that do not depend on dynamic content (like user uploaded data, public profiles, etc.). For example you can add your about page as well as a contact page - those will load faster, and will be indexed by bots who do not execute JavaScript, improving Search Engines rankings.
Note that if you want to also pre-render user generated content, you will have to switch to Server-Side Rendering, there are no other options.
The list of routes is split into an array and passed into the Webpack plugin.
The routes aren't checked for existence or even duplicates, just split into an
array and sent to the PrerenderSPAPlugin instance.
? Use a render event to trigger the snapshot? YesUse a document event to signal prerender-spa-plugin to trigger a snapshot of
the DOM and save it. By default the renderer waits until DOMContentLoaded to
take a snapshot of the DOM. But it is still recommended that you control the
snapshot trigger - no surprise waiting for hours for your build before
realizing what's happening.
When enabling the event-based snapshot trigger, it will tell
PrerenderSPAPlugin to listen for an x-app-rendered event. Your main file
is then modified to add a mounted() hook where the event will fire. Note that
it doesn't check if the hook is already present, nor does it parses the file;
it just looks for the line starting with render: (minus whitespaces) and
inserts the mounted() hook below. If you already have the hook set up, or if
your render() function on the main file is longer than one line, it will break
your Vue entrypoint. A better injection routine is planned, but for now, it
covers a vast majority of projects where the main file isn't touched.
? Use a headless browser to render the application? (recommended) YesThis option is there for debugging purposes, but should be left enabled otherwise. Not using a headless browser will open a Chrome window when building with your app running inside, then close once the snapshot has been taken. Since the plugin configuration object isn't available, it is available here.
The headless value of the configuration object is set to the answer to the
question.
? Only use prerendering for production builds? (recommended) YesOnly load the pre-rendering plugin when building for production. This is strongly recommended as the plugin, spawning an instance of the Chrome browser, adds significant time to the build process. Development builds should be snappy and not memory-intensive; which is exactly what this plugin does to your build.
However, there may be cases where you want to test the pre-rendering itself, and switching to a production build isn't the solution - you may then turn off that option.
This option is configured from within the Vue CLI itself, but serves to a whole host of plugins to determine whether to turn on parallel jobs / multi-threading.
This plugin uses it to tell prerender-spa-plugin to render pages concurrently
(meaning in parallel) or not by setting the maxConcurrentRoutes parameter to
either 1 or 4, if the build is respectively single-threaded or multi-threaded.
After being invoked, the plugin saves a file named .prerender-spa.json in the
root directory of the project; where you can specify custom options for the
Puppeteer renderer. It will be merged, and its options will overwrite those set
by the plugin itself.
Other way to set custom configuration for the Puppeteer renderer is to use customRendererConfig
dictionary of possible Puppeteer launch options.
Example configuration of debugging your site with Chrome DevTools opened automatically:
// vue.config.js
module.exports = {
pluginOptions: {
prerenderSpa: {
registry: undefined,
renderRoutes: [
'/',
'/about'
],
useRenderEvent: true,
onlyProduction: true,
headless: false, // <- this could also be inside the customRendererConfig
customRendererConfig:
{
args: ["--auto-open-devtools-for-tabs"]
}
}
}
}Pupeteer allows to postprocess the HTML after it's been snapshot, and the plugin allows you to provide your own function if you need to.
Add a postProcess option into your vue.config.js file to provide a custom
post-processing function to run on every build.
Example configuration:
// vue.config.js
module.exports = {
pluginOptions: {
prerenderSpa: {
registry: undefined,
renderRoutes: [
'/',
'/about'
],
useRenderEvent: true,
headless: true,
onlyProduction: true,
postProcess: route => {
// Defer scripts and tell Vue it's been server rendered to trigger hydration
route.html = route.html
.replace(/<script (.*?)>/g, '<script $1 defer>')
.replace('id="app"', 'id="app" data-server-rendered="true"');
return route;
}
}
}
}You are very welcome to contribute. To ask for a feature, or submit a bug, use the Issues list. If you want to contribute a feature yourself, first submit an Issue, work on your code, and add a Pull Request, referencing your issue in the PR message. This way the isse can serve as a mean to discuss the feature, and the Pull Request is where we can review the code and talk specificities.
In all cases, follow the templates carefully, in order to maximize information throughput.
Since the index.html is now (most likely, depending on your list of routes)
pre-rendered, pointing to it from another path will lead to whiteflashing as
the pre-rendered content (of the index page) will not match the expected
content of the route (say from an about page). For this reason, the plugin
outputs another file called app.html that doesn't get pre-rendered. For
better user experience, it is recommended to route non-prerendered routes to
this file instead of the default index.html.
Here's an example nginx configuration snippet:
location / {
try_files $uri $uri/index.html $uri.html /app.html;
}And an example Firebase configuration (taken from https://stackoverflow.com/a/51218261):
"rewrites": [
{
"source": "**",
"destination": "/app.html"
},
{
"source": "/",
"destination": "/index.html"
}
]Because the prerender-spa-plugin uses a headless Chrome instance, your
regular node:latest Docker image will not chug your build correctly; you need
system dependencies and configuration that might not be efficient to add to the
job itself - rather, it is recommended to switch to a Node.js + Puppeteer
image where you can just use your install && build workflow without any
additional configuration. I personally use the alekzonder/puppeteer image.
If you do decide on using alekzonder/puppeteer and you want to install global npm packages. The following commands can be used prior to the installation of your required global package to ensure that you do not receive an EACCES: permission denied, access '/usr/local/lib/node_modules' error. I have tested this using Gitlab CI.
- mkdir ~/.npm-global
- npm config set prefix '~/.npm-global'
- npm install -g @vue/cli-service-global
This plugin should be compatible with any plugin that doesn't add a mounted()
hook into the Vue entrypoint in your main.{js,ts} file, as this is the only
file it updates, and only if you choose an event-based snapshot trigger.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
