Upgrading to PlasmicLoader v2

Headless API v2 is a different approach from v1 for consuming Plasmic designs. Whereas v1 tried to generate React component files into your file system, v2 treats Plasmic components more as data assets that can be fetched and used over the wire, without a file system involved. This allows v2 to be more versatile and used in more places — from dynamic client-side React applications to rendering pure HTML.

This is a breaking change. Here are some things you need to do:

Migrating for Next.js

If your current project uses @plasmicapp/loader, and you use Next.js, then you should migrate. Here are the steps you should take:

1. Change your dependency from @plasmicapp/loader to @plasmicapp/loader-nextjs.
2. Add a call to initPlasmicLoader() somewhere (usually in some init.ts file), like this:

import { initPlasmicLoader } from '@plasmicapp/loader-nextjs';
export const PLASMIC = initPlasmicLoader({
  projects: [
    {
      id: '',
      token: ''
    }
  ]
});

Here, you will be listing all the projects and their security tokens. You can look up tokens of the projects you’re currently using in your plasmic-loader.json file.

3. Switch <PlasmicLoader /> to <PlasmicComponent />. The API of this component is similar, but now more accurately reflect what it does.

4. Move your component substitutions to init.ts. Component substitution used to be done in next.config.js; now you register them directly in init.ts, like so:

import { initPlasmicLoader } from '@plasmicapp/loader-nextjs';
import { SpecialButton } from './components/SpecialButton';
export const PLASMIC = initPlasmicLoader({ ... });
// Substitutes SpecialButton for Plasmic component "Button"
PLASMIC.substituteComponent(SpecialButton, "Button");

Note that if your substituted component is also using <PlasmicComponent/> to render, then you’ll need to pass in forceOriginal, to make sure PlasmicComponent gives you the original Plasmic-generated component, and not the substituted component.

export function Button(props) {
  // Add in your own state or hooks
  const [blah, setBlah] = React.useState();
  // But still use Plasmic-generated Button to render
  return <PlasmicComponent component="Button" componentProps={props} forceOriginal />;
}

5. Add in your catch-all [...plasmicLoaderPage].tsx page. The old PlasmicLoader used to generate this page for you; now it is up to you to integrate PlasmicLoader with the rest of your catch-all handler. See section on how.

Migrating for Gatsby

If your current project uses @plasmicapp/loader, and you use Gatsby, then you should migrate. Here are the steps you should take:

1. Change your dependency from @plasmicapp/loader to @plasmicapp/loader-gatsby.

2. Update gatsby-config.js with the new configuration for the plugin:

module.exports = {
  ...
  plugins: [
    {
      resolve: "@plasmicapp/loader-gatsby",
      options: {
        projects: [
          {
            id: "...",  // ID of a project you are using
            token: "..."  // API token for that project
          },
        ],
        defaultPlasmicPage: require.resolve(
          "./src/templates/defaultPlasmicPage.tsx"
        ),
      },
    },
  ],
}

3. Create an initPlasmic function somewhere (usually in some init.ts file), that look like this:

import { initPlasmicLoader } from '@plasmicapp/loader-gatsby';

export function initPlasmic(options) {
  const loader = initPlasmicLoader(options);
  return loader;
}

4. Switch <PlasmicLoader /> to <PlasmicComponent />. The API of this component is similar, but now more accurately reflect what it does.

5. Update your graphql queries. Each page that was created manually and is using the old <PlasmicLoader /> should include a new query for the components that are used in the page and a <PlasmicRootProvider />.

import {
  PlasmicComponent,
  PlasmicRootProvider,
} from "@plasmicapp/loader-gatsby";
import { initPlasmic } from "./plasmic-init";

export const query = graphql`
  query {
    ...

    plasmicComponents(componentNames: ["Header", "Footer"])
    plasmicOptions
  }
`;

export default const MyPage = ({ data }) => {
  const { plasmicComponents, plasmicOptions } = data;
  return (
    <PlasmicRootProvider
      loader={initPlasmic(plasmicOptions)}
      prefetchedData={plasmicComponents}
    >
      <PlasmicComponent component="Header" />
      ....
      <PlasmicComponent component="Footer" />
    </PlasmicRootProvider>
  );
};

6. Move your component substitutions to init.ts. Component substitution used to be done in gatsby-config.js; now you register them directly in init.ts, like so:

import { initPlasmicLoader } from '@plasmicapp/loader-gatsby';
import { SpecialButton } from './components/SpecialButton';
export function initPlasmic(options) {
  const loader = initPlasmicLoader(options);
  // Substitutes SpecialButton for Plasmic component "Button"
  loader.substituteComponent(SpecialButton, 'Button');
  ...
  return loader;
}

7. Add in your defaultPage plasmicDefaultPage.tsx page. The old PlasmicLoader used to generate this page for you; now it is up to you to include the template for your pages defined in Plasmic. See section on how.

Have feedback on this page? Let us know on our forum.