fix: update image CDN docs and defaults (#307)

* chore: default image CDN to disabled

* chore: update docs

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

Author: ascorbic

README.md

@@ -80,53 +80,10 @@ Gatsby Functions or the remote image CDN.
 
 ### Gatsby Image CDN
 
-Gatsby 5 includes beta support for deferred image resizing using a CDN. This can
-greatly improve build times for sites with remote images, such as those that use
-a CMS. When using these, images do not need to be downloaded and resized at
-build time, and instead are built on the fly when first loaded. The image CDN is
-enabled by default on Netlify, but can be disabled by setting the environment
-variable `GATSBY_CLOUD_IMAGE_CDN` to `false`.
-
-When using the image CDN, Gatsby generates URLs of the form
-`/_gatsby/image/...`. On Netlify, these are served by a
-[builder function](https://docs.netlify.com/configure-builds/on-demand-builders/),
-powered by [sharp](https://sharp.pixelplumbing.com/) and Nuxt's
-[ipx image server](https://github.com/unjs/ipx/). It supports all image formats
-supported by Gatsby, including AVIF and WebP.
-
-On first load there will be a one-time delay while the image is resized, but
-subsequent requests will be super-fast as they are served from the cache.
-
-Currently Gatsby supports the image CDN for sites that use Contentful or
-WordPress, but more should be added and will be enabled automatically when
-available in the plugin.
-
-When using WordPress with the image CDN, we recommend disabling downloading of
-files if possible by setting
-[`createFileNodes`](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/docs/plugin-options.md#typemediaitemcreatefilenodes)
-to `false`. You should also setup an image size in WordPress to use as a
-placeholder. See
-[the `gatsby-source-wordpress` docs](https://github.com/gatsbyjs/gatsby/blob/master/packages/gatsby-source-wordpress/docs/plugin-options.md#typemediaitemplaceholdersizename)
-for more details.
-
-For example:
-
-```js
-module.exports = {
-  plugins: [
-    {
-      resolve: `gatsby-source-wordpress`,
-      options: {
-        url: 'https://example.com/graphql',
-        type: { MediaItem: { createFileNodes: false } },
-      },
-    },
-  ],
-}
-```
-
-For more information about Gatsby's image CDN feature, see
-[the Gatsby docs](https://gatsby.dev/img).
+Gatsby includes beta support for deferred image resizing using a CDN. Netlify
+includes full support for Image CDN on all plans. For details on how to enable
+it, see
+[the image CDN docs](https://github.com/netlify/netlify-plugin-gatsby/blob/main/docs/image-cdn.md).
 
 ### Caveats
 

docs/image-cdn.md

@@ -0,0 +1,51 @@
+# Gatsby Image CDN on Netlify
+
+Gatsby Image CDN is a new feature available in the prerelease version of Gatsby.
+Instead of downloading and processing images at build time, it defers processing
+until request time. This can greatly improve build times for sites with remote
+images, such as those that use a CMS. Netlify includes full support for Image
+CDN, on all plans.
+
+When using the image CDN, Gatsby generates URLs of the form
+`/_gatsby/image/...`. On Netlify, these are served by a
+[builder function](https://docs.netlify.com/configure-builds/on-demand-builders/),
+powered by [sharp](https://sharp.pixelplumbing.com/) and Nuxt's
+[ipx image server](https://github.com/unjs/ipx/). It supports all image formats
+supported by Gatsby, including AVIF and WebP.
+
+On first load there will be a one-time delay while the image is resized, but
+subsequent requests will be super-fast as they are served from the edge cache.
+
+## Enabling the Image CDN
+
+To enable the Image CDN during the beta period, you should set the environment
+variable `GATSBY_CLOUD_IMAGE_CDN` to `true`.
+
+Image CDN currently requires the beta version of Gatsby. This can be installed
+using the `next` tag:
+
+```shell
+npm install gatsby@next gatsby-plugin-image@next gatsby-plugin-sharp@next gatsby-transformer-sharp@next
+```
+
+Currently Image CDN supports Contentful and WordPress, and these source plugins
+should also be installed using the `next` tag:
+
+```shell
+npm install gatsby-source-wordpress@next
+```
+
+or
+
+```shell
+npm install gatsby-source-contentful@next
+```
+
+Gatsby will be adding support to more source plugins during the beta period.
+These should work automatically as soon as they are added.
+
+## Using the Image CDN
+
+Your GraphQL queries will need updating to use the image CDN. The details vary
+depending on the source plugin. For more details see
+[the Gatsby docs](https://support.gatsbyjs.com/hc/en-us/articles/4522338898579)

plugin/src/helpers/functions.ts

@@ -69,7 +69,7 @@ export const setupImageCdn = async ({
 }) => {
   const { GATSBY_CLOUD_IMAGE_CDN } = netlifyConfig.build.environment
 
-  if (GATSBY_CLOUD_IMAGE_CDN === '0' || GATSBY_CLOUD_IMAGE_CDN === 'false') {
+  if (GATSBY_CLOUD_IMAGE_CDN !== '1' && GATSBY_CLOUD_IMAGE_CDN !== 'true') {
     return
   }
 

plugin/src/index.ts

@@ -33,8 +33,6 @@ export async function onPreBuild({
   await restoreCache({ utils, publish: PUBLISH_DIR })
 
   checkGatsbyConfig({ utils, netlifyConfig })
-  // eslint-disable-next-line no-param-reassign
-  netlifyConfig.build.environment.GATSBY_CLOUD_IMAGE_CDN ||= '1'
 }
 
 export async function onBuild({