Document ENABLE_GATSBY_REFRESH_ENDPOINT

[m-allanson]

Summary

Setting an env var ENABLE_GATSBY_REFRESH_ENDPOINT=true while running gatsby develop will configure the develop server to re-source data when it receives a POST request to /__refresh.

This is a really useful feature when working with content while developing your site. The only documentation for this at the moment lives in PR and issue comments. This information should live in the docs of gatsbyjs.org.

Basic example

Useful info available from:

• https://www.youtube.com/watch?v=8uvnAbMMVhU
• Add endpoint to refresh external data #3054 (comment)

Implementation:

gatsby/packages/gatsby/src/commands/develop.js

Lines 117 to 128 in 2f1b487

	app.post(`/__refresh`, (req, res) => {
	const enableRefresh = process.env.ENABLE_GATSBY_REFRESH_ENDPOINT
	const refreshToken = process.env.GATSBY_REFRESH_TOKEN
	const authorizedRefresh =
	!refreshToken || req.headers.authorization === refreshToken
	if (enableRefresh && authorizedRefresh) {
	console.log(`Refreshing source data`)
	sourceNodes()
	}
	res.end()
	})

Possibly in other issues / PRs in this repo.

Motivation

This feature is too useful to remain undocumented 😄

[RichardBronosky]

This ticket and https://github.com/gatsbyjs/gatsby/pull/10366/commits and https://github.com/gatsbyjs/gatsby/projects/2 are still the top Google hits. I have found https://www.gatsbyjs.org/docs/environment-variables/#reserved-environment-variables by reading the related commits. The helped me realize that the reason it seemed to not be working is that I need to POST to it rather than hit it with a browser.

[drake-smith]

I understand how this refresh token is working and have tried it out on my local machine using localhost. However, I wonder how this can be implemented into a preview system for a non-developer, like a client that needs to preview content before publishing. Especially on Contentful, to set up the POST webhook, I need a non-localhost URL. I could use ngrok, but again, that only works in a limited scope, and wouldn't be a permanent and publicly-accessible URL for others to use.

[RichardBronosky]

@drake-smith You can pass --host=0.0.0.0 to develop to get it to listen on non-local interfaces.

[Charlesdoiron]

Hi @drake-smith i really need the same online preview for my gatsby contentfull website.
Do you find something ?

thanks a lot !