gatsby

What is gatsby?

Gatsby is a React-based open-source framework for creating websites and apps. It allows developers to build fast, secure, and powerful web experiences using modern web technologies. Gatsby leverages GraphQL for data management and offers a rich plugin ecosystem to extend its functionality.

What are gatsby's main functionalities?

Static Site Generation

Gatsby can generate static pages from data sources like Markdown files. This code sample demonstrates how to create pages dynamically using GraphQL to query Markdown files and the createPage API to generate pages.

const path = require('path');

exports.createPages = async ({ graphql, actions }) => {
  const { createPage } = actions;
  const result = await graphql(`
    {
      allMarkdownRemark {
        edges {
          node {
            frontmatter {
              path
            }
          }
        }
      }
    }
  `);

  result.data.allMarkdownRemark.edges.forEach(({ node }) => {
    createPage({
      path: node.frontmatter.path,
      component: path.resolve(`src/templates/blog-post.js`),
      context: {},
    });
  });
};

GraphQL Data Layer

Gatsby uses GraphQL to manage data. This example shows how to query site metadata using GraphQL and display it in a React component.

import React from 'react';
import { graphql } from 'gatsby';

export const query = graphql`
  query {
    site {
      siteMetadata {
        title
      }
    }
  }
`;

const IndexPage = ({ data }) => (
  <div>
    <h1>{data.site.siteMetadata.title}</h1>
  </div>
);

export default IndexPage;

Plugin Ecosystem

Gatsby has a rich plugin ecosystem that allows developers to extend its functionality. This example shows how to configure plugins for handling React Helmet, sourcing files from the filesystem, and transforming Markdown files.

module.exports = {
  plugins: [
    `gatsby-plugin-react-helmet`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `src`,
        path: `${__dirname}/src/`,
      },
    },
    `gatsby-transformer-remark`,
  ],
};

Other packages similar to gatsby

next

Next.js is a React framework for server-side rendering and static site generation. It offers a more flexible approach to rendering, allowing developers to choose between static generation, server-side rendering, and client-side rendering on a per-page basis. Compared to Gatsby, Next.js is more versatile in terms of rendering options but may require more configuration for static site generation.

nuxt

Nuxt.js is a framework for creating Vue.js applications with server-side rendering, static site generation, and client-side rendering. It provides a similar feature set to Gatsby but is built on Vue.js instead of React. Nuxt.js is ideal for developers who prefer Vue.js over React.

gridsome

Gridsome is a Vue.js framework for building static websites and apps. It is similar to Gatsby in that it uses GraphQL for data management and offers a plugin ecosystem. Gridsome is a good alternative for developers who prefer Vue.js and want a static site generator with a similar feature set to Gatsby.

README

Gatsby

Transform plain text into dynamic blogs and websites using the latest web technologies. A React.js static site generator.

Build sites like it's 1995. Files are translated into HTML pages at the same position within the file system. Add a markdown file at /docs/index.md and it'll be converted to /docs/index.html.

Supports Markdown, HTML, and React.js components out of the box. Easy to add support for additional files types.

Leverages [React Router's "nested component hierarchy"](http://rackt.github.io/react-router/#Router Overview) to make templating incredibly intuitive.

All templates, css, and content are hot reloadable.

Goals

• No-reload page transitions
• Hot reload editing. Tweak your pages, templates, and styles and see changes in real time.
• Make React.js component model and ecosystem available for building static sites
• Intuitive directory-based URLs. The URL of a page is derived from its spot on the file system.
• Support "Starters" — install starter sites directly from Github. Use open sourced starters or build your own.

Demos

• Documentation site
• Blog

Why use Gatsby instead of other Static Site Generators

• No-refresh page transitions
• The awesome React.js component model
• Live editing on every part of your site. Dramatically speed development.

I'm already building a server-rendered React.js site, is Gatsby a good fit?

If you're site falls closer to the site end of the app<---->site spectrum then yes.

Gatsby is an excellent fit for blogs, marketing sites, docs sites, etc. Proper web apps should probably remain as normal web apps (though I'd love to be proved wrong!).

Warning!

Gatsby is very new. APIs will break. Functionality is missing. It's usable but if you plan on building with it, expect a rocky road for some time.

Contributions welcome!

Getting started

Install

npm install -g gatsby

Usage

1. Create new Gatsby site gatsby new my-test-gatsby-site This creates the directory for your Gatsby project and adds the minimal files needed.
2. cd my-test-gatsby-site
3. gatsby serve — Gatsby will compile your code using Webpack and serve the site at localhost:8000
4. See the tutorial below for more.

Gatsby Starters

The Gatsby cli tool lets you install "starters". These are partially built sites preconfigured to help you get moving faster on creating a certain type of site.

When creating a new site, you can optionally specify a starter to base your new site on e.g. gatsby new [URL_OF_STARTER]

For example, to quickly create a blog using Gatsby, you could install the Gatsby Starter Blog by running:

gatsby new blog https://github.com/gatsbyjs/gatsby-starter-blog

This downloads the files and initializes the site by running npm install

If you don't specify a custom starter, your site will created from the minimal default starter.

There are several starters that have been created. Create a PR to include yours!

• https://github.com/gatsbyjs/gatsby-starter-blog
• https://github.com/gatsbyjs/gatsby-starter-documentation

Tutorial: Building a documentation site from the Gatsby Documentation Starter

1. Install gatsby npm install -g gatsby
2. Install documentation site starter gatsby new docs-site gh:gatsbyjs/gatsby-starter-documentation
3. type cd docs-site
4. type gatsby serve
5. Open site in browser at localhost:8000. Verify clicking on links works.
6. Try editing the site's config file config.toml. Change the siteTitle key. The site's title should change shortly after saving.
7. Next try editing a doc page. Open /pages/docs/getting-started/index.md and edit it. Again any saved changes should load without refreshing in the browser.
8. Add a new markdown page to the documentation. Copy the getting-started directory to some-additional-steps. Then edit the markdown file within the new directory. If you're familiar with other static site generation software, you'll be familiar with the "frontmatter" at the top of the file. Edit the title there + change the order to "5". Save this. Ideally this new file would be hot reloaded like other changes but I haven't figured out how to make this happen yet (help appreciated here). So to see your new page, restart gatsby serve and then refresh your browser.
9. Build your site gatsby build. The site is built to the /public directory. Serve the site by going into the public directory and typing python -m SimpleHTTPServer

How Gatsby works

How files become pages

The process is file --> Webpack loader --> React.js wrapper component --> static html page.

Gatsby leverages Webpack extensively. Webpack is a sophisticated module bundler that can turn any sort of file into a commonjs module. Webpack uses "Loaders" to convert a file into a module. These loaded modules are then wrapped inside a react.js component that's specific to a given file type. Gatsby then generates a static html page from this component.

Gatsby ships with default loaders and wrappers for HTML, Markdown, and JSX/CJSX but for most projects you'll want to write your own loaders and wrappers (very easy to do).

As an example of how this process works, let's walk quickly through converting a markdown file into an html page.

The default Gatsby markdown loader parses the markdown into HTML and uses Highlight.js to syntax highlight code blocks.

Our markdown file.

---
title: This is a title
---

# Hi friends.
This is a markdown file.

When loaded and required, the resulting javascript object looks like the following.

{
  file: {
    // Information about file on disk e.g. extension, directory path, etc.
  },
  data: {
    title: "This is a title",
    body: "<h1>Hi friends.</h1><p>This is a markdown file</p>"
  }
}

Now Gatsby wraps the markdown file in this very simple React.js component.

module.exports = React.createClass({
  displayName: "MarkdownWrapper",

  render: function() {
    post = @props.page.data

    <div className="markdown">
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{__html: post.body}}/>
    </div>
  }
})

How to write your own loaders/wrappers

• Coming...

Structure of a Gatsby site

• /pages — All pages go here. Everything is turned into a page except files which start with an underscore
• _template files — coming...

Sites built with Gatsby

• bricolage.io
• relaterocket.co
• Add yours!

FAQ

Configuring Babel

Configuring babel-loader is as easy as creating a .babelrc in the root of the project. To enable stage 0 transforms, the following .babelrc could be used:

{
  "stage": 0
}