Skip to content

Commit 26ac30a

Browse files
7sferry7sferry
committed
0 parents  commit 26ac30a

9 files changed

+252
-0
lines changed

‎.gitignore

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
8+
# Runtime data
9+
pids
10+
*.pid
11+
*.seed
12+
*.pid.lock
13+
14+
# Directory for instrumented libs generated by jscoverage/JSCover
15+
lib-cov
16+
17+
# Coverage directory used by tools like istanbul
18+
coverage
19+
20+
# nyc test coverage
21+
.nyc_output
22+
23+
# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
24+
.grunt
25+
26+
# Bower dependency directory (https://bower.io/)
27+
bower_components
28+
29+
# node-waf configuration
30+
.lock-wscript
31+
32+
# Compiled binary addons (http://nodejs.org/api/addons.html)
33+
build/Release
34+
35+
# Dependency directories
36+
node_modules/
37+
jspm_packages/
38+
39+
# Typescript v1 declaration files
40+
typings/
41+
42+
# Optional npm cache directory
43+
.npm
44+
45+
# Optional eslint cache
46+
.eslintcache
47+
48+
# Optional REPL history
49+
.node_repl_history
50+
51+
# Output of 'npm pack'
52+
*.tgz
53+
54+
# dotenv environment variable files
55+
.env*
56+
57+
# gatsby files
58+
.cache/
59+
public
60+
61+
# Mac files
62+
.DS_Store
63+
64+
# Yarn
65+
yarn-error.log
66+
.pnp/
67+
.pnp.js
68+
# Yarn Integrity file
69+
.yarn-integrity

‎LICENSE

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
The BSD Zero Clause License (0BSD)
2+
3+
Copyright (c) 2020 Gatsby Inc.
4+
5+
Permission to use, copy, modify, and/or distribute this software for any
6+
purpose with or without fee is hereby granted.
7+
8+
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
9+
REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
10+
AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
11+
INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
12+
LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
13+
OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
14+
PERFORMANCE OF THIS SOFTWARE.

‎README.md

+113
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
<p align="center">
2+
<a href="https://www.gatsbyjs.com">
3+
<img alt="Gatsby" src="https://www.gatsbyjs.com/Gatsby-Monogram.svg" width="60" />
4+
</a>
5+
</p>
6+
<h1 align="center">
7+
Starter for a Gatsby Plugin
8+
</h1>
9+
10+
A minimal boilerplate for the essential files Gatsby looks for in a plugin.
11+
12+
## 🚀 Quick start
13+
14+
To get started creating a new plugin, you can follow these steps:
15+
16+
1. Initialize a new plugin from the starter with `gatsby new`
17+
18+
```shell
19+
gatsby new my-plugin https://github.com/gatsbyjs/gatsby-starter-plugin
20+
```
21+
22+
If you already have a Gatsby site, you can use it. Otherwise, you can [create a new Gatsby site](https://www.gatsbyjs.com/docs/tutorial/getting-started/part-0/#create-a-gatsby-site) to test your plugin.
23+
24+
Your directory structure will look similar to this:
25+
26+
```text
27+
/my-gatsby-site
28+
├── gatsby-config.js
29+
└── /src
30+
└── /pages
31+
└── /index.js
32+
/my-plugin
33+
├── gatsby-browser.js
34+
├── gatsby-node.js
35+
├── gatsby-ssr.js
36+
├── index.js
37+
├── package.json
38+
└── README.md
39+
```
40+
41+
With `my-gatsby-site` being your Gatsby site, and `my-plugin` being your plugin. You could also include the plugin in your [site's `plugins` folder](https://www.gatsbyjs.com/docs/loading-plugins-from-your-local-plugins-folder/).
42+
43+
2. Include the plugin in a Gatsby site
44+
45+
Inside of the `gatsby-config.js` file of your site (in this case, `my-gatsby-site`), include the plugin in the `plugins` array:
46+
47+
```javascript
48+
module.exports = {
49+
plugins: [
50+
// other gatsby plugins
51+
// ...
52+
require.resolve(`../my-plugin`),
53+
],
54+
}
55+
```
56+
57+
The line `require.resolve('../my-plugin')` is what accesses the plugin based on its filepath on your computer, and adds it as a plugin when Gatsby runs.
58+
59+
_You can use this method to test and develop your plugin before you publish it to a package registry like npm. Once published, you would instead install it and [add the plugin name to the array](https://www.gatsbyjs.com/docs/using-a-plugin-in-your-site/). You can read about other ways to connect your plugin to your site including using `npm link` or `yarn workspaces` in the [doc on creating local plugins](https://www.gatsbyjs.com/docs/creating-a-local-plugin/#developing-a-local-plugin-that-is-outside-your-project)._
60+
61+
3. Verify the plugin was added correctly
62+
63+
The plugin added by the starter implements a single Gatsby API in the `gatsby-node` that logs a message to the console. When you run `gatsby develop` or `gatsby build` in the site that implements your plugin, you should see this message.
64+
65+
You can verify your plugin was added to your site correctly by running `gatsby develop` for the site.
66+
67+
You should now see a message logged to the console in the preinit phase of the Gatsby build process:
68+
69+
```shell
70+
$ gatsby develop
71+
success open and validate gatsby-configs - 0.033s
72+
success load plugins - 0.074s
73+
Loaded gatsby-starter-plugin
74+
success onPreInit - 0.016s
75+
...
76+
```
77+
78+
4. Rename the plugin in the `package.json`
79+
80+
When you clone the site, the information in the `package.json` will need to be updated. Name your plugin based off of [Gatsby's conventions for naming plugins](https://www.gatsbyjs.com/docs/naming-a-plugin/).
81+
82+
## 🧐 What's inside?
83+
84+
This starter generates the [files Gatsby looks for in plugins](https://www.gatsbyjs.com/docs/files-gatsby-looks-for-in-a-plugin/).
85+
86+
```text
87+
/my-plugin
88+
├── .gitignore
89+
├── gatsby-browser.js
90+
├── gatsby-node.js
91+
├── gatsby-ssr.js
92+
├── index.js
93+
├── LICENSE
94+
├── package.json
95+
└── README.md
96+
```
97+
98+
- **`.gitignore`**: This file tells git which files it should not track / not maintain a version history for.
99+
- **`gatsby-browser.js`**: This file is where Gatsby expects to find any usage of the [Gatsby browser APIs](https://www.gatsbyjs.com/docs/browser-apis/) (if any). These allow customization/extension of default Gatsby settings affecting the browser.
100+
- **`gatsby-node.js`**: This file is where Gatsby expects to find any usage of the [Gatsby Node APIs](https://www.gatsbyjs.com/docs/node-apis/) (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.
101+
- **`gatsby-ssr.js`**: This file is where Gatsby expects to find any usage of the [Gatsby server-side rendering APIs](https://www.gatsbyjs.com/docs/ssr-apis/) (if any). These allow customization of default Gatsby settings affecting server-side rendering.
102+
- **`index.js`**: A file that will be loaded by default when the plugin is [required by another application](https://docs.npmjs.com/creating-node-js-modules#create-the-file-that-will-be-loaded-when-your-module-is-required-by-another-application0). You can adjust what file is used by updating the `main` field of the `package.json`.
103+
- **`LICENSE`**: This plugin starter is licensed under the 0BSD license. This means that you can see this file as a placeholder and replace it with your own license.
104+
- **`package.json`**: A manifest file for Node.js projects, which includes things like metadata (the plugin's name, author, etc). This manifest is how npm knows which packages to install for your project.
105+
- **`README.md`**: A text file containing useful reference information about your plugin.
106+
107+
## 🎓 Learning Gatsby
108+
109+
If you're looking for more guidance on plugins, how they work, or what their role is in the Gatsby ecosystem, check out some of these resources:
110+
111+
- The [Creating Plugins](https://www.gatsbyjs.com/docs/creating-plugins/) section of the docs has information on authoring and maintaining plugins yourself.
112+
- The conceptual guide on [Plugins, Themes, and Starters](https://www.gatsbyjs.com/docs/plugins-themes-and-starters/) compares and contrasts plugins with other pieces of the Gatsby ecosystem. It can also help you [decide what to choose between a plugin, starter, or theme](https://www.gatsbyjs.com/docs/plugins-themes-and-starters/#deciding-which-to-use).
113+
- The [Gatsby plugin library](https://www.gatsbyjs.com/plugins/) has over 1750 official as well as community developed plugins that can get you up and running faster and borrow ideas from.

‎gatsby-browser.js

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
/**
2+
* Implement Gatsby's Browser APIs in this file.
3+
*
4+
* See: https://www.gatsbyjs.com/docs/browser-apis/
5+
*/
6+
// You can delete this file if you're not using it

‎gatsby-node.js

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
/**
2+
* Implement Gatsby's Node APIs in this file.
3+
*
4+
* See: https://www.gatsbyjs.com/docs/node-apis/
5+
*/
6+
// You can delete this file if you're not using it
7+
8+
/**
9+
* You can uncomment the following line to verify that
10+
* your plugin is being loaded in your site.
11+
*
12+
* See: https://www.gatsbyjs.com/docs/creating-a-local-plugin/#developing-a-local-plugin-that-is-outside-your-project
13+
*/
14+
exports.onPreInit = () => console.log("Loaded gatsby-starter-plugin")

‎gatsby-ssr.js

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
/**
2+
* Implement Gatsby's SSR (Server Side Rendering) APIs in this file.
3+
*
4+
* See: https://www.gatsbyjs.com/docs/ssr-apis/
5+
*/
6+
// You can delete this file if you're not using it

‎index.js

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
// noop

‎package-lock.json

+13
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
{
2+
"name": "gatsby-starter-plugin",
3+
"version": "1.0.0",
4+
"description": "A minimal boilerplate for the essential files Gatsby looks for in a plugin",
5+
"main": "index.js",
6+
"scripts": {
7+
"test": "echo \"Error: no test specified\" && exit 1",
8+
"build": "echo \"No build script setup\""
9+
},
10+
"keywords": [
11+
"gatsby",
12+
"gatsby-plugin"
13+
],
14+
"author": "Kyle Gill <[email protected]>",
15+
"license": "0BSD"
16+
}

0 commit comments

Comments
 (0)