gatsbyjs / gatsby

The best React-based framework with performance, scalability and security built in.

Gatsby

The future of web development is here.

Gatsby is a free and open source framework based on React that helps developers build blazing fast websites and apps.
It combines the control and scalability of dynamically rendered sites with the speed of static-site generation, creating a whole new web of possibilities.

Quickstart · Tutorial · Plugins · Starters · Showcase · Contribute
Support: Twitter, Discussions & Discord

Gatsby helps professional developers efficiently create maintainable, highly-performant, content-rich websites.

• Load Data From Anywhere. Gatsby pulls in data from any data source, whether it’s Markdown files, a headless CMS like Contentful or WordPress, or a REST or GraphQL API. Use source plugins to load your data, then develop using Gatsby’s uniform GraphQL interface.

• Go Beyond Static Websites. Get all the benefits of static websites with none of the limitations. Gatsby sites are fully functional React apps, so you can create high-quality, dynamic web apps, from blogs to e-commerce sites to user dashboards.

• Choose your Rendering Options. You can choose alternative rendering options, namely Deferred Static Generation (DSG) and Server-Side Rendering (SSR), in addition to Static Site Generation (SSG) — on a per-page basis. This type of granular control allows you to optimize for performance and productivity without sacrificing one for the other.

• Performance Is Baked In. Ace your performance audits by default. Gatsby automates code splitting, image optimization, inlining critical styles, lazy-loading, prefetching resources, and more to ensure your site is fast — no manual tuning required.

• Use a Modern Stack for Every Site. No matter where the data comes from, Gatsby sites are built using React and GraphQL. Build a uniform workflow for you and your team, regardless of whether the data is coming from the same backend.

• Host at Scale for Pennies. Gatsby sites don’t require servers, so you can host your entire site on a CDN for a fraction of the cost of a server-rendered site. Many Gatsby sites can be hosted entirely free on Gatsby Cloud and other similar services.

• Use Gatsby's Centralized Data Layer Everywhere. With Gatsby's Valhalla Content Hub you can bring Gatsby's data layer to any project. Making it accessible via a unified GraphQL API for building content sites, eCommerce platforms, and both native and web applications.

Learn how to use Gatsby for your next project.

🚀 Ship your first Gatsby site in 5 Minutes

Click the link below to quickly try the workflow of developing, building, and deploying websites with Gatsby and Gatsby Cloud.

At the end of this process, you'll have

1. a site working on Gatsby Cloud
2. a new repository that is linked to that new site
3. as you push changes to your new repository, Gatsby Cloud will automatically rebuild and redeploy your site!

💻 Get started with Gatsby locally in 5 Minutes

You can get a new Gatsby site up and running on your local dev environment in 5 minutes with these four steps:

1. Initialize a new project.

   npm init gatsby

   Give it the name "My Gatsby Site".

2. Start the site in develop mode.

   Next, move into your new site’s directory and start it up:

   cd my-gatsby-site/
   npm run develop

3. Open the source code and start editing!

   Your site is now running at http://localhost:8000. Open the my-gatsby-site directory in your code editor of choice and edit src/pages/index.js. Save your changes, and the browser will update in real time!

At this point, you’ve got a fully functional Gatsby website. For additional information on how you can customize your Gatsby site, see our plugins and the official tutorial.

🎓 Learning Gatsby

Full documentation for Gatsby lives on the website.

• For most developers, we recommend starting with our in-depth tutorial for creating a site with Gatsby. It starts with zero assumptions about your level of ability and walks through every step of the process.

• To dive straight into code samples head to our documentation. In particular, check out the “How-to Guides”, “Reference”, and “Conceptual Guides” sections in the sidebar.

We welcome suggestions for improving our docs. See the “how to contribute” documentation for more details.

Start Learning Gatsby: Follow the Tutorial · Read the Docs

🚢 Release Notes

Wondering what we've shipped recently? Check out our release notes for key highlights, performance improvements, new features, and notable bugfixes.

Also, read our documentation on version support to understand our plans for each version of Gatsby.

💼 Migration Guides

Already have a Gatsby site? These handy guides will help you add the improvements of Gatsby v5 to your site without starting from scratch!

• Migrate from v4 to v5
• Migrate from v3 to v4
• Migrate from v2 to v3

❗ Code of Conduct

Gatsby is dedicated to building a welcoming, diverse, safe community. We expect everyone participating in the Gatsby community to abide by our Code of Conduct. Please read it. Please follow it. In the Gatsby community, we work hard to build each other up and create amazing things together. 💪💜

🤝 How to Contribute

Whether you're helping us fix bugs, improve the docs, or spread the word, we'd love to have you as part of the Gatsby community!

Check out our Contributing Guide for ideas on contributing and setup steps for getting our repositories up and running on your local machine.

A note on how this repository is organized

This repository is a monorepo managed using Lerna. This means there are multiple packages managed in this codebase, even though we publish them to NPM as separate packages.

📝 License

Licensed under the MIT License.

💜 Thanks

Thanks go out to all our many contributors creating plugins, starters, videos, and blog posts. And a special appreciation for our community members helping with issues and PRs, or answering questions on Discord and GitHub Discussions.

A big part of what makes Gatsby great is each and every one of you in the community. Your contributions enrich the Gatsby experience and make it better every day.

gatsby's Issues

Change command from "watch" to "serve"

As Hexo does.

Doesn't work when installed with npm 3.x

File webpack.config.coffee assumes too much about how npm layouts modules when installing them. npm 3.x is radically different than npm 2.x in this regard and so gatsby doesn't work.

Suggestion is to use require.resolve instead of relying on ../../node_modules paths (webpack-dev-server entry points). resolveLoader.modulesDirectories also needs a tweak.

Using other webpack loaders

I'm trying to use stylus and just prepend the loader when requiring the file since there's no way to alter the webpack config:

require('!css!stylus!./css/main.styl')

but it appears gatsby only searches its own node_modules rather than node_modules of the project itself. Any way around this?

This also brings up a good question about implementing a way to extend the webpack config with other plugins and things.

Upgrade dependencies

#45 (comment) /cc @ChristopherBiscardi

FEATURE: Code splitting by route

Once we upgrade to ReactRouter 1.0, leverage Webpack's code splitting to dynamically load sections of large sites e.g. docs/* or blog/*

http://webpack.github.io/docs/code-splitting.html
remix-run/react-router#755

Cannot find module "wrappers/md"

Steps to reproduce:

npm install -g [email protected]
gatsby new gatsby-test
cd gatsby-test
gatsby build

Generating static html pages
failed at generating static html pages
{ [Error: Cannot find module "wrappers/md"] code: 'MODULE_NOT_FOUND' }

TASK: Update demo sites to latest version and use link helper function

Exit code when module is not found is wrong

$ gatsby build

Generating static html pages
failed at generating static html pages
{ [Error: Cannot find module "components/page-layout"] code: 'MODULE_NOT_FOUND' }

$ echo $?

0

This should return something other than zero.

Figure out ways to share code with Antwar?

Just a quick FYI, we've been working on a similar tool known as Antwar for a few months. Interestingly there's a huge amount of overlap in terms of functionality and goals.

Perhaps we could find some way to collaborate or share code even? That might be beneficial to both projects.

Break loaders/wrappers into plugins

There are potentially dozens of different file types people would want to use with Gatsby + many different ways to prepare Markdown and other file formats. To simplify (code + conceptually) adding or modifying how files are loaded/wrapped, we should create a plugin architecture + break out existing markdown/html loaders/wrappers into plugins that are installed separately from Gatsby core.

for site config + code overrides, use gatsby.config.js

Build crashes for directories with only images

If there is a folder in pages that includes only images (no jsx/md/html pages), the build crashes with an error Cannot read property 'path' of undefined:

> mkdir pages/images
> touch pages/images/foo.jpg
> gatsby build
Generating static html pages
Compiling production bundle.js
Copying assets
/Users/ville/Projects/gatsby/lib/utils/post-build.coffee:37
        newPath = parsePath(page.path).dirname + parsed.basename;
                                ^

TypeError: Cannot read property 'path' of undefined
  at copy (/Users/ville/Projects/gatsby/lib/utils/post-build.coffee:31:16)
  at /Users/ville/Projects/gatsby/node_modules/async/lib/async.js:358:13
  at /Users/ville/Projects/gatsby/node_modules/async/lib/async.js:239:13

Page indexes

Frequently when creating a site you'll want to reference pages elsewhere e.g. on index pages or menu sections.

To simplify this, it'd be nice if you could create ad-hoc page indexes something like:

const blogIndex = createIndex('/blog/*.md', {sort: (page) => page.meta.date})

// Now on an index page.
latestBlogPosts = blogIndex({first: 10})

// Render links...

"Composable" sites

As brought up in this discussion

Woah. Just had an idea. What do you think about the idea of "composable" websites? Gatsby is already doing this to some extent as it has fallbacks for most critical files you need but you can override them easily but we could extend that concept further to something like Object.assign(Gatsby, website_base, actual_website).

So in practice how this would work is there'd be a base documentation site hosted on github. When you want a new docs site you'd just set the github url for the base site and then start adding markdown files. Anything else you'd want to modify could be set in the site config file.

Error: Cannot find module '../lib/utils/init-starter' on second step of tutorial

Very excited by this, thanks for providing it!

Hit a problem when following the tutorial, to reproduce:

$ npm i -g gatsby
$ gatsby new docs-site gh:gatsbyjs/gatsby-starter-documentation

// gives the following stack trace:

Error: Cannot find module '../lib/utils/init-starter'
  at Function.Module._resolveFilename (module.js:338:15)
  at Function.Module._load (module.js:280:25)
  at Module.require (module.js:364:17)
  at require (module.js:380:17)
  at Object.<anonymous> (/usr/local/n/versions/0.10.25/lib/node_modules/gatsby/bin/new.coffee:2:15)
  at Object.<anonymous> (/usr/local/n/versions/0.10.25/lib/node_modules/gatsby/bin/new.coffee:1:1)
  at Module._compile (module.js:456:26)
  at Object.loadFile (/usr/local/n/versions/0.10.25/lib/node_modules/gatsby/node_modules/coffee-script/lib/coffee-script/register.js:16:19)
  at Module.load (/usr/local/n/versions/0.10.25/lib/node_modules/gatsby/node_modules/coffee-script/lib/coffee-script/register.js:45:36)
  at Function.Module._load (module.js:312:12)
  at Module.require (module.js:364:17)
  at require (module.js:380:17)
  at Object.<anonymous> (/usr/local/n/versions/0.10.25/lib/node_modules/gatsby/bin/gatsby-new.js:4:1)
  at Module._compile (module.js:456:26)
  at Object.Module._extensions..js (module.js:474:10)
  at Module.load (module.js:356:32)
  at Function.Module._load (module.js:312:12)
  at Function.Module.runMain (module.js:497:10)
  at startup (node.js:119:16)
  at node.js:906:3

Any tips to debug / fix ?

Braindump of ideas

Here's a quick braindump of directions I've been thinking.

• Configuration/Convention driven but easily overridable with code. What this means in practice is that there'd be a command line tool with commands to create/watch/build sites. Most sites wouldn't need anything special for configuration so there'd be a common webpack etc configurations bundled with the cli tool that would set up hot reloading while developing and uglified builds for production.
• RSS/Atom support — necessary for anything blog like
• no reload page transitions. This would be amazing and pretty easy to do with React Router. The initial html page would load followed quickly by a js bundle with the content for the rest of the site. Atlassian's Git tutorial site does this and it feels amazing (built with React/React-Router as well) https://www.atlassian.com/git. CircleCi almost gets this right but they load content for each page individually which delay causes noticable layout jerk https://circleci.com/docs/getting-started
• smart code splitting. E.g. autostart splitting if bundle gets larger than 750kb. A fun research project would be to investigate how to use internal link structure to generate ideal bundles e.g. for each page, bundle together all content within 2 clicks of page. We'd handle loading additional bundles automatically.
• themes that are installable separately. E.g. for blogs/doc sites, etc. This would leverage react router by wrapping page content inside it. So a blog theme would provide a header, navigation, background colors/images/etc and put the child blog post inside it.
• Support Markdown/Asciidoctor/other writing formats
• rehabilitate https://github.com/andreypopp/reactdown and give it 1st class support
• each page can have its own package.json. Useful for marketing sites where one or two pages might have lots of extra stuff or blog posts where you want to drop live demos in. Basically each page can act as its own app if it wants to.
• no configuration routing. Just use the directory structure of posts (posts/a-long-voyage-across-the-southern-seas/index.md) to auto-generate the react-router configuration.
• A docker image that autobuilds/server site. My startup uses Docker containers for running microservices so the ideal setup for me would be to develop locally and then push the src which would get added to a Docker image, built there, and get served by Nginx.
• plugins support e.g. simple client-side search for a blog. Extract text from markdown and make searchable with http://lunrjs.com/
• built-in support for my typography tool. There could be a number of builtin typography "themes". This also speeds initial load time as all css would be inlined meaning initial page is loaded with one request.
• hot reloading built-in while writing/developing

There's a lot of static site generators out there and I've played with several and written my own for my blog. They're all pretty much the same and not particularly interesting. I think a React.js based SSG can push the state of the art in three ways — easy no-page transitions, react.js style components, and leveraging the growing react.js ecosystem of tools and components.

Most stuff on the web are sites not apps. And react.js components as just as powerful for sites as they are apps so a kickass tool for building react.js sites would be very valuable.

Detect if in Gatsby directory and exit if not

It'd be interesting though if not in a Gatsby directory to auto-scan above and below the current working directory for Gatsby sites (glob for a gatsby.config.* file?) This is potentially problematic as could lead to opening 1000s of files. Not sure if node-glob can limit how many directories you look into.

There's also finding modules like https://www.npmjs.com/package/find which might be a better choice. Have to investigate cross-platform compatibility.

Hot reloading only works locally

On remote servers you can set the host but this breaks serving the JS and other assets atm.

Validate first thing that a directory has necessary files to build site

Cannot import CSS into html component when serving site as Node.js doesn't understand Webpack module types

First, I apologize if this is due to my own ignorance and not knowing enough about how webpack works, but I cannot seem to load any css files.

In html.jsx I have:

import './css/style.css';

Whenever I run gatsby serve, I get an "Illegal token error" on the css file. I've also seen "Unexpected reserved word" errors where javascript reserved words are used in the CSS (like @import). It doesn't appear that it is recognizing it as a css file, but the webpack loaders look good and I've seen the same thing done in gatsby examples.

Am I missing something obvious here?

FEATURE: Encourage caching by giving each build of bundle.js a unique name

Currently someone can visit a new page and if they've cached the old bundle.js in their browser, after loading that, the new page will go blank as the old bundle.js doesn't know yet about it.

Copy "brunch new" command to install starter sites from github

Set patterns for page files to declare metadata

Markdown has standardized on frontmatter. Don't want to force frontmatter on other file types e.g. JSX.

My proposal for the post-build is that we create a special metadata gathering webpack entry file that pulls in all pages and grabs their metadata. Each loader would need to return a metadata key.

Upgrade to React 0.14 and React Router 1.0

If someone wants to grab this, this would be an easy first PR.

Gatsby should be able to serve/build a standalone file

Which means Gatsby should have defaults for all other necessary files.

FEATURE: Add way to automatically resize/optimize photos

When copying assets to the public folder, optimize images.

Add way to ignore file during build

Perhaps just look for metadata like ignore: true?

E.g. from a markdown file's frontmatter?

Gatsby Docker Image

A docker image that autobuilds and serves site. Leverages ONBUILD to build Gatsby site from src on building Docker image. Would include preconfigured Nginx + Gatsby ONBUILD instruction.

Browsable/searchable list of starters

The Gatsby website should have a list of starters.

This would be derived from a YAML file within this repo.

People can create a PR to add their starter.

There should be tests which:

1. validate that each site has necessary fields e.g. title, description, url to demo site, url to valid github repo, screenshot, authors w/ emails, other metadata (e.g. tags, added date, tech uesd (Sass/less/etc), stars, etc.)
2. validate that starter can be installed and built without errors.

These two tests will ensure the quality of starters remain high without a lot of manual intervention.

Perhaps when a starter test fails, auto email the author?

Setup http://greenkeeper.io/ for each community starter?

Perhaps run install + build tests weekly and then generate a screenshot from that? On a failure, create a PR on their repo to update. If they don't fix by the following week, comment them out of the community listing until they've fixed themselves. If they fix their starter before the following week, they can manually create a PR against Gatsby to re-add themselves.

Trim package.json

There's a number of dependencies from when the examples/starters were in this repo. They're fattening the install unnecessarily.

non-index pages are created as name-of-file.html/index.html

Use tree instead of flat structure for files internally and in theming?

This might simplify some things + make code more efficient as it doesn't have to scan all files in order to find some subset of files (e.g. all files owned by a template).

Broccoli would be a source of inspiration / potentially code if we move this direction.

Sass support?

Hello, I know how to support sass files using webpack, but I am little confused if/how that is supported in gatsbyjs as webpack config seems buried in source of gatsby.

Thanks in advance for help.

Add option to CLI for verbose/noisy vs. quiet output. Default to quiet

Google analytics

Need to be able to fire off page views to google analytics.

Remove backticks

Not supported on older versions of node.

Make builds deterministic

Right now every time you build, every html file is changed due to the React ids changing. Is this avoidable somehow? It'd be nice if the only changed files in the public directory where files that had actually changed in src.

Add deploy-gh-pages command which builds site and publishes to Github Pages

UPDATE: We'll be using https://www.npmjs.com/package/gh-pages

Support for pagination and categories/tags

I haven't dig much about it, does gatsby have built in support for pagination and categories/tags?
i.e.
http://blog.ghost.org/page/2/
http://blog.ghost.org/tag/writing/

That would sum up in two special routes that accept a wildcard * after the main path.
/page/*/
/tag/*/

While playing with gatsy I also found beneficial to leave the main route "themable", I mean
/page/_template.jsx
/tag/_template.jsx
As it would work for WordPress (use the custom page if found, or pick the default one).

Another different scenario is the 404 page that should be supported by React Router.

SyntaxError: Unexpected reserved word

Just installed a fresh copy of gatsby, and created a blog. When I try to run gatsby serve I get this error:

/usr/local/lib/node_modules/gatsby/lib/utils/serve.js:2
import Hapi from 'hapi';
^^^^^^
SyntaxError: Unexpected reserved word

Seems like babel isn't running for some reason. Any clues?

Should support Surge (and other publish plugins)

Via #6. Should have the ability to add Surge as an option for deployment.

Right now, surge token will give you a token (example) you could use in your config as mentioned in the other issue, but you wouldn’t want it committed to repo, so not sure that’s the best approach. For Surge at least, account creation is implicit, if you aren’t logged in already you will be prompted, so that isn’t necessarily an issue.

Migrate hot-loader to react-transform's family of modules

https://github.com/gaearon/react-transform-boilerplate

Investigate why webpack isn't seeing loaders not written in plain JS

webpack/webpack#1103 (comment)

Replace "gatsby serve" with "gatsby develop"

Better match for intent of message. Deprecate old command and print depreciation notice and actually remove at 1.0

SyntaxError: Unexpected token ILLEGAL

Thank you for this wonderful script

➜  nikblog  gatsby serve
/usr/local/lib/node_modules/gatsby/lib/utils/serve.js:25
      HTML = require(`${__dirname}/../isomorphic/html`);
                     ^
SyntaxError: Unexpected token ILLEGAL
  at exports.runInThisContext (vm.js:73:16)
  at Module._compile (module.js:443:25)
  at Module._extensions..js (module.js:478:10)
  at Object.require.extensions.(anonymous function) [as .js] (/usr/local/lib/node_modules/gatsby/node_modules/babel-core/lib/api/register/node.js:214:7)
  at Module.load (/usr/local/lib/node_modules/gatsby/node_modules/coffee-script/lib/coffee-script/register.js:45:36)
  at Function.Module._load (module.js:310:12)
  at Module.require (module.js:365:17)
  at require (module.js:384:17)
  at Object.<anonymous> (/usr/local/lib/node_modules/gatsby/bin/serve.coffee:5:9)
  at Object.<anonymous> (/usr/local/lib/node_modules/gatsby/bin/serve.coffee:1:1)
  at Module._compile (module.js:460:26)
  at Object.loadFile (/usr/local/lib/node_modules/gatsby/node_modules/coffee-script/lib/coffee-script/register.js:16:19)
  at Module.load (/usr/local/lib/node_modules/gatsby/node_modules/coffee-script/lib/coffee-script/register.js:45:36)
  at Function.Module._load (module.js:310:12)
  at Module.require (module.js:365:17)
  at require (module.js:384:17)
  at Object.<anonymous> (/usr/local/lib/node_modules/gatsby/bin/gatsby-serve.js:5:1)
  at Module._compile (module.js:460:26)
  at Object.Module._extensions..js (module.js:478:10)
  at Module.load (module.js:355:32)
  at Function.Module._load (module.js:310:12)
  at Function.Module.runMain (module.js:501:10)
  at startup (node.js:129:16)
  at node.js:814:3

Can you please help me fix this?

Move needed require.context into an auto-written dot file and deprecate app.js

Every site needs a loadContext function to create a Webpack context (Webpack doesn't let you create require contexts with variables meaning loadContext has to have a hardcoded path which means it must have a known relationship with the pages source directory.).

Right now you need an app.js file for this function. We should make that optional by auto-writing a .gatsby.js file in the root directory of a site. This would also remove a potential roadblock from people creating a Gatsby site + allow us to easily change/add to this loadContext function.

Generating a sitemap

Any advice on where to start on generating sitemap either during gatsby serve or build ?

Thinking of using gatsby for my blog: https://johnbrett.me/

Single-file mode

As suggested by @andreypopp, it'd be very useful to be able to build a Gatsby site from a single JSX file. This would probably be built on top of #20 i.e. the base Gatsby \site would expect a single component to be passed in. The base site would setup the HTML structure etc. and render the react component inside of it.

Add hash to the bundle filename for better caching

Commands don't work on Window (Error: Cannot find module '...\npm\node_modules\gatsby\bin\cli-new' on `gatsby new`)

Gatsby installed successfully (no node-gyp errors), but creating a new site is throwing the error at me. I'm using Windows 10. Reinstalling gatsby didn't fix it.

Full error:

C:\Users\aniru>gatsby new test
module.js:339
    throw err;
    ^

Error: Cannot find module 'C:\Users\aniru\AppData\Roaming\npm\node_modules\gatsby\bin\cli-new'
    at Function.Module._resolveFilename (module.js:337:15)
    at Function.Module._load (module.js:287:25)
    at Function.Module.runMain (module.js:467:10)
    at startup (node.js:134:18)
    at node.js:961:3