Part of a series on Gatsby v2
You're familiar with Gatsby. You realise there's much awesomeness in v2. You want some of that now. You need it now.
tl;dr - Install
Why is v2 awesome? A handful of reasons. You can check out the v2 project for a good overview. A few of our personal highlights include:
You've read about why Gatsby chokes on large sites? Now's a good time. We'll wait. You can come right back via the "back" button.
Gatsby needs a list of every page on your site. Then where the data for that page can be found. It's a static file. The file name includes a cache busting hash. We need to know the filename. There's no way to guess. This list has 1 entry for every page. 100k pages means 100k entries.
In Gatsby v1 the entire list is put into the HTML of every page. That means if you have a lot of pages, your HTML files will be huge. It's a problem. It makes Gatsby v1 impractical for sites with more than ~1k pages.
This is fixed in Gatsby v2. First, the list is much, much smaller. Second, it's no longer part of the HTML. It's loaded after the page has rendered. These changes are huge. Gatsby v2 will easily support sites with 5k pages. Maybe even 50k or 100k pages.
You know that Gatsby only allows GraphQL queries in two places. In layouts and page components. Layouts are disappearing in v2. You can use GraphQL in any component instead.
This is currently a work in progress. It might change by the final release of v2.
No more layouts. So what now? Now you wrap your components in other components. You can create any kind of "layout" hierarchy you want. Awesome. How do we get data into those components? Via the new
StaticQuery? It's a new component. It's a bit like
Provider from redux. You give it a GraphQL query. It fetches that data and delivers it to your component.
How does it work? That's still not finalised. But checkout Gatsby's first RFC for more details.
The transpiled code is bigger. It includes lots of "polyfills". These are special helpers for old browsers which don't have some modern features.
That's the goal of modern builds. Give modern browsers a smaller build. Keep the bigger builds for old browsers.
Another performance optimisation from Gatsby. This is just an idea right now. It hasn't been built yet. You can read the discussion about it here.
So v2 will be awesome. You want it now. Great. But there's no migration guide yet. Darn.
Here's a short list of some of the bigger changes from v1 to v2. This list is definitely not exhaustive. v2 is constantly evolving. This list will get you started until the v2 migration guide comes out.
You're convinced. You want to try it now. Awesome.
First, do this in a branch. It might not work.
git checkout -b gatsby-v2
First, install the
react-dom. They are now peer dependencies. They must go into your
yarn add react react-dom
Great. Are you using helmet? Probably. If you are, install it. Same as above.
yarn add react-helmet
Now install Gatsby v2. It's easy.
yarn add gatsby@next
You've installed Gatsby v2. Congratulations. Unfortunately, it probably doesn't work yet. Try anyway, just for fun!
Errors? You probably need to update some other Gatsby packges. It's hard to know exactly which ones. Are you using the filesystem source plugin? Probably. Update it.
yarn add gatsby-source-filesystem@next
You might have errors at this point. Try to figure out which package they're coming from. Try upgrading that package.
Be careful. Some packages have
@nextversions which are actually old. You can check on the "Versions" tab on npm. For example gatsby-plugin-react-helmet today (11 Apr 2018). The
latesttag is version
2.0.10. While the
2.0.6-2which is 10 days older.
This process might take a little trial and error. It's worth it. Remember to make frequent git commits!
There's something new about PostCSS in v2. We haven't fully figured it out. It's not yet documented. We had success by removing the
gatsby-plugin-postcss-sass package and instead using the
yarn remove gatsby-plugin-postcss-sass yarn add gatsby-plugin-sass@next
Warning: gatsby-plugin-sass is an example of a plugin whose
@nexttag is out of date.
But most of all. Persevere. Good luck.
If you'd like to share this post, here are some handy links to make that easier.
Post last updated: April 10, 2018
Feedback? A point to make? Express yourself via the comment form below.
Don't forget to check the captcha. Otherwise we won't receive your comment.