Launching the project

Prismic no longer recommends the gatsby-source-prismic-graphql plugin

With recent changes to Gatsby, Prismic no longer recommends the gatsby-source-prismic-graphql plugin that this documentation uses. Read more about the future of Prismic and Gatsby. We highly recommend using the gatsby-source-prismic instead. The documentation for this plugin can be found in the plugin's github README.

We will leave this documentation here for now, but will change it in the future when we determine the best approach for Prismic & Gatsby.

Welcome to the first article in this getting started tutorial. Hopefully by now you've checked out the intro article to get an idea of what this series is all about. In this article, we'll be getting everything we need for this tutorial series setup and prepared. Let's jump in and get started!

1. Launch a Prismic repo & download the project files

To help us begin, we have a Prismic Command Line Interface (CLI) tool that will let us launch a new Prismic repository with all our content and download the static Gatsby site.

First we'll need to install the Prismic CLI (if you don't already have it). Launch the terminal (command prompt or similar on Windows) and run the following command.

Copy
npm install -g prismic-cli

Sometimes it's possible that this command doesn't work. If that's the case for you and you're on a Mac, try executing a sudo command instead: sudo npm install -g prismic-cli. If you're on a windows PC, then run the command as an Admin.

Now you'll need to navigate in the terminal to the location you want to create your Prismic project and run the following command.

Copy
prismic theme https://github.com/prismicio/gatsby-getting-started-tutorial --ignore-conf

This will launch the installer. It will prompt you to name your Prismic repository and local folder (the location where you will download the project files).

You may also need to enter the email and password for your Prismic account (or sign up for an account), but once you are done with that, the CLI will set everything up for you.

It will automatically create your new Prismic repository (filled with all required content) and download the project files to your computer.

2. Run the project locally

Now let's launch the project so that you can see the static version of the site in action. Launch a terminal and navigate to the root of the project you just downloaded and run the following command.

Copy
npm start

The site may take a minute to build, but once that is done, you'll be able to view your site from http://localhost:8000/. Make sure that the site is working, then let's take a look at the project code.

Open the project files in your favorite text editor. We recommend Microsoft Visual Studio Code as a great free editor, but obviously you can use whatever editor you like best 😀

If you take a look at the project files, you'll notice that all the content is hardcoded in all the pages, for example in src/pages/about.js. It doesn't use Prismic yet, so that's what we'll be doing from here on out: converting from having the content hardcoded to being pulled from your Prismic repository.

3. Install the required plugin & dependency

Next let's install the dependencies that we need for this project. We will need a plugin for Gatsby to retrieve the content from Prismic as well as a Prismic library to help convert some of the Prismic data into JSX to add to our pages.

The Gatsby plugin

There are a few plugins for Gatsby & Prismic, but the plugin that we recommend using is gatsby-source-prismic-graphql.

Let's add this plugin to our project now. You can terminate your local server by going to your terminal and pressing Ctrl + C. Now run the following command from the root of your project (you should already be there).

Copy
npm install @prismicio/gatsby-source-prismic-graphql

This will install the plugin that we need.

The Prismic rendering library

Now we just need to install one more library: prismic-reactjs. As mentioned above this will help us add certain fields (like Rich Text fields) to our templates as we'll see in later articles in this series.

Run the following command to install the library.

Copy
npm install prismic-reactjs

And now we should have everything we need installed on the project!

4. Set up the plugin configuration

Before we can do anything else, we need to update the gatsby-config.js file to include the configuration for the new plugin that we just installed.

Open the gatsby-config.js file: here is where you can setup the configuration for all your plugins. Let's add the following config to the bottom of the plugins array (note that the tabs below show you the individual snippet as well as the full page code).

  • Plugin config
  • Full gatsby-config.js file
Copy
{
  resolve: '@prismicio/gatsby-source-prismic-graphql',
  options: {
    repositoryName: 'your-repo-name',
  },
},
Copy
module.exports = {
  siteMetadata: {
    title: 'Gatsby + Prismic Tutorial',
    description: 'Learn how to integrate Prismic into your Gatsby project.',
  },
  plugins: [
    'gatsby-plugin-react-helmet',
    {
      resolve: 'gatsby-plugin-prefetch-google-fonts',
      options: {
        fonts: [
          {
            family: 'Lato',
            variants: ['400', '400i', '700', '700i', '900'],
          },
          {
            family: 'Amiri',
            variants: ['400', '400i', '700', '700i'],
          },
        ],
      },
    },
    'gatsby-transformer-sharp',
    'gatsby-plugin-sharp',
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        icon: 'src/images/favicon.png',
      },
    },
    {
      resolve: '@prismicio/gatsby-source-prismic-graphql',
      options: {
        repositoryName: 'your-repo-name',
      },
    },
  ],
}

Update the repositoryName

Make sure that you update the repositoryName to match the url of the Prismic repository that was created earlier in this article. In order to find this, go to your Prismic repository. If the url for your repository is https://my-awesome-repository.prismic.io/ then you'll need to replace 'your-repo-name' above with 'my-awesome-repository'.

Save the gatsby-config.js file with your changes before moving on.

5. Test the plugin

Now that the config is set, let's do a quick test to make sure that it is working. Go back to your terminal and launch the project again.

Copy
npm start

Once the build is complete, you should be able to go to http://localhost:8000/___graphql to test your GraphQL queries. Let's see if the content from Prismic was pulled into the project correctly. In the left panel add this query:

Copy
{
  prismic {
    allHomepages {
      edges {
        node {
          banner_title
          banner_description
          banner_background
        }
      }
    }
  }
}

Run the query by pressing the "play" button at the top and you should see your Prismic content appear in the right panel.

Gatsby GraphQL query results

If this is what you see then congratulations: it's working!! Now we're all set to start converting our hardcoded content into Prismic content.

Next steps

Next up we will be replacing the banner at the top of the homepage with content that is pulled from Prismic. Head to the next article to get started!

Converting the static Homepage Banner →