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.