Version Control Workflows

We designed Plasmic to easily fit into your version control and collaboration workflows. That means Plasmic components should be easily imported into your existing code, built by your existing build system, and checked in using your existing source code management tool. That also means that you own your code.

What should I check in?

To start, make sure you check in your plasmic.json and plasmic.lock file so that others share the same configuration.

plasmic sync updates your Plasmic components to the latest versions from the corresponding Plasmic project. After you synchronize, be sure to fix any errors and test your code before checking all files in. Usually you will see Typescript errors that inform you explicitly of breaking changes in the upstream Plasmic project.

Because the files are checked into source code management, other collaborators do not need to run plasmic sync unless they plan on updating Plasmic components.

Do not check in your .plasmic.auth file, which contain user-specific secrets for authenticating with Plasmic servers. This is typically located in your home directory, so usually is not in your version controlled project directory.

Historical versions

When plasmic sync updates any component, it also records the specific version number of that component into plasmic.lock. Thus, when you later check out any historical commit, you can always view the corresponding version of the Plasmic component in Plasmic as well.

Resolving conflicts

When merging or rebasing branches of your codebase, where both branches have synced the same set of components, you will encounter conflicts in Plasmic component files, just as you will with any file that was changed in both branches.

However, because Plasmic serves as your single source of truth for those components, you can safely overwrite any files in the presentational component library (e.g. PlasmicButton.tsx, PlasmicButton.css, etc.—in short, all the files in plasmic/) with the latest from plasmic sync.

You will still need to manually resolve conflicts on the developer-owned wrapper components (e.g. Button.tsx in src/), where the application logic, state, and event handlers are specified—this is as you would with any traditionally written components.

Parallel feature development

Currently, it can be a challenge to work on 2 different features concurrently in the same Plasmic project. For example, suppose feature A is in-progress but feature B is complete. A developer might sync the project to get the results of feature B in code. However, the sync would also pull down any in-progress work of feature A.

If this problem affects you, please reach out to us at team@plasmic.app. Your feedback will help us design a workflow that suits your needs.

Current workarounds include:

  • If the in-progress work is a new component, there is no harm to sync components that are unused in code.
  • If the in-progress work modifies an existing component, you can hide the changes behind a variant.
  • If the above approaches do not work, you can always separate new in-progress features into separate projects.
    • Note: there is currently no easy way to merge two Plasmic projects