Fetching components from Plasmic

Components are designed in the Plasmic Studio, and rendered in your application. When you are ready to render, you need to fetch the designs from Plasmic first.

The @plasmicapp/loader-* packages export an initPlasmicLoader() function, which returns the object you can use to fetch component designs and other metadata from Plasmic.

PlasmicComponentLoader

An instance of PlasmicComponentLoader is returned by initPlasmicLoader(). This should be a global singleton in your app; it can be passed into the <PlasmicRootProvider/> component, and be used to dynamically fetch component data.

initPlasmicLoader()

This function takes in an object with these keys as the argument:

Specifying project version

By default, PlasmicComponent will fetch and render the latest published version of your project. These published versions have been optimized and will be served over CDNs.

If you want a specific published version instead of the latest published version, you can explicitly specify it like so:

export const PLASMIC = initPlasmicLoader({
  projects: [
    {
      id: '...',
      token: '...',
      version: '2.1.3'
    }
  ]
});

Previewing latest changes during development

During development, however, you may wish to render the latest unpublished changes, instead of the latest published version, so you can see changes in your development server as you make updates in Plasmic studio. In that case, you can pass a preview flag:

export const PLASMIC = initPlasmicLoader({
  projects: [
    {
      id: '...',
      token: '...'
    }
  ],
  preview: true
});

Note that preview: true will take longer and serve less optimized code! Only use this for development.

PlasmicComponentLoader.fetchComponentData()

This method fetches data needed to render the specified components. It takes any number of arguments; each argument can be either:

• A string corresponding to either the name of a component or the path of a page
• An object {name: 'name_or_path', projectId: '...'} if there are multiple components of the same name across different projects.

For example,

const data = await PLASMIC.fetchComponentData('/', 'LoginForm');

The specified components are ‘entrypoints’; components that are used by those entrypoints are automatically included, so you don’t need to provide an exhaustive list of components to fetch.

If you’ve specified a component name that Plasmic doesn’t know about, an error is thrown.

This function returns an object like this:

{
  entryCompMetas: [
    // There's one object here for each entrypoint you
    // specified in your call to fetchComponentData()
    {
      id: "...", // unique identifier
      name: "ComponentName", // normalized name of component
      displayName: "Component Name", // display name of component
      isPage: true, // true if it corresponds to a page
      pageMetadata: {
        // This object exists if isPage is true
        path: "/page", // path for this page

        // The page metadata below can be used to embed into your
        // <head/> tag
        title: "My Page", // title of the page if set
        description: "This is me!", // description of the page if set
        openGraphImageUrl: "...", // url of open graph image
      },
      // Studio users can attach arbitrary key-value metadata to any page/component.
      metadata: {
        isStagingOnly: "true",
        keywords: "seo, search, engine, optimization, rank, pagerank",
        customTargeting: "audience=women, repeatbuyer=true",
        // ...
      }
    }
  ],
  remoteFontUrls: [
    // Remote URLS that can be used to load fonts that you need
    // in your projects.  By default, `PlasmicComponent` will
    // already include the fonts you need, but you can use this
    // information to try to pre-load them in your site if
    // you'd like.
    "https://fonts.google.com/..."
  ],
  bundle: {
    // There is one entry here per project, including projects that are imported dependencies.
    projects: [
      {
        id: "Q62yQ3x2m25QvuUT8iBcZm",
        // true if this was a dependency, false if it was an explicitly requested project
        indirect: false,
        name: "My Project",
        teamId: "yQ3x2m25QvuUT8iBcZmQ62",
        // Maybe a specific version number, or `latest` if in preview mode
        version: "latest"
      }
    ]
  }
}

PlasmicComponentLoader.maybeFetchComponentData()

Same as fetchComponentData(), except if you specify a component name that Plasmic doesn’t know about, null is returned. This is useful in catch-all pages, where you’re not sure if an arbitrary path string corresponds to a Plasmic page or not.

PlasmicComponentLoader.fetchPages()

This fetches all pages that you have defined across your initialized set of projects. This is useful when you want to retrieve a list of pages you want to statically pre-generate HTML for.

PlasmicComponentLoader.substituteComponent()

This function registers an arbitrary React component to swap with a Plasmic component. You can use this to substitute in a real component for a stand-in Plasmic component.

For example,

import Slider from '@material-ui/core/Slider';

// Swap in the real material UI slider
PLASMIC.substituteComponent(Slider, 'Slider');

Unlike .registerComponent(), this does not affect the Plasmic Studio editing experience.

PlasmicComponentLoader.registerComponent()

This function registers an arbitrary React component for use within Plasmic Studio. Plasmic Studio editors will then be able to drag-and-drop these “code components” into their pages and configure their props.

For example,

PLASMIC.registerComponent(ProductCard, {
  name: 'ProductCard',
  props: {
    children: 'slot',
    columns: 'number',
    animate: {
      type: 'boolean',
      defaultValue: true
    },
    category: {
      type: 'choice',
      options: ['success', 'warning', 'error']
    }
  }
});

For code components to work, you need to enable app-hosted Plasmic. See the code components docs and its own API reference to learn more.

Odds and ends

Normally, you’ll see informational logs on each fresh fetch, like:

Plasmic: doing a fresh fetch...
Plasmic: fetched designs for ...
Plasmic: doing a fresh fetch...
Plasmic: fetched designs for ...

You can specify PLASMIC_QUIET=1 as an environment variable to suppress this output.

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