Migrating from a previous version of Bit

Bit v15 (Harmony) and Bit v14 are mutually incompatible. To take advantage of Harmony's new features and capabilities, you need to migrate your workspace and collections manually.

First, let's go through the fundamental changes between the legacy version of Bit and Harmony:

Component structure - Harmony is opinionated when it comes to structuring components in the file system. Each component must be in its own directory.
Dependencies - Harmony doesn't allow relative import statements between components. Each Bit component always has a local, compiled module in node_modules - use them for all Bit component import statements in your code.
Environments - Harmony features a new approach for compilers/testers called envs.
Configuration - In harmony config is managed in a new file format - workspace.jsonc.
Module names - In harmony we removed the @bit prefix, and instead components are now pre-fixed by @<account_name>.
Scopes - Collections in v15 are called Scopes.
Documentation - Component docs is now a local development workflow feature using MD/MDX formats.
Live playground - Live component playground is now a local development workflow feature and not managed in bit.cloud

One of the main leaps forward in Harmony is that it is extremely extendible - so Harmony's feature set is constantly expanding.
That said, here's a sample of the major new features that have been introduced with Harmony:

• Component Development Environments Shareable components which contain configurations for the full component lifecycle, to both reduce environment setup time and to introduce component development standardization across the organization
• Documentation Use .docs. files to document your components at source
• Compositions Use .compositions. files to demonstrate and illustrate your component with its variants and inside complex application contexts, all rendered as part of your component's documentation
• Ripple CI Propagating CI along the dependency tree, so you know how changes upstream will affect dependents, even before they adopt the changes

There are strict limitations regarding using both v14 and v15

• v14 components can't depend on v15 and vice-versa.
• v14 and v15 components can't live in the same scope.
• You must run two installations of Bit with different binary-names for using v14 and v15 simultaneously. Learn more
• You can't have the same local workspace with both v14 and v15 content in .git/bit directory.

The rest of the migration flow will assume that bit points to your Harmony installation. If the version of bit -v begins with 14.x.x then you likely have bbit as the alias for the Harmony version of bit. Run bbit -v to check, and if you get a 0.0.xxx version then you should substitute all bit commands to bbit.

Now that we've outlined the above, the major steps required to migrate components over from using legacy versions of Bit (14-) to Harmony are as follows (details for each below).

Harmony and legacy workspaces are mutually incompatible, and a repo ain't big enough for the two of them. So to now work in a Harmony workspace you have to reset your Bit workspace, as follows (we recommend cloning the current repo and Harmony-ising the clone):

1. If you are maintaining your legacy Bit workspace, clone your repository.
2. Create a new branch for Harmony migration.
3. Remove all bit-related files and directories from your project and re-initialise as a Harmony workspace - bit init --reset-hard.

Check that you have a .bitmap and workspace.jsonc files in your workspace, and that there is no bit section in your package.json file. If that's the case, then congratulations you have converted over to a Harmony bit workspace.

As v15 mandates a structure where components are grouped in separate directories, you may need to restructure the codebase to fit this rule. Once done, use bit add to track components.

Note that now each component in the workspace has a node_module folder under @your-org with its component ID. You can use it when importing components as dependencies.

Our workspace documentation details exactly how to configure your workspace.jsonc file to set environments, dependency configurations and more, as required. It is important to configure defaultScope correctly in variants, as this defines the target remote scope for each component.

A major new introduction in Harmony is the [Component Development Environment (envs). While in the past you would select a single compiler, tester, etc for your entire workspace, now all component life-cycle processes (compilation, linting, testing, etc) are managed by the Environment, and all configurations for these environments are customizable.

What this means is that a first step for migrating over your components is setting up the development Environment - either by simply selecting the relevant base Environment that Bit supplies (react, node, react-native for now), or by extending these base Environments with your own configuration files (e.g. tsconfig).

Once you have the components tracked in your Bit workspace and have configured the relevant environment for them in the workspace's variants section run:

bit start
Copied

This starts the local development server. See that components can render, add docs, compositions and live playground examples as needed.

It's recommended to start with creating a different set of scopes for this flow when you get started, as you can't create Harmony scopes with the same names as existing v14 collections.

Head over to bit.cloud and create the required set of scopes for your setup.

Versioning workflow works just the same. Use bbit tag --all to version your components and set them to be exported.

Export your components to their predefined scopes by running the bbit export command without setting a target scope.
In Harmony the target scope is defined in workspace.json using variants, per the configuration step.