Skip to content

chore: update readme for GA #239

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jan 26, 2022
Merged

chore: update readme for GA #239

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9381791
chore: update readme for GA
ascorbic Jan 25, 2022
6d345af
Apply suggestions from code review
ascorbic Jan 26, 2022
042bcf2
Merge branch 'main' into mk/ga-readme
kodiakhq[bot] Jan 26, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 25 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,13 +1,10 @@
![Netlify Build plugin Gatsby – Run Gatsby seamlessly on Netlify](netlify-gatsby-plugin.png)

# Essential Gatsby Plugin - v2 beta
# Essential Gatsby Plugin - v2

This version of the Essential Gatsby build plugin is a beta release, supporting
the new features of Gatsby 4 including the SSR and DSG
[render modes](https://v4.gatsbyjs.com/docs/conceptual/rendering-options/). For
older versions of Gatsby, please use
[version 1.x of the build plugin](https://github.com/netlify/netlify-plugin-gatsby/tree/v1),
which is installed automatically for new Gatsby sites.
The Essential Gatsby build plugin enables caching of builds, SSR and DSG
[render modes](https://v4.gatsbyjs.com/docs/conceptual/rendering-options/) and
Gatsby Functions. It is installed automatically for all new Gatsby sites.

> **Note:**
>
Expand All @@ -20,58 +17,40 @@ which is installed automatically for new Gatsby sites.
> - Essential Gatsby is not compatible with the Gatsby community plugin
> [gatsby-plugin-netlify-cache](https://www.gatsbyjs.com/plugins/gatsby-plugin-netlify-cache/).

## Installation and Configuration
## Installation

<!-- All sites deployed to Netlify with Gatsby will automatically install this plugin
for a seamless experience.
Gatsby sites need two plugins to support all features.

This means that you don't have to do anything — just build and deploy your site
to Netlify as usual and we'll handle the rest.
1. The Netlify build plugin, called "Essential Gatsby" or
`@netlify/plugin-gatsby`. This is installed automatically for all Gatsby
sites deployed to Netlify.
2. The Gatsby plugin `gatsby-plugin-netlify`. This needs to be manually
installed.

You're able to
[remove the plugin](https://docs.netlify.com/configure-builds/build-plugins/#remove-a-plugin)
at any time by visiting the **Plugins** tab for your site in the Netlify UI. -->
### Installing the Netlify build plugin
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[sand] This header uses "Installing" while the following header (line 43) uses "Install". They should use the same verb form. I advocate using "installing" for both, but you could make an argument either way.


There are three steps to enable support for Gatsby 4 in your Netlify site. This
includes installing _two_ plugins: a Netlify build plugin called "Essential
Gatsby Plugin", and a Gatsby plugin called "gatsby-plugin-netlify":
New Gatsby sites on Netlify automatically install the Essential Gatsby build plugin. You can confirm this in the build logs. If you need to install it
manually, you have two options:

- [Install version 2 beta of `@netlify/plugin-gatsby`](#install-the-netlify-build-plugin)
(the Netlify build plugin)
- [Install version 4 beta of `gatsby-plugin-netlify`](#install-the-gatsby-plugin)
(the Gatsby plugin)
- [The Netlify UI](https://docs.netlify.com/configure-builds/build-plugins/#ui-installation). Here, you can search for "Essential Gatsby" and install the plugin.

### Install the Netlify build plugin
- [File-based plugin installation](https://docs.netlify.com/configure-builds/build-plugins/#file-based-installation). You can install the plugin as `@netlify/plugin-gatsby` in your `netlify.toml` file.


1. Create a `netlify.toml` in the root of your project. Your file should include
the plugins section below:
### Install the Gatsby Plugin

```toml
[[plugins]]
package = "@netlify/plugin-gatsby"
```
You should also install the Gatsby plugin
[gatsby-plugin-netlify](https://www.gatsbyjs.org/plugins/gatsby-plugin-netlify/).
This is required for SSR pages, and adds support for Gatsby redirects and asset
caching rules:

2. From your project's base directory, add this plugin to `devDependencies` in
`package.json`.
1. Add the package as a dependency:

```shell
npm install -D @netlify/plugin-gatsby@^2.0.0-beta
npm install -D gatsby-plugin-netlify
```

Read more about
[file-based plugin installation](https://docs.netlify.com/configure-builds/build-plugins/#file-based-installation)
in our docs.

## Install the Gatsby Plugin

To use SSR pages you must install the beta version of
[gatsby-plugin-netlify](https://www.gatsbyjs.org/plugins/gatsby-plugin-netlify/):

```shell
npm install -D gatsby-plugin-netlify@next
```

Then add the following to your `gatsby-config.js` file:
2. Then add the following to your `gatsby-config.js` file:

```js
module.exports = {
Expand Down Expand Up @@ -103,10 +82,6 @@ DSG pages. The best workaround is to use an image CDN such as
or [imgix](https://github.com/imgix/gatsby) to host your images. This will give
you faster builds and rendering too.

### Beta feedback

TODO: forums link

### Local development

When developing Gatsby Functions it is usually easier to use the built-in
Expand Down