Skip to content
Branch: master
Find file History
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
README.md fix broken link in docs/plugins/README.md (#1280) Aug 13, 2019
browser-api.md V7 (#1079) Apr 1, 2019
node-api.md Adds `afterBundle` hook to Plugin API (#1159) Apr 29, 2019

README.md

Plugins

React Static ships with a plugin API to extend React Static's functionality.

Installing Plugins

Official Plugins via NPM

Unofficial Plugins via NPM

Local Plugins via the /plugins directory

If you have a custom plugin or are developing a plugin locally, you can place your plugin directory in the /plugins directory in your project root. It can then be used by React Static.

Local Plugin API via the /node.api.js and /browser.api.js project files

If you simply need direct access to the the plugin API for a project, you can create a node.api.js and/or browser.api.js file in the root of your project. These files are treated just like plugins themselves, but do not receive plugin options and are executed very last in the plugin cycle.

Using & Configuring Plugins

After installation, configure it by adding it to the plugins array in static.config.js:

// static.config.js
export default {
  plugins: ['react-static-plugin-emotion', 'my-custom-plugin'],
}

Plugin Execution and Order (IMPORTANT)

Order of execution:

  1. Plugins in plugins: [], starting from the first element of array.
  2. Any node.api.js and browser.api.js files at the project root.

Plugin Resolution

Plugins are resolved in this order:

  1. Plugins with an absolute path. Eg. ~/path/to/my/my-plugin would resolve to that path.
  2. Plugins found in the /plugins directory of your project root. Eg. my-plugin would resolve to /plugins/my-plugin.
  3. Plugins found in node_modules. Eg. react-static-plugin-emotion would resolve to node_modules/react-static-plugin-emotion.

Plugin Options

Plugins can be passed options by using an array (similar to how babel and eslint work).

  • The first item in the array is the plugin name string
  • The second item in the array is the options object that will be passed to the plugin
// static.config.js

export default {
  plugins: [
    [
      'react-static-plugin-awesomeness',
      {
        isAwesome: true,
      },
    ],
  ],
}

Plugin API

All plugins contains at least one of:

Why use separate node and browser entry points for plugins?

Separating plugin entrypoints avoids creating conflict with imported modules that may not be supported in both environments.

How to write the node.api.js and browser.api.js files when creating plugins?

The file (for either environment) must:

  • Provide a function as the default export
  • That function receives an optional user plugin options argument
  • Return an object providing any API methods to implement

Basic plugin example:

export default pluginOptions => ({
  myCustomAPIMethod: options => {
    console.log('hello world')
  },
})

What can plugins do?

View the browser API docs and the node API docs for full list of API methods that can be implemented.

Plugins must be compiled if installed via node_modules

Only the plugins directory will be transformed by react-static's babel runtime.

Hence, when distributing your plugin, your plugin must be ES5 compatible.

You can’t perform that action at this time.