Get started with Gatsby

Overview

This covers integrating Plasmic into your existing Gatsby codebase.

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

Installation

Copy
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
Copy
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

Note: You can auto-load all Plasmic pages at the correct routes (recommended) rather than manually loading individual pages—see next section.

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

For example, to render a page: add a file under src/pages/, named for your desired route, with the following code:

src/pages/my-page.tsx
Copy
// This page will show up at the route /my-page
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
Copy
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
Copy
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 removeTrailingSlash = (path) => (path === '/' ? '/' : path.replace(/\/+$/, ''));
const PlasmicGatsbyPage = ({ location, data }) => {
const { plasmicComponents, plasmicOptions } = data;
return (
<PlasmicRootProvider loader={initPlasmicLoader(plasmicOptions)} prefetchedData={plasmicComponents}>
<PlasmicComponent component={removeTrailingSlash(location.pathname)} />
</PlasmicRootProvider>
);
};
export default PlasmicGatsbyPage;

Add custom code components

Let your Plasmic Studio users drag/drop and visually manipulate any React component! (Learn more.)

Step 1

Create a special hidden page at route /plasmic-host.

src/pages/plasmic-host.tsx
Copy
import * as React from 'react';
import { PlasmicCanvasHost } from '@plasmicapp/loader-gatsby';
import Helmet from 'react-helmet';
import '../plasmic-init';
export default function Host() {
return (
<>
<Helmet>
<script src="https://static1.plasmic.app/preamble.js" />
</Helmet>
<PlasmicCanvasHost />
</>
);
}

Step 2

Start your app:

Copy
npm run start

And check that you see a confirmation message at http://localhost:8000/plasmic-host.

Step 3

Create a simple example React component:

src/components/HelloWorld.tsx
Copy
import React from 'react';
export interface HelloWorldProps {
children?: ReactNode;
className?: string;
verbose?: boolean;
}
export function HelloWorld({ children, className, verbose }: HelloWorldProps) {
return (
<div className={className} style={{ padding: '20px' }}>
<p>Hello there! {verbose && 'Really nice to meet you!'}</p>
<div>{children}</div>
</div>
);
}

Step 4

Create a module src/plasmic-init.ts that extracts initPlasmicLoader centrally:

src/plasmic-init.ts
Copy
import { initPlasmicLoader } from '@plasmicapp/loader-gatsby';
import { HelloWorld } from './components/HelloWorld';
export function initPlasmicLoaderWithRegistrations(plasmicOptions: any) {
const PLASMIC = initPlasmicLoader(data);
// Add all your code component registrations here.
PLASMIC.registerComponent(HelloWorld, {
name: 'HelloWorld',
props: {
verbose: 'boolean',
children: 'slot'
}
});
return PLASMIC;
}

Now replace all other calls to initPlasmicLoader with initPlasmicLoaderWithRegistrations. For instance, if you’re auto-loadng all Plasmic pages in src/templates/defaultPlasmicPage.tsx:

src/templates/defaultPlasmicPage.tsx
Copy
import { initPlasmicLoaderWithRegistrations } from '../plasmic-init';
// ...
const PlasmicGatsbyPage = ({ location, data }) => {
const { plasmicComponents, plasmicOptions } = data;
return (
<PlasmicRootProvider loader={initPlasmicLoaderWithRegistrations(plasmicOptions)} prefetchedData={plasmicComponents}>
{/* ... */}
</PlasmicRootProvider>
);
};
// ...

Step 5

Open https://studio.plasmic.app, click the menu for the current project, select "Configure project," and set it to http://localhost:8000/plasmic-host.

configure project menu

Step 6

Re-open this project (or reload this tab) to see your component listed in the insert menu!

insert code component

Later, after you deploy the route to production, update the project to use your production host URL instead, such as https://my-app.com/plasmic-host. This way, other members of your team (who can’t access your localhost dev server) will be able to open and edit the project in Plasmic.

Learn more about code components.

There’s much more to explore!

For example:

Continue learning in the full docs.