PlasmicLoader guide

PlasmicLoader lets you load pages and components at build-time into your Next.js and Gatsby applications, without actually needing to store code into your repo/version history. This enables the same workflow as a content management system—non-developers can freely iterate and publish pages and other content directly from Plasmic Studio, without needing to involve developers or commit changes into the codebase. Simply initiating a new build of your website is sufficient to see your content go live.

PlasmicLoader is currently available for Next.js and Gatsby codebases.

Getting started

To quickly integrate PlasmicLoader into any Next.js or Gatsby codebase, check out our quickstart guide.

Usage

By default, once you have set up PlasmicLoader in your Next.js or Gatsby configuration, then any pages you create in your Plasmic project will automatically show up in your built site at the associated routes. No further code changes are needed.

Besides pages, to render a component somewhere in your app, use the PlasmicLoader component:

import PlasmicLoader from '@plasmicapp/loader';

export default function MyPage() {
  return (
    <div>
      <PlasmicLoader
        component="component-name"

        {/* Required if you have multiple projects with the same component name. */}
        projectId="some-project-id"

        {/* Any props or overrides you wish to pass to this component. See API below. */}
        componentProps={{
          onClick() {
            // ...
          },
          someComponentProp() {
            // ...
          }
        }}

        {/* Wrap this component in its own global variant providers. */}
        {/* Keep reading for a better way to achieve this across all components. */}
        providerProps={{
          Theme: 'dark'
        }}
      />
    </div>
  );
}

Component API

The componentProps prop offers a flexible API to let you control any aspect of them. You can pass in values to slots, replace or wrap elements, attach props to elements, and more.

Learn about the component API.

Adding global variant providers

If your components make use of global variant groups, you’ll want to add the corresponding providers to specify which global variant per group to render. Usually you’ll want all your components across your application to render according to the same global variant—for instance, render all components according to Theme=Dark global variant.

To do so, you can add these providers from your global app wrapper.

Component substitution

The componentProps API lets you customize any instance of a component, but when you are adding state or behavior, you usually want this to be associated with the component itself (across all instances).

Besides attaching behavior, you may also want to globally replace any component with an existing code component.

In these scenarios, you can tell Plasmic that wherever it encounters an instance of some Plasmic component, render instead a different React component of your choosing. This can be a wrapper that contains state/behavior, or it can be an entirely different component (don’t render the Plasmic design at all).

// In your plasmic config
{
  substitutions: {
    components: [{ name: 'Header', path: 'src/components/Header.jsx' }],
  }
}

Then from that React component, you can add arbitrary logic:

// src/components/Header.jsx
import PlasmicLoader from '@plasmicapp/loader';
import useUser from 'hooks/data/useUser';

export default function Header(props) {
  // Do anything you want in this component!

  // For instance, add hooks or any other logic.
  const user = useUser();

  // Use PlasmicLoader to render the Header component from the Plasmic
  // project--this one *won't* be substituted recursively.
  return (
    <PlasmicLoader
      component="Header"
      componentProps={{
        // Important! Spread the props to forward them to our plasmic header.
        ...props,
      }}
  );

  // Or render something entirely different....
  // render <WebglPoweredHeader/>;
}

Learn more about substituting in existing code components.

Plugin options

These options are useful if you need to integrate PlasmicLoader into a custom codebase.

PropDefaultDescription
projectsNone (Only required setting!)An array with the projects to sync.
dirCurrent working directory.The root directory of your project.
plasmicDir.cache/.plasmic (Gatsby)
.plasmic (Next)
Plasmic will sync your plasmic projects to this directory.
pageDirsrc/pages (Gatsby)
pages(Next)
A directory with your existing pages.
watchTrue (in development)
False otherwise.
Listen to changes in your plasmic project and sync them to your codebase.
initArgsPlatform-dependent.Plasmic is able to detect your codebase language (js, tsx) and comes with good defaults for public folder, image assets, css mode and other options. Click here for a full list. To override something, pass an object with the key being plasmic CLI’s flag name and the corresponding value.
substitutionsNoneClick here. for more information regarding component substitution.