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
CopiedCopy

The output should be the following:

successfully initialized a bit workspace.
CopiedCopy

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.

Configuring Bit to run alongside React application

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}",
CopiedCopy

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

bit install @bitdev/react.react-env
CopiedCopy

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

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

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.

Using package manager directly with Bit in an React project

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"
  }
}
CopiedCopy

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

Using Bit dependency management in an React project

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.

Bit components in an React project

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
...
CopiedCopy

Using Bit components by the local React app

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';
CopiedCopy

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
CopiedCopy

Creating additional apps in an React repository

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
CopiedCopy

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

bit use apps/my-react-app
CopiedCopy

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
CopiedCopy

Multiple types of Bit components in React repository

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
CopiedCopy

And add to workspace.jsonc:

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

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.

Integrating with your existing React project's CI

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