Launch the project

Welcome to the first article in this getting started with Prismic & Gatsby tutorial. 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 the project

Install the Prismic CLI

Install the latest version of the Prismic CLI. (Check your version by running prismic --version and compare it to the latest version released on npm) You can do that by running the following command:

Copy
npm install -g prismic-cli

Sometimes it's possible that a global (-g) command like this doesn't work because of permission levels on your machine. If that's the case for you, try executing the sudo command below:

Copy
sudo npm install -g prismic-cli

Login or Sign up

You may also need to enter the email and password for your Prismic account (or sign up for an account). Once you are done with that, the CLI will set everything up for you. Enter this command to login:

Copy
prismic login

Launch a Prismic repo & download the project files

Now, navigate 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

It will prompt you to name your Prismic repository and local folder. It will create your new Prismic repository filled with all required content and download the project files to your computer.

2. Run the project locally

Navigate to the root of the project (you can run cd your-project-name to enter the correct directory. Just make sure you change the name to your project name); once there, 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 by visiting this URL in your browser http://localhost:8000. Then, open the project code in your favorite text editor (e.g., VS Code).

At this point, all the content is hardcoded in all the pages, and it doesn't use Prismic yet, e.g., src/pages/about.js. So that's what we'll be doing from here on out, converting hardcoded content to being pulled from your Prismic repository ✨.

3. Install the plugin & dependencies

Next, let's install the plugin and dependencies needed for this project.

The gatsby-source-prismic plugin

Add the recommended plugin. Terminate your local server by running Ctrl + C, then run the following command from your project's root:

Copy
npm install gatsby-source-prismic

The prismic-reactjs rendering library

Install one more library: prismic-reactjs. 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:

Copy
npm install prismic-reactjs

4. Set up the plugin configuration

Update the gatsby-config.js file to include the plugin that we just installed. Let's add the following config to the plugins array. For now, we're just going to set the most basic configuration, which is:

  1. repositoryName: The name of your repository.
  2. schemas: The JSON definition of each of the Custom types and their fields in your repository to build the correct GraphQL schema. For now, you should leave this configuration and the Custom types as they are. You'll be able to change this in the future.

⚠️ Update the repositoryName

Make sure that you update the repositoryName to match the URL of the Prismic repository created earlier in this article. To find this, go to your Prismic dashboard, then to your 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'.

  • Plugin config
  • Full gatsby-config.js file
Copy
{
  resolve: 'gatsby-source-prismic',
  options: {
    repositoryName: 'your-repo-name',
    schemas: {
       homepage: require("./custom_types/homepage.json"),
       navigation: require("./custom_types/navigation.json"),
       page: require("./custom_types/page.json"),
    },
  },
},
Copy
module.exports = {
  siteMetadata: {
    title: 'Gatsby + Prismic Tutorial',
    description: 'Learn how to integrate Prismic into your Gatsby project.',
  },
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: 'your-repo-name',
        schemas: {
          homepage: require('./custom_types/homepage.json'),
          navigation: require('./custom_types/navigation.json'),
          page: require('./custom_types/page.json'),
        },
      },
    },
    'gatsby-plugin-react-helmet',
    'gatsby-transformer-sharp',
    'gatsby-plugin-sharp',
    {
      resolve: 'gatsby-plugin-manifest',
      options: {
        icon: 'src/images/favicon.png',
      },
    },
    {
      resolve: 'gatsby-source-filesystem',
      options: {
        name: 'images',
        path: `${__dirname}/src/images`,
      },
    },
    {
      resolve: 'gatsby-plugin-google-fonts',
      options: {
        fonts: [`Lato\:400,400,700,700i,900`, `Amiri\:400,400,700,700i`],
      },
    },
  ],
}

⚠️ Don't modify the Custom type schemas

We recommend you to not change anything in the Custom types or documents of your repo at this point. You'll be able to do it later in this guide.

But, If you modified anything in the Custom Types of your repository, you'll need to update the JSON schemas files as well. Otherwise, the changes won't be reflected. To update the JSON files, you'll need to go to the modified Custom Type, click on the JSON editor tab, copy the content, and then paste it into the corresponding file.

5. Test the plugin

Now that the config is set let's do a quick test to ensure it works. Go back to your terminal and relaunch the project.

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
{
  allPrismicHomepage {
    edges {
      node {
        data {
          banner_title {
            raw
          }
          banner_description {
            raw
          }
        }
      }
    }
  }
}

Run the query by pressing the play button at the top, and you should see your Prismic content appear in the right panel. If this is what you see, then congratulations: it's working!

Next steps

Next up, we will be replacing the banner at the top of the homepage with content that is pulled from Prismic.

Converting the static Homepage Banner →