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:

ArgumentDescription
projectsA list of Plasmic projects you are using for your application. Each project should look like: an object with an id and a token field. You can also optionally pass in a version field to pin it to a specific published version.

To find your project’s ID and public API token: open the project in Plasmic Studio.

The project ID is in the URL, like: https://studio.plasmic.app/projects/PROJECTID.

The public API token can be found by clicking the Code toolbar button.

previewBy default, Plasmic will always use the most recently published version of your projects. If instead you want to see the latest unpublished changes in your projects, you can pass in the preview: true. Note that this should only be used for development! Learn more about supporting previews in your app.

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:

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

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

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

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

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

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

Give feedback on this page