plasmic.json Configuration

This document is all you need to know about what’s required in your plasmic.json file. It must be actual JSON, not just a JavaScript object literal.

Example plasmic.json

Copy
{
  "platform": "react",
  "code": {
    "lang": "ts",
    "scheme": "blackbox"
  },
  "images": {
    "scheme": "files",
  },
  "style": {
    "scheme": "css",
    "defaultStyleCssFilePath": "plasmic/plasmic__default_style.css"
  },
  "tokens": {
    "scheme": "theo",
    "tokensFilePath": "plasmic-tokens.theo.json"
  },
  "srcDir": "./src/components",
  "defaultPlasmicDir": "./plasmic",
  "projects": [
    {
      "projectId": "9pr9hBu15oVRTwBRL9Gnwi",
      "projectName": "Login Page",
      "version": "latest",
      "cssFilePath": "plasmic/login_page/plasmic_login_page.css",
      "components": [
        {
          "id": "mUenpOOz61",
          "name": "LoginPage",
          "type": "managed",
          "projectId": "9pr9hBu15oVRTwBRL9Gnwi",
          "renderModuleFilePath": "plasmic/login_page/PlasmicLoginPage.jsx",
          "importSpec": {
            "modulePath": "LoginPage.jsx"
          },
          "cssFilePath": "plasmic/login_page/PlasmicLoginPage.css",
          "scheme": "blackbox",
          "componentType": "component"
        }
      ],
      "icons": [],
      "dependencies": []
    },
    {
      "projectId": "sxwiVrVtwgyciBtFBrphc5",
      "projectName": "Buttons",
      "version": "^2.0.2",
      "cssFilePath": "plasmic/buttons/plasmic_buttons.css",
      "components": [
        {
          "id": "WNCRIbDI-m",
          "name": "Button",
          "type": "managed",
          "projectId": "sxwiVrVtwgyciBtFBrphc5",
          "renderModuleFilePath": "plasmic/buttons/PlasmicButton.jsx",
          "importSpec": {
            "modulePath": "Button.jsx"
          },
          "cssFilePath": "plasmic/buttons/PlasmicButton.css",
          "scheme": "blackbox",
          "componentType": "component"
        }
      ],
      "icons": [
        {
          "id": "GbOtzqdgr",
          "name": "PlasmicsvgIcon",
          "moduleFilePath": "plasmic/login_page/PlasmicIcon__Plasmicsvg.tsx"
        }
      ]
    }
  ],
  "globalVariants": {
    "variantGroups": [
      {
        "id": "0_5sqO0BtSLgf1",
        "name": "Theme",
        "projectId": "wGm6WRYg9QLZDauuwajumw",
        "contextFilePath": "plasmic/PP__GlobalVariant__Theme.tsx"
      }
    ]
  }
  "cliVersion": "0.1.45"
}

platform

The target platform for generated code. Currently, we support:

  • “react”
  • “nextjs”
  • “gatsby”

It is used to generate code specific to one of these platforms. For example, if “nextjs” or “gatsby” are selected then Plasmic will generate links using their <Link> components.

code

This is where we keep track of code generation options.

code.lang

Target language for code generation. Plasmic currently supports:

  • “ts”: TypeScript
  • “js”: JavaScript

images

This is where we keep track of image options.

images.scheme

How image files should be referenced from generated React components. We currently support:

  • “files”: Images are imported as relative files, like import img from './image.png';
  • “public-files”: Images are stored in a public folder, and referenced from some url prefix, for example: <img src="/static/image.png"/>;
  • “inlined”: Images are inlined directly into React and CSS files as base64-encoded data-URIs;
  • “cdn”: Images are served directly from Plasmic CDN with optimization.

images.publicDir

The folder where static files are stored (only required if using "public-files" scheme). Plasmic-managed image files will be stored as plasmic/project-name/image-name under this folder. The path is relative to srcDir.

images.publicUrlPrefix

The URL prefix from which static files can be referenced (only required if using "public-files" scheme). For example, if publicDir is "public" and publicUrlPrefix is "/static", then an image at public/image.png would be referenced as /static/image.png.

style

This is where we keep track of style generation options.

style.scheme

The scheme to use for styling. Currently, we support:

  • “css”
  • “css-modules”

style.defaultStyleCssFilePath

The target file path for Plasmic to store default styles used across all projects and all components. The path is relative to srcDir. This is a generated file and should not be directly edited.

tokens

This is where we keep track of style token generation options. Style tokens are exported for convenience

tokens.scheme

The scheme used for tokens. Currently we only support:

tokens.tokensFilePath

The target file path for Plasmic to store style tokens. The path is relative to srcDir. This is a generated file and should not be directly edited.

srcDir

The starting path for all other paths in this file. srcDir can be specified either as an absolute path or a relative path. If it is a relative path, it will be relative to the directory where your plasmic.json file is located. All other paths in your plasmic.json file will be specified as relative paths starting at srcDir.

defaultPlasmicDir

New generated files (previously unseen in plasmic.json) will be stored in this directory by default. This path is relative to srcDir.

gatsbyConfig

This is where we store options that are specific to Gatsby when platform is set to “gatsby”.

gatsbyConfig.pagesDir

This is the directory where page files are stored in Gatsby environment. The path is relative to ‘srcDir`.

nextjsConfig

This is where we store options that are specific to Next.js when platform is set to “nextjs”.

nextjsConfig.pagesDir

This is the directory where page files are stored in Next.js environment. The path is relative to ‘srcDir`.

projects

An array of Plasmic projects used.

projects[i].projectId

The unique ID of the project. This field should not be edited.

projects[i].projectName

The readable name of the project defined in Plasmic Studio. We will update this field automatically after each sync.

projects[i].version

Specify a version range for syncing this project. Version ranges are backwards compatible with semver ranges used in npm. Unlike npm, you can also specify a “latest” range.

  • “latest”: Plasmic will generate code for the latest project save as seen in Plasmic Studio. You do not need to publish a project version to use this range.

If you specify a semver range, you must first publish a project version first through the Plasmic Studio. Plasmic will sync the newest publish version that satisfies the range.

  • version: Must match version exactly
  • ~version: “Compatible with version”
    • Developers should expect the component API to remain unchanged, but presentation (e.g. styling, sizing) can change arbitrarily.
  • ^version: “Approximately equivalent to version”
    • Developers should expect the component API to be backwards compatible, but may contain new variants, slots, and/or components.
  • >=version: Must be greater than or equal to version
    • Developers should expect breaking changes to the component API. Variants, slots, and components may have been renamed or deleted. See the Plasmic Studio to see how the interface as changed.
  • >version
  • <=version
  • <version

projects[i].cssFilePath

The target file path for Plasmic to store styles used across all components in the project. The path is relative to srcDir. This is a generated file and should not be directly edited.

projects[i].components

An array of Plasmic components used from the project.

projects[i].components[j].id

The unique ID of the component. This field should not be edited.

projects[i].components[j].name

The readable name of the component defined in Plasmic Studio.

projects[i].components[j].type

Currently the only valid value for this is “managed”.

projects[i].components[j].componentType

The values can be:

  • “component”
  • “page”

projects[i].components[j].projectId

The ID of parent project. This needs to be consistent with the projectId above and should not be changed.

projects[i].components[j].renderModuleFilePath

The target path for the generated file of the presentational component library. The path is relative to srcDir. This file is not meant to be edited directly, as it will be replaced on future syncs.

projects[i].components[j].importSpec.modulePath

The target path for the developer-owned wrapper component. This file is where you add your logic, state, and event handlers for a Plasmic component. The path is relative to srcDir. This file will not be modified unless you change your scheme.

projects[i].components[j].cssFilePath

The target path for Plasmic-generated styles for the component. The path is relative to srcDir. This file is not meant to be edited directly, as it will be replaced on future syncs.

projects[i].icons

You can sync your project’s icons as separate components that can be used in your code. We will only sync and populate this section when you run plasmic sync-icons.

projects[i].icons[j].id

A unique Plasmic-generated identifier for the icon.

projects[i].icons[j].name

The icon’s readable name as specified in Plasmic Studio

projects[i].icons[j].moduleFilePath

The target path for the Plasmic-generated component embodying the icon. The path is relative to srcDir. This file is not meant to be edited directly, as it will be replaced on future syncs.

globalVariants

globalVariants.variantGroups

An array of all global variants groups that are used by sync’ed projects.

globalVariants.variantGroups[i].id

A Plasmic-generated unique identifier for the variant group

globalVariants.variantGroups[i].name

The user-specified name for the variant group. To change, please use Plasmic Studio.

globalVariants.variantGroups[i].projectId

The ID of the parent project where this variant group can be found

globalVariants.variantGroups[i].contextFilePath

The target path for the generated file embodying the variant group. The path is relative to srcDir. This file is not meant to be edited directly, as it will be replaced on future syncs.

cliVersion

The latest CLI version used with this plasmic.json file. You must use a version of the Plasmic CLI that is >=cliVersion. Please do not edit this property, as we use it to automatically migrate your plasmic.json schema to newer versions.

Was this page helpful?

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