Versioned Sync

Using version ranges during sync

It can often be helpful to limit which version of a project you pull down when running plasmic sync—for example, if a designer is making changes in Plasmic Studio that are not ready for use in code yet.

Once you have published versions of a project, you can set any valid semantic version range in your plasmic.json file. For example, setting the version to “>=0.0.0” will retrieve the newest published version of a project, neglecting any unpublished changes.

plasmic.json:

{
  ...
  "projects": [
      {
        "projectId": "9pr9hBu15oVRTwBRL9Gnwi",
        "projectName": "Login Page",
        "version": ">=0.0.0"
  ...
}

Semantic versions

When publishing a project version, the version numbers will be automatically calculated by Plasmic (e.g. 0.1.2). These version numbers primarily hold meaning when developers sync components down to code.

  • Major version numbers: The first part of the version is the “major” version (i.e. “0” from “0.1.2”). When this increments, it indicates a change that could result in breaking a developer’s code build, such as when components, variants, slots, or style tokens are renamed or deleted.
  • Minor version numbers: The middle part of the version is the “minor” version (i.e. “1” from “0.1.2”). When this increments, it indicates new components, variants, slots, and/or style tokens that can now be used by the developer, but no breaking changes.
  • Patch version numbers: The last part of the version is the “patch” version (i.e. “2” from “0.1.2”). This will increment on any changes that do not affect the component’s code interface. (e.g. changing styles or layout)
  • For more information, see semantic versioning.

Syncing imported projects

By default, plasmic sync will pull down any cross-project dependencies to your working directory.

Let’s say I created a LoginPage component in my project that uses an imported Button. When I sync down the project containing LoginPage, I should also automatically sync the required Button from the dependency project.

$ plasmic sync --projects 9pr9hBu15oVRTwBRL9Gnwi
'Login Page' uses 'Design System', which has never been synced before. We will also sync '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]
Fixing import statements...

Voila! 😎

plasmic.lock files

The Plasmic CLI will auto-generate plasmic.lock files. You should never edit these files manually, but you can inspect them to see what versions exist on disk after sync.

What does “latest” mean?

“latest” is an unstable version. It effectively means that we retrieved the latest unpublished data seen on Plasmic Studio at the time of sync. This can be helpful when you are iteratively developing components (e.g. using plasmic watch). By default, we will set the version to “latest” the first time you sync a new project using the CLI and its dependencies are synced to the exact version imported.

plasmic.lock:

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