Get started with Gatsby

Overview

This covers integrating Plasmic into your existing Gatsby codebase in three steps.

Want to generate a new codebase with Plasmic already integrated? Follow this quickstart instead!

Installation

npm install @plasmicapp/loader-gatsby
# or yarn add @plasmicapp/loader-gatsby

Initialization

Include the plugin @plasmicapp/loader-gatsby in gatsby-config.js.

gatsby-config.js

module.exports = {
  ...
  plugins: [
    {
      resolve: "@plasmicapp/loader-gatsby",
      options: {
        projects: [
          {
            id: "PROJECTID",  // ID of a project you are using
            token: "APITOKEN"  // API token for that project
          },
        ],
        // Fetches the latest revisions, whether or not they were unpublished!
        // Disable for production to ensure you render only published changes.
        preview: true
      },
    },
  ],
}

Render a single Plasmic page or component

We use Gatsby’s GraphQL layer to fetch the design statically.

src/pages/my-page.tsx

import React from "react";
import {
  PlasmicComponent,
  PlasmicRootProvider,
  initPlasmicLoader,
} from "@plasmicapp/loader-gatsby";
import { graphql } from 'gatsby';

// Statically fetch the data needed to render Plasmic pages or components.
// You can pass in multiple page paths or component names.
export const query = graphql`
  query {
    plasmicComponents(componentNames: ["COMPONENTNAME"])
    plasmicOptions
  }
`;

// Render the page or component from Plasmic.
export default const MyPage = ({ data }) => {
  const { plasmicComponents, plasmicOptions } = data;
  return (
    <PlasmicRootProvider
      loader={initPlasmicLoader(plasmicOptions)}
      prefetchedData={plasmicComponents}
    >
      <PlasmicComponent component="PATH_OR_COMPONENT" />
    </PlasmicRootProvider>
  );
};

Auto load all Plasmic pages

To automatically render all Plasmic-defined pages at the routes specified in Plasmic, specify a Gatsby template page:

gatsby-config.js

module.exports = {
  // ...
  plugins: [
    {
      resolve: '@plasmicapp/loader-gatsby',
      options: {
        // ...
      },
      options: {
        projects: [
          {
            id: 'PROJECTID', // ID of a project you are using
            token: 'APITOKEN' // API token for that project
          }
        ],
        defaultPlasmicPage: require.resolve('./src/templates/defaultPlasmicPage.tsx'),
        // Optionally specify pages to ignore.
        ignorePaths: ['/my-page']
      }
    }
  ]
};

And create the template, editing it with any wrappers you want:

src/templates/defaultPlasmicPage.tsx

import React from 'react';
import { initPlasmicLoader, PlasmicComponent, PlasmicRootProvider } from '@plasmicapp/loader-gatsby';
import { graphql } from 'gatsby';

export const query = graphql`
  query ($path: String) {
    plasmicComponents(componentNames: [$path])
    plasmicOptions
  }
`;

const PlasmicGatsbyPage = ({ location, data }) => {
  const { plasmicComponents, plasmicOptions } = data;
  return (
    <PlasmicRootProvider loader={initPlasmicLoader(plasmicOptions)} prefetchedData={plasmicComponents}>
      <PlasmicComponent component={location.pathname} />
    </PlasmicRootProvider>
  );
};

export default PlasmicGatsbyPage;

There’s much more to explore!

Bring your own React components into Plasmic.
Perform server-side rendering.
Render different variants.
Override the content or props.
Add dynamic behavior.

Continue learning in the docs.