Plasmic

https://github.com/gijs-epping/plasmic-docs
Admin
Render content designed in Plasmic into your existing website or web application codebase.
Tokens:149,931
Snippets:968
Trust Score:5.6
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Start the app (npm run dev)

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/hydrogen-quickstart/.md

Command to start the development server. After running, check http://localhost:3000/plasmic-host for a confirmation message.

```bash
npm run dev
```

--------------------------------

### Install @plasmicapp/loader-vue

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/vue-quickstart/.md

Install the Plasmic loader for Vue. Use npm or yarn as shown.

```bash
npminstall@plasmicapp/loader-vue
# or yarn add @plasmicapp/loader-vue
```

--------------------------------

### Install @plasmicapp/loader-gatsby

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/gatsby-quickstart/.md

Install the Plasmic loader for Gatsby using npm or yarn.

```bash
npm install @plasmicapp/loader-gatsby
# or yarn add @plasmicapp/loader-gatsby
```

--------------------------------

### Install dependencies with yarn

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/minitwitter-tutorial/.md

Install dependencies for generating unique IDs, formatting timestamps, and handling routing in the frontend project.

```bash
yarn add uuid moment react-router-dom
yarn add -D @types/uuid @types/react-router-dom @types/react-router
```

--------------------------------

### Start the local development server

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/quickstart-cli.md

Starts the dev server for your new Plasmic project. The server runs at http://localhost:3000 by default. Make sure you've cd'd into the new directory first.

```bash
npm run dev
# or
yarn dev
```

--------------------------------

### Install @plasmicapp/loader-react

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/react-quickstart/.md

Install the Plasmic loader for React using npm or yarn. Use this in an existing React project to begin integrating Plasmic.

```bash
npminstall@plasmicapp/loader-react
# or yarn add @plasmicapp/loader-react
```

--------------------------------

### Install Plasmic Loader for Next.js

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/content-management/.md

Install the @plasmicapp/loader-nextjs package to use Plasmic with Next.js.

```bash
npm install @plasmicapp/loader-nextjs
```

--------------------------------

### Clone and install dependencies for the new Plasmic codebase

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/quickstart-gui/.md

Clones the newly created Plasmic project repository from GitHub and installs its dependencies. Replace <github-username> and <repo-name> with your actual GitHub username and repository name. Use either npm install or yarn to install dependencies.

```bash
git clone git@github.com:<github-username>/<repo-name>.git
cd <repo-name>
npm install
# or
yarn
```

--------------------------------

### Install @plasmicapp/cli globally

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/codegen-guide/.md

Install the Plasmic CLI globally using npm or yarn. Required before using codegen commands.

```bash
npm install -g @plasmicapp/cli
# or: yarn global add @plasmicapp/cli
```

--------------------------------

### Publish API response example

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/plasmic-cms-api-reference/.md

Example response from the publish endpoint, showing the published row with its ID, table ID, timestamps, and data fields.

```json
{
  "id": "387J2rZHouBSQhVdHbKDbY",
  "tableId": "37ZHFaa2oL6L3F6uEpSzCP",
  "createdAt": "2022-05-18T16:32:13.165Z",
  "updatedAt": "2022-05-18T16:32:13.165Z",
  "identifier": null,
  "data": {
    "author": "Anonymous Author",
    "message": {
      "": "Phasellus a massa fermentum, consequat orci at.",
      "ar-JO": "Default Arabic (Jordan) localized message"
    },
    "imageUrl": null
  },
  "draftData": null
}
```

--------------------------------

### Install @plasmicapp/loader-react

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/hydrogen-quickstart/.md

Install the Plasmic loader for React in your Hydrogen project. Use either npm or yarn.

```bash
npm install @plasmicapp/loader-react
# or yarn add @plasmicapp/loader-react
```

--------------------------------

### showModal() example

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/editor-actions/.md

Shows how to display a fullscreen modal with custom content and an onClose callback that fires when the user clicks outside.

```typescript
showModal({
children:<div>This is my modal!</div>,
onClose:()=>alert('Thank you for using this modal.')
});
```

--------------------------------

### Create React App with TypeScript

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/minitwitter-tutorial/.md

Creates a new React app with TypeScript and starts the development server. Use this to set up the project before syncing Plasmic components.

```bash
npx create-react-app minitwitter --typescript
cd minitwitter/
yarn start
```

--------------------------------

### Install @plasmicapp/auth-api

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/auth-integration/.md

Install the @plasmicapp/auth-api package using npm or yarn. The package provides the API for communicating with Plasmic about user authentication status.

```bash
npm install @plasmicapp/auth-api
# or yarn add @plasmicapp/auth-api
```

--------------------------------

### plasmic.lock file example showing project versions and dependencies

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/versioned-sync/.md

Example of a `plasmic.lock` file auto-generated by the Plasmic CLI. It records the synced versions for each project and its dependencies; the main project is set to 'latest' while the imported project is pinned to 5.0.0. Never edit this file manually.

```json
{
  "projects": [
    {
      "projectId": "e3Q1tGtm8oRtjs3qPa4xvQ",
      "version": "5.0.0",
      "dependencies": {}
    },
    {
      "projectId": "9pr9hBu15oVRTwBRL9Gnwi",
      "version": "latest",
      "dependencies": {
        "e3Q1tGtm8oRtjs3qPa4xvQ": "5.0.0"
      }
    }
  ]
}
```

--------------------------------

### Create a simple React component for custom code components (HelloWorld.tsx)

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/react-quickstart/.md

Create a simple example React component to register as a custom code component. This component accepts children, className, and verbose props, and renders a greeting with optional verbose text.

```tsx
import*asReactfrom'react';
exportinterfaceHelloWorldProps{
children?:React.ReactNode;
className?:string;
verbose?:boolean;
}
exportfunctionHelloWorld({children,className,verbose}:HelloWorldProps){
return(
<divclassName={className}style={{padding:'20px'}}>
<p>Hello there!{verbose&&'Really nice to meet you!'}</p>
<div>{children}</div>
</div>
);
}
```

--------------------------------

### Override object props example

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/react-api/.md

Example of an Override object's props property, showing how to pass HTML attributes or component props to the element.

```javascript
{
  props:{
    title:user.name,
    onClick:()=>...,
    // etc.
  }
}
```

--------------------------------

### Install @plasmicapp/loader-angular

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/angular-quickstart/.md

Install the Plasmic loader for Angular. The comment shows the equivalent yarn command. You may need to set skipLibCheck in your tsconfig.json for proper running.

```bash
npm install @plasmicapp/loader-angular
# or yarn add @plasmicapp/loader-angular
```

--------------------------------

### Using the args key to combine slot props

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/angular-api.md

Shows how to combine all slot content into a single 'args' key within componentProps, using the 'children' slot as an example.

```jsx
<PlasmicComponent
  component="Button"
  componentProps={{
    args: {
      children: 'Hello!'
    }
  }}
/>
```

--------------------------------

### Install @plasmicapp/loader-vue

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/nuxt-quickstart/.md

Install the Plasmic loader for Vue/Nuxt using npm or yarn. This is required for Nuxt 3 and Nuxt Bridge, but not Nuxt 2.

```bash
npm install @plasmicapp/loader-vue
# or yarn add @plasmicapp/loader-vue
```

--------------------------------

### Authenticate with Plasmic CLI

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/codegen-guide/.md

Log into the Plasmic CLI to authenticate with Plasmic. Run this after installing the CLI.

```bash
plasmic auth
```

--------------------------------

### Google Fonts CSS @font-face example

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/page-performance/.md

Example of the CSS content returned by Google Fonts, showing @font-face rules with unicode-range. This illustrates the additional font file fetches that occur after the CSS is loaded.

```css
/* cyrillic-ext */
@font-face {
  font-family: 'Roboto';
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url(https://fonts.gstatic.com/s/roboto/v30/KFOmCnqEu92Fr1Mu72xKKTU1Kvnz.woff2) format('woff2');
  unicode-range: U+0460-052F, U+1C80-1C88, U+20B4, U+2DE0-2DFF, U+A640-A69F, U+FE2E-FE2F;
}
/* cyrillic */
@font-face {
  /* ... */
}
/* ... */
```

--------------------------------

### Minimal custom prop control example

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/custom-controls/.md

Shows a code component that renders a prop, a custom control component with a button to update the value, and registration with PLASMIC.registerComponent using type: 'custom'.

```jsx
// A code component that just renders the prop
const CodeComponent = ({customProp, className}) => <div className={className}>{`${customProp}`}</div>;

// A prop control with the value and a button to update it
const CustomProp = ({updateValue, value}) => (
  <div
    style={{
      width: '100%',
      display: 'flex',
      justifyContent: 'space-between',
      padding: '0px 10px 0px 10px'
    }}
  >
    <span>Value: {`${value}`}.</span>
    <button onClick={() => updateValue(!value)} style={{background: 'lightgray', padding: '0px 5px 0px 5px'}}>
      Change
    </button>
  </div>
);

// Registration
PLASMIC.registerComponent(CodeComponent, {
  name: 'CodeComponent',
  props: {
    customProp: {
      type: 'custom',
      control: CustomProp
    }
  }
});
```

--------------------------------

### Export component helpers with initFunc and onChangeArgsToValue

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/code-components-ref/.md

Export component helper functions from a module so generated code can find them. This example defines initFunc and onChangeArgsToValue for a component state named count.

```typescript
export const TextInputHelpers = {
  states: {
    count: {
      initFunc: ($props) => $props.initValue,
      onChangeArgsToValue: (event) => event.target.value
    }
  }
};
```

--------------------------------

### Example custom behavior attachments wrapping children

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/custom-behaviors/.md

Shows three example custom behavior components (OnClickAnalyticsTracker, ParallaxScroll, DataProvider) wrapping arbitrary elements or components to inject behavior or data. Custom behaviors do not render anything themselves; they inject behavior or prop values into their children.

```jsx
// Example: Add an onClick behavior to an arbitrary element or component.
<OnClickAnalyticsTracker>
  <a href='...'/>
</OnClickAnalyticsTracker>

// Add some interactive effects by monitoring the element with IntersectionObserver.
<ParallaxScroll>
  <HeroSection/>
</ParallaxScroll>

// Provide some data to its element.
<DataProvider>
  <Chart/>
</DataProvider>
```

--------------------------------

### GET /api/v1/loader/html/{MODE}/{PROJECTID}/{COMPONENTNAME}

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/render-api.md

Fetches generated HTML for a specific component from Plasmic's servers. Requires authentication via the x-plasmic-api-project-tokens header.

```APIDOC
## GET /api/v1/loader/html/{MODE}/{PROJECTID}/{COMPONENTNAME}

### Description
Fetches generated HTML for a specific component from Plasmic's servers. The mode determines whether the published or preview version of the project is used.

### Method
GET

### Endpoint
https://codegen.plasmic.app/api/v1/loader/html/{MODE}/{PROJECTID}/{COMPONENTNAME}

### Parameters
#### Path Parameters
- **MODE** (string) - Required - Mode should be either `published` or `preview`. If set to published, the latest published version of your project is fetched; in preview mode, the current state of your project is used to generate the HTML.
- **PROJECTID** (string) - Required - The ID of the project where the component is present. You can find the ID by accessing the project in the studio and copying it from the URL.
- **COMPONENTNAME** (string) - Required - The name of the component to fetch, using the same name used in the studio.

### Request Headers
- **x-plasmic-api-project-tokens** (string) - Required - A header containing the project ID and token in the format `PROJECTID:PROJECTTOKEN` to authorize the request.

### Request Example
{
  "x-plasmic-api-project-tokens": "PROJECTID:PROJECTTOKEN"
}

### Response
#### Success Response (200)
Returns the generated HTML for the specified component.

#### Response Example
(HTML content)

```

--------------------------------

### No-op render function example

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/overrides/.md

A no-op render function that returns the component with its props, behaving as if no render function was specified.

```javascript
{
  render: (props, Component) => <Component {...props} />;
}
```

--------------------------------

### GET /api/v1/loader/html/preview/{PROJECTID}/{COMPONENTNAME}

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/js-quickstart/.md

Documentation for the Plasmic Loader REST API endpoint that returns the HTML for a component, with support for server-side data prefetching and customization of props and global variants.

```APIDOC
## [GET] /api/v1/loader/html/preview/{PROJECTID}/{COMPONENTNAME}

### Description
Fetches the HTML for a Plasmic component, with optional server-side data prefetching and customization of component props and global variants.

### Method
GET

### Endpoint
`https://codegen.plasmic.app/api/v1/loader/html/preview/{PROJECTID}/{COMPONENTNAME}`

### Parameters
#### Path Parameters
- **PROJECTID** (string) - Required - The ID of the Plasmic project.
- **COMPONENTNAME** (string) - Required - The name of the component to render.

#### Query Parameters
- **hydrate** (string) - Optional - Set to `1` to enable hydration.
- **embedHydrate** (string) - Optional - Set to `1` to embed the hydration script.
- **prepass** (string) - Optional - Set to `1` to prefetch data on the server.
- **maxAge** (number) - Optional - Cache duration in seconds.
- **componentProps** (string) - Optional - JSON string of an object to override component props.
- **globalVariants** (string) - Optional - JSON string of an array of objects, each with `name` and `value` to specify active global variants.

#### Headers
- **x-plasmic-api-project-tokens** (string) - Required - Format: `PROJECTID:APITOKEN`. Your project ID and public API token.

### Request Example
```
const response = await fetch(
  'https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/COMPONENTNAME?hydrate=1&embedHydrate=1&prepass=1&maxAge=600',
  {
    headers: {
      'x-plasmic-api-project-tokens': 'PROJECTID:APITOKEN'
    }
  }
);
```

### Response
#### Success Response (200)
- **html** (string) - The rendered HTML of the component.

#### Response Example
```
const result = await response.json();
document.body.innerHTML = result.html;
```

### Notes
- The HTML response is cached; changes to fetched content may not be visible until cache expiry. Use `maxAge` or publish a new version to bypass.
- To enable hydration, load and call `window.__plasmicHydrater.hydrateAll()` or include the hydration script.
```

--------------------------------

### Customize component props and global variants using curl

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/rest-quickstart/.md

This curl command sends a GET request with componentProps and globalVariants as query parameters, saves the JSON response to out.json, and extracts the HTML field into out.html using jq.

```bash
curl \
  --header ''x-plasmic-api-project-tokens: PROJECTID:TOKEN'' \
  'https://codegen.plasmic.app/api/v1/loader/html/preview/PROJECTID/Box' -G -d 'hydrate=1&embedHydrate=1&componentProps={"PROP":"VALUE"}&globalVariants=[{"name": "NAME", "value": "VALUE"}]' > out.json
jq .html -r < out.json > out.html
```

--------------------------------

### Registering a component with editor actions

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/editor-actions/.md

Example of registering a code component with two editor actions: a button-action that appends an image element to a slot, and a custom-action that renders a form to create a new tab. The custom-action uses React state and the studioOps.appendToSlot method.

```typescript
PLASMIC.registerComponent(CodeComponent,{
name:'CodeComponent',
props:{
children:'slot'
},
actions:[
{
// Creates a button that, on click, will append a new
// image element to the `children` slot of this
// component instance.
type:'button-action',
label:'Append new element',
onClick:({studioOps})=>{
studioOps.appendToSlot(
{
type:'img',
src:'',
styles:{
maxWidth:'100%'
}
},
'children'
);
}
},
{
type:'custom-action',
control:({studioOps})=>(
// A form that adds a new tab with the given key
const[value,setValue]=React.useState();
return(
<div>
<input
type="text"
value={value}
onChange={e=>setValue(e.target.value)}
placeholder="Tab Key"
/>
<button onClick={()=>{
studioOps.appendToSlot(
{
type:"component",
name:"TabPanel",
props:{
tabKey:value
}
},
"children"
);
}}>Create new tab</button>
</div>
)
)
}
]
});
```

--------------------------------

### Load draft versions of CMS items with draft parameter

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/plasmic-cms-api-reference/.md

Loads the draft version of a CMS item by adding the 'draft' parameter (set to 1 when true) to the query. Based on the previous example, this snippet modifies the URL search parameters to fetch the draft content.

```javascript
// ...
const useDraftVersion = true;
apiUrl.search = new URLSearchParams({
q: JSON.stringify({where:{slug:'my-first-blog-post'},limit:1}),
// Load the Draft version of the blog post
draft: Number(useDraftVersion) // ?draft=1
}).toString();
// ...
```

--------------------------------

### Register custom functions with PLASMIC.registerFunction

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/registering-custom-functions/.md

These examples show how to register custom functions with PLASMIC.registerFunction. The first registers a basic function, the second adds parameter and return value documentation, and the third uses a custom TypeScript declaration for complex types. All functions become accessible in Plasmic Studio with the $$ prefix.

```javascript
import{parseData}from'../data-utils';
// Basic usage
PLASMIC.registerFunction(parseData,{
name:'parseData'
});
```

```javascript
import{isEven}from'some-utility-package';
// Register with param and return value documentation (types, description)
PLASMIC.registerFunction(isEven,{
name:'isEven',
params:[
{
name:'x',
type:'number',
description:'The value to test its evenness'
}
],
returnValue:{
type:'boolean',
description:'Whether `x` is an even number'
}
});
```

```javascript
import{filterData}from'../data-utils';
// Add custom typescript declaration for complex types
PLASMIC.registerFunction(filterData,{
name:'filterData',
description:`Filters the data.
@param data The data to filter
@param opts The options for filtering`,
typescriptDeclaration:`<T>(
data: T[],
opts?: {
/** Maximum number of elements to return */
limit?: number;
/** Options for sorting the data */
sort?: {
field: string;
order: "asc" | "desc";
}
}
): T[]`
});
```

--------------------------------

### Wrapping components with standard contexts

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/custom-controls/.md

Shows how to wrap custom controls with providers because the Studio UI runs in a different document/iframe and app host context is not available.

```jsx
function StandardContexts({children}) {
  return (
    <ThemeProvider>
      <SomeOtherProvider>{children}</SomeOtherProvider>
    </ThemeProvider>
  );
}

function CustomProp1(props) {
  return <StandardContexts>...</StandardContexts>;
}

function CustomProp2(props) {
  return <StandardContexts>...</StandardContexts>;
}
```

--------------------------------

### Create a new Plasmic project with create-plasmic-app

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/quickstart-cli.md

Run this command to generate a new Plasmic-powered website. Supports Next.js, Gatsby, and plain React (with Vite). After running, you'll need to cd into the new app directory.

```bash
npx create-plasmic-app@latest
# or
yarn create plasmic-app
cd <your-new-app-name>
```

--------------------------------

### Auto load all Plasmic pages with Next.js catch-all route

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/nextjs-quickstart/.md

Create a Next.js catch-all page (pages/[[...catchall]].tsx or pages/[...catchall].tsx) to automatically render all Plasmic-defined pages. Uses getStaticPaths with PLASMIC.fetchPages(), getStaticProps with PLASMIC.maybeFetchComponentData() and extractPlasmicQueryData(), and renders via PlasmicRootProvider and PlasmicComponent. Includes incremental static regeneration with revalidate: 300. Requires a plasmic-init file exporting PLASMIC.

```tsx
import * as React from 'react';
import {
  PlasmicComponent,
  ComponentRenderData,
  PlasmicRootProvider,
  extractPlasmicQueryData
} from '@plasmicapp/loader-nextjs';
import { GetStaticPaths, GetStaticProps } from 'next';
import Error from 'next/error';
import { useRouter } from 'next/router';
import { PLASMIC } from '../plasmic-init';

/**
 * Use fetchPages() to fetch list of pages that have been created in Plasmic
 */
export const getStaticPaths: GetStaticPaths = async () => {
  const pages = await PLASMIC.fetchPages();
  return {
    paths: pages.map((page) => ({
      params: { catchall: page.path.substring(1).split('/') }
    })),
    fallback: 'blocking'
  };
};

/**
 * For each page, pre-fetch the data we need to render it
 */
export const getStaticProps: GetStaticProps = async (context) => {
  const { catchall } = context.params ?? {};
  // Convert the catchall param into a path string
  const plasmicPath =
    typeof catchall === 'string' ? catchall : Array.isArray(catchall) ? `/${catchall.join('/')}` : '/';
  const plasmicData = await PLASMIC.maybeFetchComponentData(plasmicPath);
  if (!plasmicData) {
    // This is some non-Plasmic catch-all page
    return {
      props: {}
    };
  }
  // This is a path that Plasmic knows about.
  const pageMeta = plasmicData.entryCompMetas[0];
  // Cache the necessary data fetched for the page.
  const queryCache = await extractPlasmicQueryData(
    <PlasmicRootProvider
      loader={PLASMIC}
      prefetchedData={plasmicData}
      pageRoute={pageMeta.path}
      pageParams={pageMeta.params}
    >
      <PlasmicComponent component={pageMeta.displayName} />
    </PlasmicRootProvider>
  );
  // Pass the data in as props.
  return {
    props: { plasmicData, queryCache },
    // Using incremental static regeneration, will invalidate this page
    // after 300s (no deploy webhooks needed)
    revalidate: 300
  };
};

/**
 * Actually render the page!
 */
export default function CatchallPage(props: { plasmicData?: ComponentRenderData; queryCache?: Record<string, any> }) {
  const { plasmicData, queryCache } = props;
  const router = useRouter();
  if (!plasmicData || plasmicData.entryCompMetas.length === 0) {
    return <Error statusCode={404} />;
  }
  const pageMeta = plasmicData.entryCompMetas[0];
  return (
    // Pass in the data fetched in getStaticProps as prefetchedData
    <PlasmicRootProvider
      loader={PLASMIC}
      prefetchedData={plasmicData}
      prefetchedQueryData={queryCache}
      pageRoute={pageMeta.path}
      pageParams={pageMeta.params}
      pageQuery={router.query}
    >
      {
        // pageMeta.displayName contains the name of the component you fetched.
      }
      <PlasmicComponent component={pageMeta.displayName} />
    </PlasmicRootProvider>
  );
}
```

--------------------------------

### Add Plasmic as a build step

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/build-time-codegen/.md

Build script steps: upgrade Plasmic dependencies, run plasmic sync with --yes --force to auto-answer prompts, then build the site. Plasmic regularly upgrades the minimum required CLI version, so updating dependencies is necessary.

```bash
npm update @plasmicapp/cli @plasmicapp/react-web
npm run plasmic sync --yes --force
npm run build
```

--------------------------------

### GET /api/v1/cms/databases/{CMS_ID}/tables/{modelId}/query

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/plasmic-cms-api-reference/.md

This snippet documents the GET query endpoint for loading a specific CMS item, including optional locale and draft parameters.

```APIDOC
## [GET] https://data.plasmic.app/api/v1/cms/databases/{CMS_ID}/tables/{modelId}/query

### Description
Loads a specific item from a CMS table by filtering on a field value (e.g., `slug`) or by system ID (`_id`). The response contains the item's data and metadata.

### Method
GET

### Endpoint
`https://data.plasmic.app/api/v1/cms/databases/{CMS_ID}/tables/{modelId}/query`

### Parameters
#### Path Parameters
- **CMS_ID** (string) - Required - Your CMS ID from the settings page.
- **modelId** (string) - Required - The model's unique identifier (e.g., `blogPosts`).

#### Query Parameters
- **q** (string) - Required - A JSON string containing the query parameters: `where` (object) to filter by field values (e.g., `slug` or `_id`), `limit` (number) to limit the number of items, and `offset` (number) to skip rows.
- **locale** (string) - Optional - The locale code (e.g., `ar-JO`) to load a localized version of the item.
- **draft** (number) - Optional - Set to `1` to load the draft version of the item.

#### Headers
- **x-plasmic-api-cms-tokens** (string) - Required - The CMS ID and CMS Public API token in the format `${CMS_ID}:${CMS_PUBLIC_TOKEN}`.

### Request Example
```javascript
const CMS_ID = 'YOUR_CMS_ID';
const CMS_PUBLIC_TOKEN = 'YOUR_CMS_PUBLIC_TOKEN';
const modelId = 'blogPosts';
const apiUrl = new URL(`https://data.plasmic.app/api/v1/cms/databases/${CMS_ID}/tables/${modelId}/query`);
apiUrl.search = new URLSearchParams({
  q: JSON.stringify({
    where: { slug: 'my-first-blog-post' },
    limit: 1,
    offset: 0
  })
}).toString();
const response = await fetch(apiUrl.toString(), {
  headers: {
    'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_PUBLIC_TOKEN}`
  }
});
const parsedResponse = await response.json();
const blogPost = parsedResponse.rows[0];
console.log(blogPost);
```

### Response
#### Success Response (200)
- **id** (string) - The system ID of the item.
- **createdAt** (string) - The creation timestamp.
- **updatedAt** (string) - The last update timestamp.
- **identifier** (string) - The human-readable identifier of the item.
- **data** (object) - The item's field values.

#### Response Example
```json
{
  "id": "gN6Dw9h3FM5VRXJDcHsJz4",
  "createdAt": "2022-04-15T17:38:24.101Z",
  "updatedAt": "2022-04-15T17:48:24.101Z",
  "identifier": "Blog Post 1",
  "data": {
    "author": "John Doe",
    "title": "My First Blog Post",
    "slug": "my-first-blog-post",
    "body": "<h2>Lorem Ipsum</h2><p>Donec dignissim ornare magna, ac aliquet erat sodales eu.</p>"
  }
}
```
```

--------------------------------

### initPlasmicLoader()

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/angular-api.md

Initializes a PlasmicComponentLoader instance with project configuration. It accepts an object with projects and optional preview flag.

```APIDOC
## initPlasmicLoader()

### Description
Initializes a PlasmicComponentLoader instance used to load design data from Plasmic. This should be a global singleton in your app.

### Method
Function call

### Endpoint
initPlasmicLoader(options)

### Parameters
#### options (object) - Required
- **projects** (array) - Required - A list of Plasmic projects. Each project is an object with `id` and `token` fields, and optionally a `version` field to pin to a specific published version.
- **preview** (boolean) - Optional - If true, loads the latest unpublished changes. Should only be used for development.

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

### Response
Returns a PlasmicComponentLoader instance.

### Notes
- By default, the latest published version is used. Specify `version` to pin to a specific published version.
- `preview: true` will take longer and serve less optimized code; only use for development.
```

--------------------------------

### fetchPages()

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/vue-api/.md

Fetches all pages defined across the initialized set of projects. Useful for static pre-generation.

```APIDOC
## [GET] /fetchPages

### Description
Fetches all pages that you have defined across your initialized set of projects. Useful when you want to retrieve a list of pages to statically pre-generate HTML for.

### Method
GET

### Endpoint
/fetchPages

### Parameters
None

### Request Example
```
const pages = await PLASMIC.fetchPages();
```

### Response
#### Success Response (200)
- **pages** (array) - List of page paths or metadata.

#### Response Example
```
[
  "/",
  "/about",
  "/contact"
]
```

### Error Handling
- No specific errors documented.
```

--------------------------------

### Create ~/.plasmic.auth file manually

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/development-troubleshooting/.md

Manual creation of the ~/.plasmic.auth file for authentication. The email must match the one used to sign up on Plasmic Studio, and the token can be obtained from your settings.

```json
{
  "host":"https://studio.plasmic.app",
  "user":""EMAIL_HERE"",
  "token":""TOKEN_HERE""
}
```

--------------------------------

### Load all items of a model with Get Items API

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/plasmic-cms-api-reference/.md

Fetches all items from a Plasmic CMS model using the Get Items API. Requires the CMS ID and public token from the CMS settings page, and the model ID from the model schema page. The response contains a rows array with each item's id, timestamps, identifier, and data fields.

```javascript
// Find your CMS ID and Public Token from the settings page.
const CMS_ID = ''YOUR_CMS_ID'';
const CMS_PUBLIC_TOKEN = ''YOUR_CMS_PUBLIC_TOKEN'';
// Find your model's unique identifier from its model schema page.
const modelId = 'testimonials';
// Load all model entries
const response = await fetch(`https://data.plasmic.app/api/v1/cms/databases/${CMS_ID}/tables/${modelId}/query`, {
  headers: {
    // Your CMS ID and CMS Public API token
    'x-plasmic-api-cms-tokens': `${CMS_ID}:${CMS_PUBLIC_TOKEN}`
  }
});
const parsedResponse = await response.json();
console.log(parsedResponse);
const testimonials = parsedResponse.rows;
// ...
```

```json
{
  "rows": [
    {
      "id": "7vfFX4Ywen2fCBkzGH2J3x",
      "createdAt": "2022-03-08T00:57:40.270Z",
      "updatedAt": "2022-03-12T09:04:52.227Z",
      "identifier": "First User",
      "data": {
        "author": "First User",
        "message": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
        "imageUrl": "https://picsum.photos/200/200?image=1"
      }
    },
    {
      "id": "nWsULzngbPha2RLtxAsYaW",
      "createdAt": "2022-03-08T00:57:01.251Z",
      "updatedAt": "2022-03-12T09:05:00.268Z",
      "identifier": "Second User",
      "data": {
        "author": "Second User",
        "message": "Phasellus a massa fermentum, consequat orci at.",
        "imageUrl": "https://picsum.photos/200/200?image=2"
      }
    },
    {
      "id": "hN7Dw8h2FM6VRYJDcGsJyo",
      "createdAt": "2022-03-08T00:57:20.789Z",
      "updatedAt": "2022-04-15T17:48:24.101Z",
      "identifier": "Third User",
      "data": {
        "author": "Third User",
        "message": "Nam viverra dignissim arcu, eget ultrices elit aliquet.",
        "imageUrl": "https://picsum.photos/200/200?image=3"
      }
    }
  ]
}
```

--------------------------------

### refreshQueryData() example

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/editor-actions/.md

Refreshes the fetched data from @plasmicapp/query for all artboards in the editor. Useful after updating source data.

```typescript
refreshQueryData();
```

--------------------------------

### fetchComponentData() return object

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/angular-api.md

Return object shape of fetchComponentData(). Contains entryCompMetas for each entrypoint, remoteFontUrls for preloading fonts, and a bundle with per-project metadata including version and indirect flag.

```json
{
  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"
      }
    ]
  }
}
```

--------------------------------

### GET /api/v1/loader/html/MODE/PROJECTID/COMPONENTNAME

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/render-api.md

Documentation for the Plasmic loader HTML API endpoint, covering hydration and customization query parameters.

```APIDOC
## [GET] /api/v1/loader/html/MODE/PROJECTID/COMPONENTNAME

### Description
Fetches the HTML for a Plasmic component. Supports hydration and customization via query parameters.

### Method
GET

### Endpoint
/api/v1/loader/html/MODE/PROJECTID/COMPONENTNAME

### Parameters
#### Query Parameters
- **hydrate** (integer) - Optional - Default: 0 - Indicates if the API response should include a hydration script that will perform hydration in the response. Without hydration, event listeners aren't attached, which can lead to malfunctioning of the page (e.g., customizable components become unresponsive).
- **embedHydrate** (integer) - Optional - Default: 0 - Defines if the data to be hydrated should be embedded in the response or dynamically fetched during hydration. When embedHydrate=0, initial HTML paint is faster but hydration is slower. When embedHydrate=1, hydration is faster but initial paint is slower.
- **componentProps** (string) - Optional - Props to be passed to the component, as a stringified object. Allows customization of active variants, expected prop values, and slot content (text only).
- **globalVariants** (string) - Optional - Stringified array describing which global variants should be active for the component.

### Request Example
/api/v1/loader/html/MODE/PROJECTID/COMPONENTNAME?hydrate=1&embedHydrate=1&componentProps={}&globalVariants=[]

### Response
#### Success Response (200)
Returns the HTML content for the component, including hydration script if requested.

#### Response Example
(HTML content)
```

--------------------------------

### PLASMIC.registerComponent with actions

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/editor-actions/.md

Example of registering a code component with editor actions, including a button-action and a custom-action that append elements to a slot.

```APIDOC
## PLASMIC.registerComponent

### Description
Registers a code component with Plasmic, including editor actions that appear in the Studio right panel.

### Method
registerComponent

### Parameters
- **component** (ComponentType) - Required - The React component to register.
- **meta** (object) - Required - Metadata including name, props, and actions.
  - **name** (string) - Required - The component name.
  - **props** (object) - Required - The component props, including slots.
  - **actions** (array) - Optional - List of editor actions.
    - **type** (string) - Required - Either 'button-action' or 'custom-action'.
    - **label** (string) - Required for button-action - The button label.
    - **onClick** (function) - Required for button-action - Called with action props.
    - **control** (React component) - Required for custom-action - Rendered in the right panel.

### Example
js
PLASMIC.registerComponent(CodeComponent, {
  name: 'CodeComponent',
  props: { children: 'slot' },
  actions: [
    {
      type: 'button-action',
      label: 'Append new element',
      onClick: ({ studioOps }) => {
        studioOps.appendToSlot({ type: 'img', src: '', styles: { maxWidth: '100%' } }, 'children');
      }
    },
    {
      type: 'custom-action',
      control: ({ studioOps }) => {
        const [value, setValue] = React.useState();
        return (
          <div>
            <input type="text" value={value} onChange={e => setValue(e.target.value)} placeholder="Tab Key" />
            <button onClick={() => {
              studioOps.appendToSlot({ type: 'component', name: 'TabPanel', props: { tabKey: value } }, 'children');
            }}>Create new tab</button>
          </div>
        );
      }
    }
  ]
});

```

--------------------------------

### Sync project with imported dependencies using plasmic sync --projects

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/versioned-sync/.md

Run `plasmic sync` with the `--projects` flag to sync a project and its imported dependencies. The output shows that the imported 'Design System' project is synced at version 5.0.0, while the main project is synced at 'latest', and import statements are fixed automatically.

```bash
$ plasmicsync--projects 9pr9hBu15oVRTwBRL9Gnwi
'Login Page'uses'Design System',whichhas never been synced before. We will alsosync'Design System'@5.0.0.
'Login Page has never been synced before. Syncing...'
Syncing component: Button@5.0.0['Design System'e3Q1tGtm8oRtjs3qPa4xvQ/1gHPDFIEcK>=0.0.0]
Syncing component: LoginPage@latest['Login Page'9pr9hBu15oVRTwBRL9Gnwi/mUenpOOz61 latest]
Syncing icon: TwittersvgIcon@latest['Login Page'9pr9hBu15oVRTwBRL9Gnwi/GbOtzqdgr latest]
Syncing icon: PlusIcon@latest['Login Page'9pr9hBu15oVRTwBRL9Gnwi/qKb6SKUWQu latest]
Fixingimportstatements...
```

--------------------------------

### initPlasmicLoader with preview flag

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/angular-api.md

Initializes the Plasmic loader with preview: true to render the latest unpublished changes during development. Note that this is slower and less optimized, and should only be used for development.

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

--------------------------------

### Primitive Value Comparison Filter

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/plasmic-cms-api-reference/.md

Example of a filter query that directly compares a field to a primitive value (string, number, or boolean).

```json
{
"where":{
"category":"articles"
}
}
```

--------------------------------

### PlasmicComponentLoader.fetchPages()

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/angular-api.md

Fetches all pages defined across the initialized set of projects. Useful for retrieving a list of pages for static pre-generation.

```APIDOC
## `PlasmicComponentLoader.fetchPages()`

### Description
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.

### Method
Not applicable (JavaScript method)

### Response
Returns a list of all pages defined across the initialized projects.
```

--------------------------------

### themeResetClass Prop Type

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/code-components-ref/.md

Documentation for the 'themeResetClass' prop type in Plasmic code components, including usage example and configuration fields.

```APIDOC
## `themeResetClass` Prop Type

### Description
A css class name will be passed in as this prop, which will apply the default styles configured in the Plasmic project, the default tag styles, and also include the definition of all the css variables. This is useful if your code component is rendering content outside of the normal DOM tree via React portals.

The Plasmic Studio user won’t actually see any configuration for this prop; this is purely for your code component to use.

### Usage

```jsx
function Modal({ themeResetClass, className, modalContent }) {
  const [show, setShow] = React.useState(false);
  return (
    <>
      <button className={className} onClick={() => setShow(true)}>
        Show
      </button>
      {ReactDOM.createPortal(<div className={`modal ${themeResetClass}`}>{modalContent}</div>, document.body)}
    </>
  );
}
registerComponent(Modal, {
  name: 'Modal',
  props: {
    modalContent: 'slot',
    themeResetClass: {
      type: 'themeResetClass'
    }
  }
});
```

### Fields

| Field | Required? | Description |
| --- | --- | --- |
| `targetAllTags` | No | By default, the theme reset will only affect DOM rendered by Plasmic. If you also do want to style elements or arbitrary HTML blobs rendered by your code component, then specify `true` for this option. |
```

--------------------------------

### Custom control with FullscreenModal

Source: https://github.com/gijs-epping/plasmic-docs/blob/main/learn/custom-controls/.md

Shows how to use FullscreenModal in a custom control, with a button to open the modal and an onClose callback.

```jsx
const CustomControl = ({FullscreenModal}) => {
  const [open, setOpen] = useState(false);
  return (
    <div
      style={{
        width: '100%',
        display: 'flex',
        justifyContent: 'space-between',
        padding: '0px 10px 0px 10px'
      }}
    >
      <button onClick={() => setOpen(true)} style={{background: 'lightgray', padding: '0px 5px 0px 5px'}}>
        Edit
      </button>
      <FullscreenModal show={open} onClose={() => setOpen(false)}>
        <div>More UI here!</div>
        <button onClick={() => setOpen(false)}>Close</button>
      </FullscreenModal>
    </div>
  );
};
```
Tokens:
Raw