Find file History
Ziinc and tannerlinsley Update plugin documentation to be more concise. (#942)
<!--- Provide a general summary of your changes in the Title above -->

## Description
<!--- Describe your changes in detail -->

## Changes/Tasks
<!--- Add your changes or task as points (descriptions can be TL;DR) -->
- [ ] Changed code

## Motivation and Context
<!--- Why is this change required? What problem does it solve? -->
<!--- If it fixes an open issue, please link to the issue here. -->

## Screenshots (if appropriate):
<!--- If not delete the sub-heading above -->

## Types of changes
<!--- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
- [ ] Refactoring/add tests (refactoring or adding test which isn't a fix or add a feature)
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)

## Checklist:
<!--- Go over all the following points, and put an `x` in all the boxes that apply. -->
- [x] My change requires a change to the documentation.
  - [x] I have updated the documentation accordingly.
- [ ] My changes have tests around them
Latest commit 7986671 Jan 4, 2019

README.md

Plugins

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

Installing Plugins

Official 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/plugin.js would resolve to that path.
  2. Plugins found in the /plugins directory of your project root. Eg. myPlugin would resolve to /plugins/myPlugins.js.
  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.