A next-generation tool to create blazing-fast documentation sites
API
created:7/15/2020
,
updated:11/17/2020

Overview

component-controls allows using 3 different static site generators (SSG) to create the production version of your documentation sites.

  • gastby - in many aspects, gatsby is the original static site generator for react and continues to be a leader in this space.
  • nextjs - for many years, nextjs was known for SSR, however recent builds allow creating highly optimized static sites.
  • storybook - while storybook is not a general-purpose SSG, it comes with its own SSG engine under the hood.

In this blog post, we will research which solution offers the best development and production experience.

Examples Source Code

The documentation sites used throughout this post are essentially the same for the purpose of comparison. We would truly appreciate any feedback to additionally optimize our examples for the researched SSGs.

source code
gatsbygatsby 2+
nextjsnextjs 9+
storybookstorybook 6

Live Sites

All the sites are hosted on a free tier at netlify. The tests are conducted on the same simple documentation page.

test page
gatsbyhttps://component-controls.com
nextjshttps://nextjs.component-controls.com
storybookhttps://storybook.component-controls.com

Performance Tools

The web tests are conducted with WebPageTest and PageSpeed.

Development Mode Startup Time

Measuring the time to start up in development mode. For this test, the projects were already run once upfront, to make sure all possible caches are created.

time(s)+/-%
gatsby30s+30%
nextjs23sbest
storybook32s+39%

The times are fairly similar, with nextjs having the fastest development time startup. However, nextjs compiles individual pages on-demand so there is a sensible slowdown navigating from page to page.

Production Mode Build

Measuring the time to create a static site. Prior to launching this test, all the caches are deleted to create a level testing field.

time+/-%
gatsby7m35s+638%
nextjs1m03sbest
storybook1m04sbest

nextjs and storybook build the static site files the fastest, with gatsby much slower. To note that gatsby and nextjs create individual static pages for every document/story/page tab, while storybook creates one single bundle where all the pages are kept together under the same URL.

WebPageTest results

time
gatsbyresults
nextjsresults
storybookresults

Largest Contentful Paint

An important, user-centric metric for measuring perceived load speed because it marks the point in the page load timeline when the page's main content has likely loaded—a fast LCP helps reassure the user that the page is useful.

time+/-%
gatsby0.591s+14%
nextjs0.519sbest
storybook11.182s+2054.53%

nextjs and gatsby are very close in this test, with storybook lagging by a staggering 2000+ percent.

Total Blocking Time

An important lab metric for measuring load responsiveness because it helps quantify the severity of how non-interactive a page is before it becoming reliably interactive—a low TBT helps ensure that the page is usable.

time+/-%
gatsby1.057s+5%
nextjs1.004sbest
storybook2.448s+143%

nextjs and gatsby again are very close, with storybook over two times slower.

Document Complete Time

The time is takes to fully load all the content referenced in the HTML.

time+/-%
gatsby2.206sbest
nextjs3.012s+36%
storybook6.075s+175%

gatsby is in the lead, with nextjs almost a second slower and storybook about 3 times slower.

Document Complete Size

The size in kilobytes at the Document Complete Time.

kb+/-%
gatsby755kbbest
nextjs1,452kb+92%
storybook2,126kb+181%

gatsby generates significantly smaller bundles size, with nextjs almost twice larger and storybook about 3 times larger.

Fully Loaded Time

The time when a page completely stops loading content, including ads and below the fold elements.

time+/-%
gatsby3.209sbest
nextjs3.122sbest
storybook8.253s+164%

gatsby and nextjs have very similar times, with storybook over two times slower.

Fully Loaded Size

The size in kilobytes at the Fully Loaded Time.

kb+/-%
gatsby781kbbest
nextjs1,453kb+86%
storybook3,014kb+285%

gatsby generates significantly smaller bundles size, with nextjs almost twice larger and storybook almost 4 times larger.

Cost Of Site

Measures how much it costs for someone to use your site on mobile networks around the world. For this comparison, we will use the USA location. This measure is mostly linked to the fully loaded size.

USD+/-%
gatsby$0.05best
nextjs$0.09+80%
storybook$0.19+280%

gatsby sites are the cheapest to use, with nextjs twice more expensive and storybook almost 4 times more expensive.

PageSpeed Mobile Speed Score

The speed score is based on the lab data analyzed by Lighthouse. The results of this test vary to some extent on each run.

resultsscore+/-%
gatsbyresults29-29%
nextjsresults41best
storybookresults5-87%

nextjs sites get the best mobile speed score, with gatsby underperforming and the storybook score is close to zero.

PageSpeed Desktop Speed Score

The speed score is based on the lab data analyzed by Lighthouse. The results of this test vary to some extent on each run.

resultsscore+/-%
gatsbyresults75-7%
nextjsresults81best
storybookresults57-29%

nextjs sites get the best desktop speed score, with gatsby very close and the storybook score significantly lower..

Recap

  • build time gatsby is significantly slower, however this process is usually performed on a CI server.
  • blocking time gatsby and nextjs sites have very similar times, with storybook over twice slower.
  • bundle sizes gatsby shines here, and while it is expected that storybook creates 3 times larger bundles than gatsby since it generates one bundle for all pages, it is strange that the bundles from nextjs are twice as large as the gatsby bundles.
  • loading time nextjs and gatsby are very similar, with storybook sites performing about 3 times slower.
  • cost to use gatsby outperforms the other SSGs, with nextjs sites almost twice more expensive and storybook 4 times more expensive.
  • google pagespeed nextjs has slightly better pagespeed scores than gatsby, with storybook sites significantly underperforming.

Conclusion

gatsby and nextjs generate fast and highly optimized documentation sites, with nextjs doing slightly better on the blocking time measurement but significantly worse on the bundle size. The storybook SSG engine does not stack up favorably and generates significantly slower and bulkier sites.