All Technologies / Gatsby / Tutorial / Launch the Project

Launch the Project

Welcome to the first article in this 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

Run the following theme command in the terminal. It'll perform these processes:

  1. It will install the Prismic CLI (command-line interface) if it's not yet installed in your machine. This tool will allow you to interact with Prismic from your local machine.
  2. It will run the theme command, which will prompt you to name your Prismic repository and local folder. Then, it'll install the project code locally, download the project files to your machine, and create a brand new repository with content.
  3. If you're not logged in to Prismic yet, it'll prompt an option to enter the email and password for your Prismic account (or sign up for an account).

Navigate to the location you want to create your Prismic project and run the following command:

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

2. Add environment variables

Environment variables allow you to safely store sensitive information about your projects, like your repository name or access token. For this tutorial, we'll only configure the repository name. At the root of your project, create two files:

  • .env.development
  • .env.production

Then, paste the following variable into both of them and update the your-repo-name value with the name of the Prismic repository created earlier in this article. To find this, go to your Prismic dashboard, then to your repository. For example, if the URL for your repository is https://my-new-site.prismic.io, then replace your-repo-name with my-new-site.

Copy
GATSBY_PRISMIC_REPO_NAME=your-repo-name

Once this is set up, you'll be able to access your repository name variable like this: process.env.GATSBY_PRISMIC_REPO_NAME

3. Run the project

Navigate to the project's root (you can run cd your-project-name to enter the correct directory. 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; then, 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—for example, VS Code.

At this point, the content doesn't use Prismic yet; for example, if you open the ~src/pages/about.js file, you'll see everything is hard-coded. From here on out, we'll use the content from your Prismic repository ✨.

4. Install the plugin and dependencies

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

1. gatsby-source-prismic

Stop your local server by running Ctrl + C, then run the following command from your project's root:

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

This gatsby-source-prismic plugin sources data from your Prismic repository.

The @prismicio/react rendering library helps add certain fields (like Rich Text fields) to our templates, as we'll see in later articles in this series.

5. Configure the plugin

Update the gatsby-config.js file to include the source plugin we just installed. For now, we're just going to set the most basic configuration, which is:

  1. repositoryName: The name of your repository, which you have already set up in an environment variable.
  2. schemas: The JSON definition of each of the Custom Types and their fields in your repository to build the correct GraphQL schema. Leave this configuration and the Custom Types as they are. You'll be able to change this in the future.

Replace the code in your gatsby-config.js file with the following:

Copy
// gatsby-config.js file

require("dotenv").config({
  path: `.env.${process.env.NODE_ENV}`,
})

module.exports = {
  siteMetadata: {
    title: 'Gatsby + Prismic Tutorial',
    description: 'Learn how to integrate Prismic into your Gatsby project.',
  },
  plugins: [
    {
      resolve: 'gatsby-source-prismic',
      options: {
        repositoryName: process.env.GATSBY_PRISMIC_REPO_NAME,
        schemas: {
          homepage: require('./custom_types/homepage.json'),
          navigation: require('./custom_types/navigation.json'),
          page: require('./custom_types/page.json'),
        },
      },
    },
    'gatsby-plugin-image',
    'gatsby-plugin-react-helmet',
    {
      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`],
      },
    },
  ],
}

⚠️ No need to modify the Custom Types

You do not need to change anything in the Custom Types of your repository. If you wish to change anything, we highly recommend you wait until the end of this step-by-step tutorial and read the dedicated plugin configuration article.

6. 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 appears in the project correctly. In the left panel, add this query:

Copy
query MyQuery {
  prismicHomepage {
    data {
      banner_title {
        text
      }
      banner_description {
        text
      }
    }
  }
}

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 from Prismic.

Create a homepage banner →
Was this article helpful?
Not really
Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.