From adfb8671d49d7be144813b22579a40f75e0acff8 Mon Sep 17 00:00:00 2001 From: Kyle Gill Date: Thu, 30 Jan 2020 06:25:29 -0700 Subject: [PATCH] docs: plugin authoring workflow overview pages (#20847) * additional examples to loading/creating, and plugin authoring overview pages * correct minor errors and add tweaks to titles * Apply suggestions from code review Co-Authored-By: LB * added example repo * Update docs/docs/creating-a-local-plugin.md * simplify the site readme * update readme for clearer instructions and explanations * Apply suggestions from code review Co-Authored-By: LB Co-authored-by: LB Co-authored-by: GatsbyJS Bot --- docs/docs/creating-a-local-plugin.md | 58 ++++++++-- ...-plugins-from-your-local-plugins-folder.md | 60 ++++++++-- docs/docs/naming-a-plugin.md | 7 +- docs/docs/plugins.md | 4 +- examples/using-local-plugins/README.md | 4 + .../using-multiple-local-plugins/README.md | 108 ++++++++++++++++++ .../gatsby-node.js | 3 + .../gatsby-plugin-console-log-b/index.js | 1 + .../gatsby-plugin-console-log-b/package.json | 7 ++ .../gatsby-node.js | 3 + .../gatsby-plugin-console-log-c/index.js | 1 + .../gatsby-plugin-console-log-c/package.json | 7 ++ .../.gitignore | 69 +++++++++++ .../.prettierignore | 4 + .../.prettierrc | 7 ++ .../gatsby-site-using-local-plugins/LICENSE | 22 ++++ .../gatsby-site-using-local-plugins/README.md | 3 + .../gatsby-config.js | 20 ++++ .../gatsby-node.js | 3 + .../package.json | 32 ++++++ .../gatsby-node.js | 3 + .../gatsby-plugin-console-log-a/index.js | 1 + .../gatsby-plugin-console-log-a/package.json | 7 ++ .../src/components/header.js | 42 +++++++ .../src/components/layout.css | 83 ++++++++++++++ .../src/components/layout.js | 51 +++++++++ .../src/pages/404.js | 12 ++ .../src/pages/index.js | 15 +++ 28 files changed, 614 insertions(+), 23 deletions(-) create mode 100644 examples/using-multiple-local-plugins/README.md create mode 100644 examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/gatsby-node.js create mode 100644 examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/index.js create mode 100644 examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/package.json create mode 100644 examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/gatsby-node.js create mode 100644 examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/index.js create mode 100644 examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/package.json create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.gitignore create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.prettierignore create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.prettierrc create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/LICENSE create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/README.md create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/gatsby-config.js create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/gatsby-node.js create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/package.json create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/gatsby-node.js create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/index.js create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/package.json create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/header.js create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/layout.css create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/layout.js create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/pages/404.js create mode 100644 examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/pages/index.js diff --git a/docs/docs/creating-a-local-plugin.md b/docs/docs/creating-a-local-plugin.md index 87266e7da4b39..1b2adffcf435c 100644 --- a/docs/docs/creating-a-local-plugin.md +++ b/docs/docs/creating-a-local-plugin.md @@ -4,24 +4,68 @@ title: Creating a Local Plugin If a plugin is only relevant to your specific use-case, or if you’re developing a plugin and want a simpler workflow, a locally defined plugin is a convenient way to create and manage your plugin code. +## Project structure for a local plugin + Place the code in the `plugins` folder in the root of your project like this: -```text -plugins -└── my-own-plugin - └── package.json +``` +/my-gatsby-site +└── gatsby-config.js +└── /src +└── /plugins + └── /my-own-plugin + └── package.json +``` + +The plugin also needs to be added to your `gatsby-config.js`, because there is no auto-detection of plugins. It can be added alongside any other 3rd party Gatsby plugins already included in your config. + +For the plugin to be discovered when you run `gatsby develop`, the plugin's root folder name needs to match the name used in the `gatsby-config.js` (_not_ the _name_ it goes by in your `package.json` file). For example, in the above structure, the correct way to load the plugin is: + +```javascript:title=gatsby-config.js +module.exports = { + plugins: [ + `gatsby-third-party-plugin`, + `my-own-plugin`, // highlight-line + ], +} ``` -**NOTE:** You still need to add the plugin to your `gatsby-config.js`. There is no auto-detection of local plugins. +Then the plugin can begin to hook into Gatsby through [Node](/docs/node-apis/) and [SSR](/docs/ssr-apis/) APIs. -**NOTE:** For the plugin to be discovered, the plugin's root folder name is the value that needs to be referenced in order to load it (_not_ its _name_ in its package.json file). For example, in the above structure, the correct way to load the plugin is: +## Developing a local plugin that is outside your project + +Your plugin doesn't have to be in your project in order to be tested or worked on. If you'd like to [decouple](/docs/glossary#decoupled) your plugin from your site you can follow one of the methods described below. This is a useful thing to do if you want to publish the plugin as its own package, or test/develop a forked version of a community authored plugin. + +### Using `require.resolve` and a filepath + +Including a `plugins` folder is not the only way to reference a local plugin. Alternatively, you can include a plugin in your `gatsby-config.js` file by directly referencing its path (relative to the `gatsby-config.js` file) with `require`. ```javascript:title=gatsby-config.js module.exports = { - plugins: ["my-own-plugin"], + plugins: [ + `gatsby-plugin-react-helmet`, + // highlight-start + { + // including a plugin from outside the plugins folder needs the path to it + resolve: require.resolve(`../path/to/gatsby-local-plugin`), + }, + // highlight-end + ], } ``` +### Using `npm link` or `yarn link` + +You can use [`npm link`](https://docs.npmjs.com/cli/link.html) or [`yarn link`](https://yarnpkg.com/lang/en/docs/cli/link/) to reference a package from another location on your machine. + +By running `npm link ../path/to/my-plugin` in the root of your Gatsby site, your computer will create a symlink to your package. + +This is a similar process to setting up yarn workspaces for development with Gatsby themes (which is the recommended approach for developing themes). You can read how to setup a site in this manner in the [Building a Theme guide](/tutorial/building-a-theme/#set-up-yarn-workspaces). + +**Note**: See an example of using a local plugin from the plugins folder, with `require.resolve`, and `npm link` in [this example repository](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-multiple-local-plugins). + +## Compilation and processing with Babel + Like all `gatsby-*` files, the code is not processed by Babel. If you want to use JavaScript syntax which isn't supported by your version of Node.js, you can place the files in a `src` subfolder and build them to the plugin folder diff --git a/docs/docs/loading-plugins-from-your-local-plugins-folder.md b/docs/docs/loading-plugins-from-your-local-plugins-folder.md index 92d9b59d7f443..ac2b3966eac0d 100644 --- a/docs/docs/loading-plugins-from-your-local-plugins-folder.md +++ b/docs/docs/loading-plugins-from-your-local-plugins-folder.md @@ -2,25 +2,61 @@ title: Loading Plugins from Your Local Plugins Folder --- -Gatsby can also load plugins from your website's local plugins folder which is a folder named `plugins` in the website's root directory. +Gatsby can load plugins from your website's local plugins folder, which is a folder named `plugins` in the website's root directory. -```javascript:title=gatsby-config.js -module.exports = { - plugins: [`gatsby-local-plugin`], -} +Consider this example project structure which includes a local plugin called `gatsby-local-plugin`: + +``` +/my-gatsby-site +└── /src + └── /pages + └── /components + +└── /plugins + └── /gatsby-local-plugin + └── /package.json + └── /gatsby-node.js + +└── gatsby-config.js +└── gatsby-node.js +└── package.json ``` -If you want to reference a plugin that is not in the plugins folder then you could use something like the following: +Like the name of the plugins folder implies, you can include multiple plugins in your local plugin folder. + +Including a local plugin in your plugins folder also requires a configuration step (similar to a third-party plugin you've installed in your `node_modules` folder by running `npm install`); just as plugins installed from npm need to be included in your `gatsby-config`, you need to add the name of your local plugin to the plugins array as well: ```javascript:title=gatsby-config.js module.exports = { plugins: [ - // Shortcut for adding plugins without options. - "gatsby-plugin-react-helmet", - { - // Standard plugin with options example - resolve: require.resolve(`/path/to/gatsby-local-plugin`), - }, + `gatsby-third-party-plugin`, + `gatsby-local-plugin`, // highlight-line ], } ``` + +## Verifying your plugin is loading + +To verify that your plugin is available for use in your Gatsby site, you can add a small snippet of code to a `gatsby-node.js` file (you may need to add the `gatsby-node.js` file if there isn't one already) in the root of your plugin: + +```javascript:title=plugins/gatsby-local-plugin/gatsby-node.js +exports.onPreInit = () => { + console.log("Testing...") +} +``` + +_The [`onPreInit` API](/docs/node-apis/#onPreInit) is the first Node API called by Gatsby right after plugins are loaded._ + +Then, when running your site in develop or build mode, you should see "Testing..." logged in your terminal: + +```sh +success open and validate gatsby-configs - 0.051s +success load plugins - 1.047s +Testing... // highlight-line +success onPreInit - 0.023s +... +``` + +## Loading local plugins from _outside_ the plugins folder + +If you want to reference a plugin that is not in the plugins folder, there are several options that are described in more detail in the [Creating a Local Plugin guide](/docs/creating-a-local-plugin/). diff --git a/docs/docs/naming-a-plugin.md b/docs/docs/naming-a-plugin.md index 98315b5d5b7be..955989e576862 100644 --- a/docs/docs/naming-a-plugin.md +++ b/docs/docs/naming-a-plugin.md @@ -4,7 +4,7 @@ title: Naming a Plugin ## Plugin title naming conventions -There are four standard plugin naming conventions for Gatsby: +There are five standard plugin naming conventions for Gatsby: - **`gatsby-source-*`** — a source plugin loads data from a given source (e.g. WordPress, MongoDB, the file system). Use this plugin type if you are connecting a new source of data to Gatsby. - Example: [`gatsby-source-contentful`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-source-contentful) @@ -14,6 +14,9 @@ There are four standard plugin naming conventions for Gatsby: - Docs: [creating a transformer plugin](/docs/creating-a-transformer-plugin/) - **`gatsby-[plugin-name]-*`** — if a plugin is a plugin for another plugin 😅, it should be prefixed with the name of the plugin it extends (e.g. if it adds emoji to the output of `gatsby-transformer-remark`, call it `gatsby-remark-add-emoji`). Use this naming convention whenever your plugin will be included as a plugin in the `options` object of another plugin. - Example: [`gatsby-remark-images`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-remark-images) -- **`gatsby-theme-*`** — this naming convention must be used for [Gatsby themes](/docs/themes/), which are a type of plugin. + - Docs: [creating a remark plugin](/docs/remark-plugin-tutorial/) +- **`gatsby-theme-*`** — this naming convention **must** be used for [Gatsby themes](/docs/themes/), which are a type of plugin. Without following this naming convention, the plugin will not be recognized as a theme and it will not be able to utilize the powerful [shadowing](/docs/themes/shadowing/) feature of themes. + - Example: [`gatsby-theme-blog`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-theme-blog) + - Docs: [creating a theme](/tutorial/building-a-theme/) - **`gatsby-plugin-*`** — this is the most general plugin type. Use this naming convention if your plugin doesn’t meet the requirements of any other plugin types. - Example: [`gatsby-plugin-sharp`](https://github.com/gatsbyjs/gatsby/tree/master/packages/gatsby-plugin-sharp) diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md index 76a97003f9690..fc860e5342be6 100644 --- a/docs/docs/plugins.md +++ b/docs/docs/plugins.md @@ -4,9 +4,9 @@ title: Plugins Gatsby plugins are Node.js packages that implement Gatsby APIs. For larger, more complex sites, plugins let you modularize your site customizations into site-specific plugins. -There are many types of Gatsby plugins, including data sourcing, SEO, responsive images, offline support, Sass support, sitemaps, RSS feeds, TypeScript, Google Analytics, and more. You can also [make your own plugins](/docs/creating-plugins/)! +There are many types of Gatsby plugins, including [data sourcing](/plugins/?=gatsby-source), [SEO](/plugins/?=seo), [responsive images](/packages/gatsby-image/?=gatsby-image), [offline support](/packages/gatsby-plugin-offline/), [Sass support](/packages/gatsby-plugin-sass/), [sitemaps](/packages/gatsby-plugin-sitemap/), [RSS feeds](/packages/gatsby-plugin-feed/), [TypeScript](/packages/gatsby-plugin-typescript/), [Google Analytics](/packages/gatsby-plugin-google-analytics/), and more. You can also [make your own plugins](/docs/creating-plugins/)! -Gatsby themes are a type of plugin that include a `gatsby-config.js` file and add **pre-configured** functionality, data sourcing, and/or UI code to Gatsby sites. To learn more about theme use cases and APIs, check out the [themes section of the docs](/docs/themes/). +Gatsby themes are a type of plugin that include a `gatsby-config.js` file and add **pre-configured** functionality, data sourcing, and/or UI code to Gatsby sites. To learn more about theme use cases and APIs, check out the [themes section of the docs](/docs/themes/). To learn about how plugins differ from themes and starters refer to the [Plugins, Themes, & Starters conceptual guide](/docs/plugins-themes-and-starters/). Here are the guides in the Plugins section of the docs: diff --git a/examples/using-local-plugins/README.md b/examples/using-local-plugins/README.md index 4f5cc07358ebf..35dd1495b54cd 100755 --- a/examples/using-local-plugins/README.md +++ b/examples/using-local-plugins/README.md @@ -17,3 +17,7 @@ This example uses a [local plugin](/docs/loading-plugins-from-your-local-plugins 3. Use the [`createNode` action](/docs/actions/#createNode) to add the data to Gatsby’s GraphQL layer The [`gatsby-node.js` file](./plugins/gatsby-source-pokeapi/gatsby-node.js) of the local plugin includes detailed comments on the process. + +## Examples loading multiple local plugins outside the plugins folder + +To see how to load multiple plugins from outside the plugins folder, refer to the [`using-multiple-local-plugins` example repository](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-multiple-local-plugins). diff --git a/examples/using-multiple-local-plugins/README.md b/examples/using-multiple-local-plugins/README.md new file mode 100644 index 0000000000000..596522c6b02e4 --- /dev/null +++ b/examples/using-multiple-local-plugins/README.md @@ -0,0 +1,108 @@ +# Using Gatsby with Local Plugins + +This is an example repository demonstrating different ways to load plugins in a Gatsby site. + +## Running the Example + +The actual Gatsby site to run is in the `gatsby-site-using-local-plugins` folder. + +Navigate into the `gatsby-site-using-local-plugins` project directory with this command: + +```sh +cd gatsby-site-using-local-plugins +``` + +You'll need to install dependencies for the site by running: + +```sh +npm install +``` + +Then run `gatsby develop`: + +```sh +gatsby develop +``` + +In your command line output, you should then see the text listed below. This text is showing how the code for each plugin is run sequentially thanks to the Node API implemented. + +```sh +$ gatsby develop +success open and validate gatsby-configs - 0.051s +success load plugins - 1.047s +logging to the console from plugins folder +logging to the console from a plugin in another project with require.resolve +logging to the console from site's gatsby-node +success onPreInit - 0.023s +``` + +For the config to load all the plugins you'll need to uncomment the line in the `gatsby-site-using-multiple-local-plugins/gatsby-config.js` file for `gatsby-plugin-console-log-c`: + +```javascript:title=gatsby-site-using-multiple-local-plugins/gatsby-config.js +module.exports = { + siteMetadata: { + title: `Using Multiple Local Plugins`, + description: `An example Gatsby site utilizing multiple local plugins`, + author: `@gatsbyjs`, + }, + plugins: [ + `gatsby-plugin-react-helmet`, + // including a plugin from the plugins folder + `gatsby-plugin-console-log-a`, + { + // including a plugin from outside the plugins folder needs the path to it + resolve: require.resolve(`../gatsby-plugin-console-log-b`), + }, + // including a plugin with yarn or npm link + // in order for this plugin to be found when you run gatsby develop + // you first need to run `npm link ../gatsby-plugin-console-log-c` in the `gatsby-site-using-local-plugins` root folder + `gatsby-plugin-console-log-c`, // highlight-line + ], +} +``` + +And then run: + +```sh:title=gatsby-site-using-multiple-local-plugins +npm link ../gatsby-plugin-console-log-c +``` + +When you run `gatsby develop` now, you should see the last plugin logging another line: + +```diff +$ gatsby develop + success open and validate gatsby-configs - 0.051s + success load plugins - 1.047s + logging to the console from plugins folder + logging to the console from a plugin in another project with require.resolve ++ logging to the console from a plugin in another project with npm/yarn link + logging to the console from site's gatsby-node + success onPreInit - 0.023s +``` + +## Context + +The same `gatsby-plugin-console-log` plugin is implemented 3 times (and 1 additional time in the site's `gatsby-node`), each one hooking into the `onPreInit` Gatsby Node API to log a simple message to the console when the site is run in develop or build mode. + +The code that is implemented looks similar to this: + +```javascript +exports.onPreInit = () => { + console.log("logging to the console...") +} +``` + +### 4 patterns implemented + +The 4 ways the code is run are: + +1. Inside the site's `gatsby-node.js` +2. In a plugin in the plugins folder (`gatsby-plugin-console-log-a`) +3. In a separate project folder but included with `require.resolve` in the config (`gatsby-plugin-console-log-b`) +4. In a separate project folder but included via `npm link` (`gatsby-plugin-console-log-c`) + +You can read about these methods in the [loading local plugins doc](https://www.gatsbyjs.org/docs/loading-plugins-from-your-local-plugins-folder/). + +## More advanced local plugin example + +For another example featuring a more sophisticated local plugin, you can refer to the [`using-local-plugins` example repository](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-local-plugins). diff --git a/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/gatsby-node.js b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/gatsby-node.js new file mode 100644 index 0000000000000..23c619e2af806 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/gatsby-node.js @@ -0,0 +1,3 @@ +exports.onPreInit = () => { + console.log("logging to the console from a plugin in another project with require.resolve") +} diff --git a/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/index.js b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/index.js new file mode 100644 index 0000000000000..625c0891b2c30 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/index.js @@ -0,0 +1 @@ +// noop \ No newline at end of file diff --git a/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/package.json b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/package.json new file mode 100644 index 0000000000000..3c54af6061b0d --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-b/package.json @@ -0,0 +1,7 @@ +{ + "name": "gatsby-plugin-console-log-b", + "version": "1.0.0", + "description": "Log stuff in a Gatsby site's build process", + "main": "index.js", + "license": "MIT" +} diff --git a/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/gatsby-node.js b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/gatsby-node.js new file mode 100644 index 0000000000000..0eb75ddd8f4ed --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/gatsby-node.js @@ -0,0 +1,3 @@ +exports.onPreInit = () => { + console.log("logging to the console from a plugin in another project with npm/yarn link") +} diff --git a/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/index.js b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/index.js new file mode 100644 index 0000000000000..625c0891b2c30 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/index.js @@ -0,0 +1 @@ +// noop \ No newline at end of file diff --git a/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/package.json b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/package.json new file mode 100644 index 0000000000000..e7cf080e7eb95 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-plugin-console-log-c/package.json @@ -0,0 +1,7 @@ +{ + "name": "gatsby-plugin-console-log-c", + "version": "1.0.0", + "description": "Log stuff in a Gatsby site's build process", + "main": "index.js", + "license": "MIT" +} diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.gitignore b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.gitignore new file mode 100644 index 0000000000000..f81327511eeb4 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.gitignore @@ -0,0 +1,69 @@ +# Logs +logs +*.log +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# Runtime data +pids +*.pid +*.seed +*.pid.lock + +# Directory for instrumented libs generated by jscoverage/JSCover +lib-cov + +# Coverage directory used by tools like istanbul +coverage + +# nyc test coverage +.nyc_output + +# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files) +.grunt + +# Bower dependency directory (https://bower.io/) +bower_components + +# node-waf configuration +.lock-wscript + +# Compiled binary addons (http://nodejs.org/api/addons.html) +build/Release + +# Dependency directories +node_modules/ +jspm_packages/ + +# Typescript v1 declaration files +typings/ + +# Optional npm cache directory +.npm + +# Optional eslint cache +.eslintcache + +# Optional REPL history +.node_repl_history + +# Output of 'npm pack' +*.tgz + +# dotenv environment variable files +.env* + +# gatsby files +.cache/ +public + +# Mac files +.DS_Store + +# Yarn +yarn-error.log +.pnp/ +.pnp.js +# Yarn Integrity file +.yarn-integrity diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.prettierignore b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.prettierignore new file mode 100644 index 0000000000000..58d06c368a2ae --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.prettierignore @@ -0,0 +1,4 @@ +.cache +package.json +package-lock.json +public diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.prettierrc b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.prettierrc new file mode 100644 index 0000000000000..48e90e8d4025f --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/.prettierrc @@ -0,0 +1,7 @@ +{ + "endOfLine": "lf", + "semi": false, + "singleQuote": false, + "tabWidth": 2, + "trailingComma": "es5" +} diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/LICENSE b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/LICENSE new file mode 100644 index 0000000000000..5169a5e4135e9 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/LICENSE @@ -0,0 +1,22 @@ +The MIT License (MIT) + +Copyright (c) 2015 gatsbyjs + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. + diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/README.md b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/README.md new file mode 100644 index 0000000000000..a6f1b3bc2521f --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/README.md @@ -0,0 +1,3 @@ +# Gatsby Default Starter + +This site is loading local plugins from multiple locations. diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/gatsby-config.js b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/gatsby-config.js new file mode 100644 index 0000000000000..cfb1a9a2f68ad --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/gatsby-config.js @@ -0,0 +1,20 @@ +module.exports = { + siteMetadata: { + title: `Using Multiple Local Plugins`, + description: `An example Gatsby site utilizing multiple local plugins`, + author: `@gatsbyjs`, + }, + plugins: [ + `gatsby-plugin-react-helmet`, + // including a plugin from the plugins folder + `gatsby-plugin-console-log-a`, + { + // including a plugin from outside the plugins folder needs the path to it + resolve: require.resolve(`../gatsby-plugin-console-log-b`), + }, + // including a plugin with yarn or npm link + // in order for this plugin to be found when you run gatsby develop + // you first need to run `npm link ../gatsby-plugin-console-log-c` in the `gatsby-site-using-local-plugins` root folder + // `gatsby-plugin-console-log-c`, + ], +} diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/gatsby-node.js b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/gatsby-node.js new file mode 100644 index 0000000000000..8791eee076b9c --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/gatsby-node.js @@ -0,0 +1,3 @@ +exports.onPreInit = () => { + console.log("logging to the console from site's gatsby-node") +} diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/package.json b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/package.json new file mode 100644 index 0000000000000..a11a94f477841 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/package.json @@ -0,0 +1,32 @@ +{ + "name": "using-multiple-local-plugins", + "description": "A example with the default starter loading multiple local plugins", + "version": "0.1.0", + "dependencies": { + "gatsby": "^2.18.12", + "gatsby-image": "^2.2.34", + "gatsby-plugin-manifest": "^2.2.31", + "gatsby-plugin-offline": "^3.0.27", + "gatsby-plugin-react-helmet": "^3.1.16", + "prop-types": "^15.7.2", + "react": "^16.12.0", + "react-dom": "^16.12.0", + "react-helmet": "^5.2.1" + }, + "devDependencies": { + "prettier": "^1.19.1" + }, + "keywords": [ + "gatsby" + ], + "license": "MIT", + "scripts": { + "build": "gatsby build", + "develop": "gatsby develop", + "format": "prettier --write \"**/*.{js,jsx,json,md}\"", + "start": "npm run develop", + "serve": "gatsby serve", + "clean": "gatsby clean", + "test": "echo \"Write tests! -> https://gatsby.dev/unit-testing\" && exit 1" + } +} diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/gatsby-node.js b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/gatsby-node.js new file mode 100644 index 0000000000000..37f5fd26409c0 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/gatsby-node.js @@ -0,0 +1,3 @@ +exports.onPreInit = () => { + console.log("logging to the console from plugins folder") +} diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/index.js b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/index.js new file mode 100644 index 0000000000000..172f1ae6a468c --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/index.js @@ -0,0 +1 @@ +// noop diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/package.json b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/package.json new file mode 100644 index 0000000000000..691c947967e2e --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/plugins/gatsby-plugin-console-log-a/package.json @@ -0,0 +1,7 @@ +{ + "name": "gatsby-plugin-console-log-a", + "version": "1.0.0", + "description": "Log stuff in a Gatsby site's build process", + "main": "index.js", + "license": "MIT" +} diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/header.js b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/header.js new file mode 100644 index 0000000000000..8990b7e31bb7a --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/header.js @@ -0,0 +1,42 @@ +import { Link } from "gatsby" +import PropTypes from "prop-types" +import React from "react" + +const Header = ({ siteTitle }) => ( +
+
+

+ + {siteTitle} + +

+
+
+) + +Header.propTypes = { + siteTitle: PropTypes.string, +} + +Header.defaultProps = { + siteTitle: ``, +} + +export default Header diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/layout.css b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/layout.css new file mode 100644 index 0000000000000..36670d0b75275 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/layout.css @@ -0,0 +1,83 @@ +html { + font-family: sans-serif; + -ms-text-size-adjust: 100%; + -webkit-text-size-adjust: 100%; +} +body { + margin: 0; + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} +h1 { + font-size: 2em; + margin: 0.67em 0; +} +html { + font: 112.5%/1.45em georgia, serif; + box-sizing: border-box; + overflow-y: scroll; +} +* { + box-sizing: inherit; +} +*:before { + box-sizing: inherit; +} +*:after { + box-sizing: inherit; +} +body { + color: hsla(0, 0%, 0%, 0.8); + font-family: georgia, serif; + font-weight: normal; + word-wrap: break-word; + font-kerning: normal; + -moz-font-feature-settings: "kern", "liga", "clig", "calt"; + -ms-font-feature-settings: "kern", "liga", "clig", "calt"; + -webkit-font-feature-settings: "kern", "liga", "clig", "calt"; + font-feature-settings: "kern", "liga", "clig", "calt"; +} +h1 { + margin-left: 0; + margin-right: 0; + margin-top: 0; + padding-bottom: 0; + padding-left: 0; + padding-right: 0; + padding-top: 0; + margin-bottom: 1.45rem; + color: inherit; + font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, + Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif; + font-weight: bold; + text-rendering: optimizeLegibility; + font-size: 2.25rem; + line-height: 1.1; +} +h2 { + margin-left: 0; + margin-right: 0; + margin-top: 0; + padding-bottom: 0; + padding-left: 0; + padding-right: 0; + padding-top: 0; + margin-bottom: 1.45rem; + color: inherit; + font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen, + Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif; + font-weight: bold; + text-rendering: optimizeLegibility; + font-size: 1.62671rem; + line-height: 1.1; +} +p { + margin-left: 0; + margin-right: 0; + margin-top: 0; + padding-bottom: 0; + padding-left: 0; + padding-right: 0; + padding-top: 0; + margin-bottom: 1.45rem; +} diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/layout.js b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/layout.js new file mode 100644 index 0000000000000..0359ea62913be --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/components/layout.js @@ -0,0 +1,51 @@ +/** + * Layout component that queries for data + * with Gatsby's useStaticQuery component + * + * See: https://www.gatsbyjs.org/docs/use-static-query/ + */ + +import React from "react" +import PropTypes from "prop-types" +import { useStaticQuery, graphql } from "gatsby" + +import Header from "./header" +import "./layout.css" + +const Layout = ({ children }) => { + const data = useStaticQuery(graphql` + query SiteTitleQuery { + site { + siteMetadata { + title + } + } + } + `) + + return ( + <> +
+
+
{children}
+
+ © {new Date().getFullYear()}, Built with + {` `} + Gatsby +
+
+ + ) +} + +Layout.propTypes = { + children: PropTypes.node.isRequired, +} + +export default Layout diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/pages/404.js b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/pages/404.js new file mode 100644 index 0000000000000..70bc752374a94 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/pages/404.js @@ -0,0 +1,12 @@ +import React from "react" + +import Layout from "../components/layout" + +const NotFoundPage = () => ( + +

NOT FOUND

+

You just hit a route that doesn't exist... the sadness.

+ +) + +export default NotFoundPage diff --git a/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/pages/index.js b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/pages/index.js new file mode 100644 index 0000000000000..f9bc79425ef26 --- /dev/null +++ b/examples/using-multiple-local-plugins/gatsby-site-using-local-plugins/src/pages/index.js @@ -0,0 +1,15 @@ +import React from "react" + +import Layout from "../components/layout" + +const IndexPage = () => ( + +

Hi people

+

+ This site is to demonstrate using multiple local plugins, you should see + output in the terminal showing that the plugins are being registered! +

+ +) + +export default IndexPage