Bit in an existing React project

Using Bit in an existing React project allows you to manage independently versioned and released React components, hooks and more in the same repository as any React project. This means you can quickly share them as Bit Components with any other project.
You can also build non-React components, like modules, entities or any JavaScript/TypeScript based functionality you deem reuseable.

To use Bit in an existing React repository and run:

bit init
Copied

The output should be the following:

successfully initialized a bit workspace.
Copied

You have successfully added Bit support to your React project!
See the two generated file; workspace.jsonc, which includes all Bit related configuration, and .bitmap which tracks the Bit components in the workspace. Make sure to add and commit these files to your repository.

You should create a separate directory tree for your Bit components and apps. Open the workspace.jsonc file and add any prefix to the defaultDirectory configuration. For example:

"defaultDirectory": "bit-components/{scope}/{name}",
Copied

Now you need to install and set up the React plugin.
Start with installing the plugin:

bit install @bitdev/react.react-env
Copied

Now edit your worksapce.jsonc and add the React component generator.

{
  "teambit.generator/generator": {
    "envs": ["bitdev.react/react-env"]
  }
}
Copied

Note - at this point we recommend reading through the Introduction to Bit and React.

You can decide if you want to use Bit's capabilities for dependency management, or directly use a package manager.

If you decided to use package manager directly for dependency management ensure you do not use bit install in your workflow and you do not have any dependencies in the workspace.jsonc file (if you have any, move them to package.json).

Add the following script to your package.json:

{
  "scripts": {
    "postinstall": "bit import && bit compile && bit link"
  }
}
Copied

Note - the automated dependency detection and definition for components is still supported.

Bit support pnpm and yarn for dependency management and respects configuration applied via package.json. This makes it easy to simply adopt bit install and your dependency management tool.
We recommend moving all dependencies from package.json to workspace.json. You may keep all your scripts and can still run binaries.

Note - if you are using npm now, the only difference for you will feel is pnpm or yarn installing and managing your node_modules.

Now that you have Bit in your React repository, you can run any Bit commands to manage components:

bit templates // see all available templates you can use
bit create    // create a new component
bit start     // start the bit local dev-server
bit list      // list all components in the workspace
...
Copied

All components are linked to the local node_modules. In you need to use a Bit component in your React app, use the module link:

import { anotherBitComponent } from '@my-org/my-scope/another-bit-component';
Copied

To ensure the compiled outputs of components is up-to-date in node_modules, you need to run one of the following processes:

bit watch // runs component-compilation in a watch mode, ensure compiled node-modules for components are up-to-date
bit start // runs bit-devserver which also ensures compiled node-modules for components are up-to-date
Copied

With Bit you can create additional apps in your React repository.
To create a new app, simply choose the react-app template when creating a new component:

bit create react-app apps/my-react-app
Copied

Then add it to your workspace.jsonc configuration with the bit use command:

bit use apps/my-react-app
Copied

Now you can use the following application-workflow commands:

bit app list    // lists all available Bit apps in the repository
bit run <name> // runs a Bit app in a separate dev-server
Copied

A Bit component is isolated from the build of the repository it is in, which means you can manage components of different types. For example, you can add Angular or Vue components to be built alongside your React components, if you so please.
To do so, you only need to include additional plugins to the workspace:

bit install bitdev.angular/angular-env
Copied

And add to workspace.jsonc:

{
  "teambit.generator/generator": {
    "envs": ["bitdev.react/react-env", "bitdev.angular/angular-env"]
  }
}
Copied

note - this does not mean you can use components of different framework in the same app. for this there are other tools and practices to adopt, like MFE.

As you probably have a working and custom delivery pipeline, it is hard to provide a simple way to integrate Bit release pipeline that "will just work". Please use the following as a reference for incorporating Bit scripts in your pipeline:

• When new PR is submitted
  • Developers should run bit tag --soft on their local to mark the modified components to be versioned and released. This modifies .bitmap with updates for components. You can review these changes as part of the PR flow.
  • On CI add the bit build command to run isolated build pipeline for all modified components.
• When PR is merged
  • Add bit tag --persist && bit export to apply changes in .bitmap on the components and release them.
  • Add a "commit back" to the changes in .bitmap file and re-push it to the repository

You can also build a more advanced flow using the Bit's pre-made CI scripts, as reference.

• When new PR is submitted
  • On CI add the bit lane create && bit snap && bit export command to run isolated build pipeline for all modified components and publish a new lane with all component-changes.
• When PR is updates
  • On CI add the bit snap && bit export to update the modified components.
• When PR is merged
  • Add bit tag && bit export to release new versions for the components.
  • Add a "commit back" to the changes in .bitmap file and re-push it to the repository