Warn when implementing apis twice

docs/docs/debugging-replace-renderer-api.md

@@ -0,0 +1,113 @@
+---
+title: Debugging replaceRenderer API
+---
+
+## What is the `replaceRenderer` API?
+
+The `replaceRenderer` API is one of [Gatsby's Server Side Rendering (SSR) extension APIs](/docs/ssr-apis/#replaceRenderer). This API is called when you run `gatsby build` and is used to customise how Gatsby renders your static content. It can be implemented by any Gatsby plugin or your `gatsby-ssr.js` file - adding support for Redux, CSS-in-JS libraries or any code that needs to change Gatsby's default HTML output.
+
+## Why does it cause build errors?
+
+If multiple plugins implement `replaceRenderer` in your project, only the last plugin implementing the API can be called - which will break your site builds.
+
+Note that `replaceRenderer` is only used during `gatsby build`. It won't cause problems as you work on your site with `gatsby develop`.
+
+If multiple plugins implement `replaceRenderer`, `gatsby build` will warn you:
+
+```
+The "replaceRenderer" API  is implemented by several enabled plugins.
+This could be an error, see https://gatsbyjs.org/docs/debugging-replace-renderer-api for workarounds.
+Check the following plugins for "replaceRenderer" implementations:
+/path/to/my/site/node_modules/gatsby-plugin-styled-components/gatsby-ssr.js
+/path/to/my/site/gatsby-ssr.js
+```
+
+## Fixing `replaceRenderer` build errors
+
+If you see errors during your build, you can fix them with the following steps.
+
+### 1. Identify the plugins using `replaceRenderer`
+
+Your error message should list the files that use `replaceRenderer`
+
+```shell
+Check the following files for "replaceRenderer" implementations:
+/path/to/my/site/node_modules/gatsby-plugin-styled-components/gatsby-ssr.js
+/path/to/my/site/gatsby-ssr.js
+```
+
+In this example, your `gatsby-ssr.js` file and `gatsby-plugin-styled-components` are both using `replaceRenderer`.
+
+### 2. Copy the plugins' `replaceRenderer` functionality to your site's `gatsby-ssr.js` file
+
+You'll need to override your plugins' `replaceRenderer` code in your `gatsby-ssr.js` file. This step will be different for each project, keep reading to see an example.
+
+## Example
+
+### Initial setup
+
+In this example project we're using [`redux`](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-redux) and [Gatsby's Styled Components plugin](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-styled-components).
+
+`gatsby-config.js`
+
+```js
+module.exports = {
+  plugins: [`gatsby-plugin-styled-components`],
+}
+```
+
+`gatsby-ssr.js` (based on the [using Redux example](https://github.com/gatsbyjs/gatsby/blob/master/examples/using-redux/gatsby-ssr.js))
+
+```js
+import React from "react"
+import { Provider } from "react-redux"
+import { renderToString } from "react-dom/server"
+
+import createStore from "./src/state/createStore"
+
+exports.replaceRenderer = ({ bodyComponent, replaceBodyHTMLString }) => {
+  const store = createStore()
+
+  const ConnectedBody = () => <Provider store={store}>{bodyComponent}</Provider>
+  replaceBodyHTMLString(renderToString(<ConnectedBody />))
+}
+```
+
+Note that the Styled Components plugin uses `replaceRenderer`, and the code in `gatsby-ssr.js` also uses `replaceRenderer`.
+
+### Fixing the `replaceRenderer` error
+
+Our `gatsby-config.js` file will remain unchanged. However, oour `gatsby-ssr.js` file will update to include the [`replaceRenderer` functionality from the Styled Components plugin](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-plugin-styled-components/src/gatsby-ssr.js)
+
+`gatsby-ssr.js`
+
+```js
+import React from "react"
+import { Provider } from "react-redux"
+import { renderToString } from "react-dom/server"
+import { ServerStyleSheet, StyleSheetManager } from "styled-components"
+import createStore from "./src/state/createStore"
+
+exports.replaceRenderer = ({
+  bodyComponent,
+  replaceBodyHTMLString,
+  setHeadComponents,
+}) => {
+  const sheet = new ServerStyleSheet()
+  const store = createStore()
+
+  const app = () => (
+    <Provider store={store}>
+      <StyleSheetManager sheet={sheet.instance}>
+        {bodyComponent}
+      </StyleSheetManager>
+    </Provider>
+  )
+  replaceBodyHTMLString(renderToString(<app />))
+  setHeadComponents([sheet.getStyleElement()])
+}
+```
+
+Now `gatsby-ssr.js` implements the Styled Components and Redux functionality using one `replaceRenderer` instance. Run `gatsby build` and the site will build without errors.
+
+All the code from this example is [available on GitHub](https://github.com/m-allanson/gatsby-replace-renderer-example/commits/master).

packages/gatsby/cache-dir/api-runner-browser.js

@@ -1,8 +1,14 @@
 // During bootstrap, we write requires at top of this file which looks
 // basically like:
 // var plugins = [
-//   require('/path/to/plugin1/gatsby-browser.js'),
-//   require('/path/to/plugin2/gatsby-browser.js'),
+//   {
+//     plugin: require("/path/to/plugin1/gatsby-browser.js"),
+//     options: { ... },
+//   },
+//   {
+//     plugin: require("/path/to/plugin2/gatsby-browser.js"),
+//     options: { ... },
+//   },
 // ]
 
 export function apiRunner(api, args, defaultReturn) {

packages/gatsby/cache-dir/api-runner-ssr.js

@@ -1,15 +1,23 @@
 // During bootstrap, we write requires at top of this file which looks like:
 // var plugins = [
-//   require('/path/to/plugin1/gatsby-ssr.js'),
-//   require('/path/to/plugin2/gatsby-ssr.js'),
+//   {
+//     plugin: require("/path/to/plugin1/gatsby-ssr.js"),
+//     options: { ... },
+//   },
+//   {
+//     plugin: require("/path/to/plugin2/gatsby-ssr.js"),
+//     options: { ... },
+//   },
 // ]
 
 const apis = require(`./api-ssr-docs`)
 
+// Run the specified API in any plugins that have implemented it
 module.exports = (api, args, defaultReturn) => {
   if (!apis[api]) {
     console.log(`This API doesn't exist`, api)
   }
+
   // Run each plugin in series.
   let results = plugins.map(plugin => {
     if (plugin.plugin[api]) {

packages/gatsby/cache-dir/develop-static-entry.js

@@ -1,8 +1,8 @@
 import React from "react"
 import { renderToStaticMarkup } from "react-dom/server"
 import { merge } from "lodash"
-import apiRunner from "./api-runner-ssr"
 import testRequireError from "./test-require-error"
+import apiRunner from "./api-runner-ssr"
 
 let HTML
 try {
@@ -17,7 +17,6 @@ try {
 }
 
 module.exports = (locals, callback) => {
-  // const apiRunner = require(`${directory}/.cache/api-runner-ssr`)
   let headComponents = []
   let htmlAttributes = {}
   let bodyAttributes = {}

packages/gatsby/src/bootstrap/__mocks__/resolve-module-exports.js

@@ -0,0 +1,19 @@
+'use strict'
+
+let mockResults = {}
+
+module.exports = input => {
+  // return a mocked result
+  if (typeof input === `string`) {
+    return mockResults[input]
+  }
+
+  // return default result
+  if (typeof input !== `object`) {
+    return []
+  }
+
+  // set mock results
+  mockResults = Object.assign({}, input)
+  return undefined
+}

packages/gatsby/src/bootstrap/index.js

@@ -1,13 +1,13 @@
 /* @flow */
 const Promise = require(`bluebird`)
 
-const glob = require(`glob`)
 const _ = require(`lodash`)
 const slash = require(`slash`)
 const fs = require(`fs-extra`)
 const md5File = require(`md5-file/promise`)
 const crypto = require(`crypto`)
 const del = require(`del`)
+const path = require(`path`)
 
 const apiRunnerNode = require(`../utils/api-runner-node`)
 const { graphql } = require(`graphql`)
@@ -175,9 +175,17 @@ module.exports = async (args: BootstrapArgs) => {
 
   // Find plugins which implement gatsby-browser and gatsby-ssr and write
   // out api-runners for them.
-  const hasAPIFile = (env, plugin) =>
-    // TODO make this async...
-    glob.sync(`${plugin.resolve}/gatsby-${env}*`)[0]
+  const hasAPIFile = (env, plugin) => {
+    // The plugin loader has disabled SSR APIs for this plugin. Usually due to
+    // multiple implementations of an API that can only be implemented once
+    if (env === `ssr` && plugin.skipSSR === true) return undefined
+
+    const envAPIs = plugin[`${env}APIs`]
+    if (envAPIs && Array.isArray(envAPIs) && envAPIs.length > 0 ) {
+      return path.join(plugin.resolve, `gatsby-${env}.js`)
+    }
+    return undefined
+  }
 
   const ssrPlugins = _.filter(
     flattenedPlugins.map(plugin => {