XhmikosR / netlify-plugin-gatsby

A build plugin to integrate Gatsby seamlessly with Netlify

Essential Gatsby Plugin - v2 beta

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. For older versions of Gatsby, please use version 1.x of the build plugin, which is installed automatically for new Gatsby sites.

Note:

• Essential Gatsby includes functionality from the Gatsby Cache build plugin. If you already have the Gatsby Cache plugin installed on your Netlify site, you should remove it before installing this plugin.
• Essential Gatsby is not compatible with the Gatsby community plugin gatsby-plugin-netlify-cache.

Installation and Configuration

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":

• Install version 2 beta of @netlify/plugin-gatsby (the Netlify build plugin)
• Install version 4 beta of gatsby-plugin-netlify (the Gatsby plugin)
• Configure your build to use the correct build image and Node.js runtime

Install the Netlify build plugin

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

[[plugins]]
package = "@netlify/plugin-gatsby"

2. From your project's base directory, add this plugin to devDependencies in package.json.

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

Read more about file-based plugin installation in our docs.

Install the Gatsby Plugin

To use SSR pages you must install the beta version of gatsby-plugin-netlify:

npm install -D gatsby-plugin-netlify@next

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

module.exports = {
  plugins: ['gatsby-plugin-netlify'],
}

See the gatsby-plugin-netlify docs for more information, including optional plugin configuration.

Caveats

Currently you cannot use StaticImage or gatsby-transformer-sharp in SSR or DSG pages. The best workaround is to use an image CDN such as Cloudinary or imgix 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 gatsby develop functions server. However if you want to try the Netlify functions wrapper it will run via netlify dev. You should be sure to run netlify build first, so that the wrappers are generated and the functions copied across.