Versioned Sync

Using version ranges during sync

It can often be helpful to limit which version of a project you pull down, whether using PlasmicLoader or plasmic sync—for example, if a designer is making changes in Plasmic Studio that are not ready for use in code yet, or to limit syncing to changes that are semantic-version-compatible with the code.

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

PlasmicLoader

In the list of projects:

{
  ...
  "projects": [
      {
        "id": "9pr9hBu15oVRTwBRL9Gnwi",
        "token": "PRORJECT_TOKEN",
        "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 imported projects 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"
      }
    }
  ]
}

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