How can I get started with GatsbyJS?

Install the Gatsby CLI

Before we can start a Gatsby project, we need to install the Gatsby CLI:

npm install -g gatsby-cli

Start a Gatsby project

To start a Gatsby project using a basic starter, run

gatsby new my-project https://github.com/gatsbyjs/gatsby-starter-hello-world

This will create a my-project directory inside the current directory.

Let's cd my-project.

To start the Gatsby development server, run npm run develop.

Then, open your browser and go to localhost:8000.

You should see a page that says "Hello world".

Changing the index page

The src directory has a pages directory which is where we will place our pages.

Initially, the pages directory has only one file: index.js for the index page.

In a page file, such as index.js, you need to create a React component that will be rendered for that particular page.

Then, you need to export it as the default export.

Let's start by changing the index.js file to

import React from "react";

const IndexPage = () => (
  <div>
    <h1>Home page</h1>
    <p>Welcome to the home page!</p>
  </div>
);

export default IndexPage;

You should see these changes in your browser right away since the Gatsby development server comes with hot module reloading (HMR).

Adding more pages

You can add more pages by creating more files in the pages directory.

Let's say that you want to have an about page that will be accessed as /about.

Create an about.js file in the pages directory with the component that you want to render when the about page is visited.

For example, the content of the about page could be

import React from "react";

const AboutPage = () => (
  <div>
    <h1>About us</h1>
    <p>We are just getting started.</p>
  </div>
);

export default AboutPage;

Defining shared components

Let's say that we want to have a Button component that will be used across our pages.

We can create a separate directory, such as components inside the src directory to store shared components.

Then, in the components directory, we create a file button.js within which we define the Button component and export it.

In our pages, we can import the Button component as

import Button from "../components/button";

We can then combine our components however we want.

Defining page specific components

Let's say that we want to break a complex page into smaller pieces.

We can do so by defining components that render specific parts of our page.

Since these components are page-specific, we should not define them in the components directory which we use for shared components (unless we want to have a flat component structure in which we give components long names to make it clear to which page they belong).

What we could do is to define page-specific components in a pages directory that is inside the components directory.

So, if we have a projects.js page and we want to have a page-specific Project component, we can define the Project component in

src/components/pages/projects/project.js

Adding a Layout component

We often want our pages to have the same header and footer.

We can define a Header and a Footer component and then render them inside a Layout component.

The Layout component expects the page content to be passed via the children prop.

const Layout = ({ children }) => (
  <div>
    <Header />
    { children }
    <Footer />
  </div>
);

Then, in a page component, we can use Layout as

const IndexPage = () => (
  <Layout>
    <h1>Home page</h1>
    <p>Welcome to the home page!</p>
  </Layout>
);

This will allow all pages that wrap their content in the <Layout> component to share the same header and footer.

Adding styles

Let's now see how to style our pages and components.

Adding support for SASS

If we intend to use SASS to style our components, we need to install node-sass and the SASS Gatsby plugin:

npm install node-sass gatsby-plugin-sass

After that, we need to specify the SASS plugin in gatsby-config.js:

module.exports = {
  plugins: [
    "gatsby-plugin-sass",
    // ...
  ],
};

Now we can use SASS in our project!

Adding global styles

We probably want to have global styles with resets etc. that are applied to all pages.

We can place the file with global styles in a styles directory inside src and name it something like index.scss.

Then, we would need to import the styles file in another file that is always imported by the Gatsby entry level script.

Such file is named gatsby-browser.js and it should be created in the root directory of our project.

We can then import the global styles file inside gatsby-browser.js as:

import "./src/styles/index.scss";

Now we have global styles applied to all our pages.

Adding SASS partials

In the src/styles directory, we can also place SASS partials, such as _globals.scss and _mixins.scss, and import them in index.scss as:

@import "globals";
@import "mixins";

Adding component specific styles

To add component specific styles, we can use CSS modules which are supported out of the box in our Gatsby project.

Let's say we want to style the Header component.

We can create a header.module.scss file inside the src/components directory and add some styles, such as:

.header {
  padding: 1rem 0;
}

.content {
  font-size: 0.85rem;
}

Then, in our header.js file, we can import the styles and use them:

import styles from "./header.module.scss";
// ...
const Header = () => (
  <header className={styles.header}>
    <div className={styles.content}>
      ...
    </div>
  </header>
);

If we wanted to use SASS partials in the header styles, we would import them specifying the relative path:

@import "../styles/globals";
@import "../styles/mixins";

Adding page specific styles

Page specific styles can be added directly in the src/pages directory.

For example, styles specific to about.js will be inside the about.module.scss file, which is imported inside about.js as:

import styles from "./about.module.scss";

Creating a production build

Once we finish working on our Gatsby website and we are ready to go to production, we can create a production build by running:

npm run build

Which will create a public directory with all our pages optimized for production.

Conclusion

We've seen how to create a simple static website using GatsbyJS by defining React components and styling them using SASS and CSS modules.

If you want to learn more about GatsbyJS and other things that you can do with it (such as querying content by using GraphQL), consult the GatsbyJS documentation.