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

{
  "platform": "react",
  "code": {
    "lang": "ts",
    "scheme": "direct"
  },
  "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"
        }
      ],
      "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"
        }
      ],
      "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 only support:

  • “react”

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

code.scheme

Plasmic currently supports 2 APIs to interact with generated code.

  • “blackbox”: Blackbox scheme for a clean boundary to generated presentational components
  • “direct”: Direct Edit scheme for a transparent JSX tree that you can directly manipulate

style

This is where we keep track of style generation options

style.scheme

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

  • “css”

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.

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].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].components[j].scheme

You can override the scheme used for an individual component. Plasmic currently supports 2 APIs to interact with generated code.

  • “blackbox”: Blackbox scheme for a clean boundary to generated presentational components
  • “direct”: Direct Edit scheme for a transparent JSX tree that you can directly manipulate

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.