@slorber/static-site-generator-webpack-plugin

What is @slorber/static-site-generator-webpack-plugin?

@slorber/static-site-generator-webpack-plugin is a Webpack plugin designed to generate static HTML files from your Webpack bundles. It is particularly useful for static site generation, allowing you to pre-render your React components or other JavaScript-based views into static HTML files.

What are @slorber/static-site-generator-webpack-plugin's main functionalities?

Basic Static Site Generation

This code demonstrates the basic setup for generating a static site using @slorber/static-site-generator-webpack-plugin. It specifies the entry point, output configuration, and initializes the plugin with paths to be pre-rendered.

const StaticSiteGeneratorPlugin = require('@slorber/static-site-generator-webpack-plugin');
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    libraryTarget: 'umd'
  },
  plugins: [
    new StaticSiteGeneratorPlugin({
      entry: 'main',
      paths: ['/'],
      locals: {
        title: 'My Static Site'
      }
    })
  ]
};

Multiple Paths Generation

This example extends the basic setup to generate static HTML for multiple paths ('/', '/about', '/contact'). This is useful for sites with multiple pages.

const StaticSiteGeneratorPlugin = require('@slorber/static-site-generator-webpack-plugin');
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    libraryTarget: 'umd'
  },
  plugins: [
    new StaticSiteGeneratorPlugin({
      entry: 'main',
      paths: ['/', '/about', '/contact'],
      locals: {
        title: 'My Static Site'
      }
    })
  ]
};

Using Locals for Dynamic Content

This example shows how to pass dynamic content to the static site generator using the 'locals' object. This can be used to inject data like titles, descriptions, or other metadata into the generated HTML.

const StaticSiteGeneratorPlugin = require('@slorber/static-site-generator-webpack-plugin');
const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    filename: 'bundle.js',
    path: path.resolve(__dirname, 'dist'),
    libraryTarget: 'umd'
  },
  plugins: [
    new StaticSiteGeneratorPlugin({
      entry: 'main',
      paths: ['/'],
      locals: {
        title: 'My Static Site',
        description: 'This is a description for my static site.'
      }
    })
  ]
};

Other packages similar to @slorber/static-site-generator-webpack-plugin

prerender-loader

prerender-loader is a Webpack loader that pre-renders JavaScript applications into static HTML. It is similar to @slorber/static-site-generator-webpack-plugin but operates as a loader rather than a plugin, which can offer more flexibility in certain build configurations.

react-snap

react-snap is a zero-configuration static pre-renderer for React apps. It crawls your site and generates static HTML files. Unlike @slorber/static-site-generator-webpack-plugin, react-snap is specifically tailored for React applications and offers a simpler setup process.

gatsby

Gatsby is a React-based framework for building static sites. It offers a comprehensive set of features for static site generation, including data fetching, routing, and plugins. While more complex than @slorber/static-site-generator-webpack-plugin, Gatsby provides a full-fledged solution for static site development.

README

FORK FOR DOCUSAURUS

This is a fork used for Docusaurus

This fixes trailing slash issues by allowing to output /filename.html instead of /filename/index.html by exposing a preferFoldersOutput: false option.

It is based on a previous fork by Endiliey: https://github.com/endiliey/static-site-generator-webpack-plugin

I don't know the reasons of the initial fork.

We also added a concurrency: 32 option to avoid overloading the system with too much IO (using p-map)

static site generator webpack plugin

Minimal, unopinionated static site generator powered by webpack.

Bring the world of server rendering to your static build process. Either provide an array of paths to be rendered and a matching set of index.html files will be rendered in your output directory by executing your own custom, webpack-compiled render function.

This plugin works particularly well with universal libraries like React and React Router since it allows you to pre-render your routes at build time, rather than requiring a Node server in production.

Install

$ npm install --save-dev @slorber/static-site-generator-webpack-plugin

Usage

Ensure you have webpack installed, e.g. npm install -g webpack

webpack.config.js

const StaticSiteGeneratorPlugin = require('@slorber/static-site-generator-webpack-plugin');

module.exports = {

  entry: './index.js',

  output: {
    filename: 'index.js',
    path: 'dist',
    /* IMPORTANT!
     * You must compile to UMD or CommonJS
     * so it can be required in a Node context: */
    libraryTarget: 'umd'
  },

  plugins: [
    new StaticSiteGeneratorPlugin({
      paths: [
        '/hello/',
        '/world/'
      ],
      locals: {
        // Properties here are merged into `locals`
        // passed to the exported render function
        greet: 'Hello'
      }
    })
  ]

};

index.js

Sync rendering:

module.exports = function render(locals) {
  return '<html>' + locals.greet + ' from ' + locals.path + '</html>';
};

Async rendering via callbacks:

module.exports = function render(locals, callback) {
  callback(null, '<html>' + locals.greet + ' from ' + locals.path + '</html>');
};

Async rendering via promises:

module.exports = function render(locals) {
  return Promise.resolve('<html>' + locals.greet + ' from ' + locals.path + '</html>');
};

Multi rendering

If you need to generate multiple files per render, or you need to alter the path, you can return an object instead of a string, where each key is the path, and the value is the file contents:

module.exports = function render() {
  return {
    '/': '<html>Home</html>',
    '/hello': '<html>Hello</html>',
    '/world': '<html>World</html>'
  };
};

Note that this will still be executed for each entry in your paths array in your plugin config.

Default locals

// The path currently being rendered:
locals.path;

// An object containing all assets:
locals.assets;

// Advanced: Webpack's stats object:
locals.webpackStats;

Any additional locals provided in your config are also available.

Custom file names

By providing paths that end in .html, you can generate custom file names other than the default index.html. Please note that this may break compatibility with your router, if you're using one.

module.exports = {

  ...

  plugins: [
    new StaticSiteGeneratorPlugin({
      paths: [
        '/index.html',
        '/news.html',
        '/about.html'
      ]
    })
  ]
};

Globals

If required, you can provide an object that will exist in the global scope when executing your render function. This is particularly useful if certain libraries or tooling you're using assumes a browser environment.

For example, when using Webpack's require.ensure, which assumes that window exists:

module.exports = {
  ...,
  plugins: [
    new StaticSiteGeneratorPlugin({
      globals: {
        window: {}
      }
    })
  ]
}

Asset support

template.ejs

<% css.forEach(function(file){ %>
<link href="<%- file %>" rel="stylesheet">
<% }); %>

<% js.forEach(function(file){ %>
<script src="<%- file %>" async></script>
<% }); %>

index.js

if (typeof global.document !== 'undefined') {
  const rootEl = global.document.getElementById('outlay');
  React.render(
    <App />,
    rootEl,
  );
}

export default (data) => {
  const assets = Object.keys(data.webpackStats.compilation.assets);
  const css = assets.filter(value => value.match(/\.css$/));
  const js = assets.filter(value => value.match(/\.js$/));
  return template({ css, js, ...data});
}

Specifying entry

This plugin defaults to the first chunk found. While this should work in most cases, you can specify the entry name if needed:

module.exports = {
  ...,
  plugins: [
    new StaticSiteGeneratorPlugin({
      entry: 'main'
    })
  ]
}

Compression support

Generated files can be compressed with compression-webpack-plugin, but first ensure that this plugin appears before compression-webpack-plugin in your plugins array:

const StaticSiteGeneratorPlugin = require('@slorber/static-site-generator-webpack-plugin');
const CompressionPlugin = require('compression-webpack-plugin');

module.exports = {
  ...

  plugins: [
    new StaticSiteGeneratorPlugin(...),
    new CompressionPlugin(...)
  ]
};

Related projects

• react-router-to-array - useful for avoiding hardcoded lists of routes to render
• gatsby - opinionated static site generator built on top of this plugin

License

MIT License