React

Check out the React Aspect on Bit.dev

The built-in React Component Development Environment is a concrete composition of the Env Aspect. It compose different tools and configs that fit practices implemented in Create React App. Use it when getting started with React components with Bit and later as a base for any future customization of your React-based workflow.

Use React environment

To use this environment for your components, add it to any of the variants in your workspace.jsonc file as follows:

workspace.jsonc

{  "teambit.workspace/variants": {    "some/path": {      "teambit.react/react": {}    }  }}

Create React components

React implements several component templates:

• react-component a basic React UI component.
• react-context a react context component.
• react-hook a react hook component.
• mdx-component an MDX component.
• react-component-js a basic React component in JS.
• react-env boilerplate for a customized environment configuration.

Use any of these templates with the bit create command:

bit create <template name> [components...]

Runtime (framework) dependencies

As with many Frontend frameworks React requires a singleton instance in your app's runtime. When building reuseable components that means setting react and react-dom as peerDependencies, thus allowing the consuming app to determine the runtime version. Bit's base React environment implements this via the Dependencies service which is used to override dependency-resolver and set your preferred dependencies. It is recommended for you to extend the base React environment and define a semantic version rule and range to fit your current tech stack and guidelines for reuseable React components.

Development services

React, like all other Bit Environments must implement a set of Service Handlers. Each service corresponds to a specific tool or stage in the component life-cycle, with a default config as set by the base React environment:

Service	Aspect	Base Configuration
Compilation	TypeScript	tsconfig.json
Testing	Jest	jest.config.js
Linting	ESLint	eslintrc.ts
DevServer	Webpack	webpack.config.preview.dev.ts
Preview (simulation)	Webpack	webpack.config.preview.ts
Package	PKG	Base package.json props from TypeScript Aspect
Bundling	Webpack	webpack.config.preview.ts
Documentation	Core implementation	Docs template
Build pipeline	Builder	Build pipeline
Dependencies	Core implementation	Env-dependencies
Component Generator	Generator	example template

Customize environment

All environments are extendible. You can take any pre-existing environment, and create a component to extend it, creating a customized environment. That customized environment can use APIs from the environment it is extending to:

• Override default configurations.
• Replace composed tools with others (for example - use Babel to transpile instead of TypeScript).
• Add new services and capabilities.

Create an extension

The first step is to create a component that extends React. Use the react-env template from React env.

bit create react-env extensions/custom-react

As with any component, environments must themselves have an environment which compiles, builds, transpiles, etc, them. Bit has a special environment that knows how to create other environments - teambit.harmony/aspect. So for any component that is meant to be a Bit environment, you must set teambit.harmony/aspect as the environment for that component.

add variant for the extension and set the aspect env

{  //...  "teambit.workspace/variants": {    //...    "extensions/custom-react": {      "teambit.harmony/aspect": {}    }    //...  }}

Validate the above by running bit env and see that the extension-component has teambit.harmony/aspect set as its environment.

Now that you have a basic customized extension to start from, you can go ahead and configure it for your components in workspace.json:

edit variants and set the new env

{  //...  "teambit.workspace/variants": {    //...    "[some]/[variant]": {      "[yourscope]/extensions/custom-react": {}    }    //...  }}

Customize configuration

React implements a set of APIs you can use to merge your preferred configuration with its defaults. These APIs are called transformers and they all start with the override pre-fix. Find Available transformers here. In case of a conflict, your config will override the default.

Customized TypeScript configuration

import { EnvsMain, EnvsAspect } from '@teambit/envs';import { ReactAspect, ReactMain } from '@teambit/react';
const tsconfig = require('./typescript/tsconfig.json');
export class CustomReactExtension {  constructor(private react: ReactMain) {}
  static dependencies: any = [EnvsAspect, ReactAspect];
  static async provider([envs, react]: [EnvsMain, ReactMain]) {    const customReactEnv = react.compose([react.overrideTsConfig(tsconfig)]);
    envs.registerEnv(customReactEnv);
    return new CustomReactExtension(react);  }}

To override any specific configuration it's recommended to create a separate config file with your customized configuration and import it into the main .extension.ts file where you can supply it to the relevant transformers. See the tsconfig example in the above snippet.

Composing tools and services

Environments use Environment Services by implementing a special class of methods called Service Handlers. The supplied transformers allow overriding of these services - for instance the overrideCompiler transformer allows overriding the environment's getCompiler() method.

The below example uses the overrideCompiler transformer to override the getCompiler() Service Handler to change the compilation service.

1. Add a Babel config file to your custom environment and import/require it in your .extension file
2. Create a new Babel compiler using the Babel aspect, and initialize it with the above babelConfig
3. Use the compose Env API to apply the compiler override transformer and add Babel as a transpiler in the environment

import { EnvsMain, EnvsAspect } from '@teambit/envs';import { ReactAspect, ReactMain } from '@teambit/react';import { BabelAspect, BabelMain } from '@teambit/babel';
const babelConfig = require('./babel/babel.config');
export class CustomReactExtension {  constructor(private react: ReactMain) {}
  static dependencies: any = [EnvsAspect, ReactAspect, BabelAspect];
  static async provider([envs, react, babel]: [EnvsMain, ReactMain, BabelMain]) {    const babelCompiler = babel.createCompiler({      babelTransformOptions: babelConfig,    });
    const customReactEnv = react.compose([      react.overrideCompiler(babelCompiler),      react.overrideCompilerTasks([babelCompiler.createTask()]),    ]);
    envs.registerEnv(customReactEnv);    return new CustomReactExtension(react);  }}

Transformers API docs

Use these APIs to customize the base React environment default configuration with your extension. Read more here.

overrideTsConfig(tsconfig: TsConfigSourceFile): EnvTransformer

Merges the environment's default TypeScript configuration with the contents of your typescript configuration file. This config affects the transpilation carried out when rendering components on the local dev UI. To override the config used when building components, use overrideBuildTsConfig below.

// ...const tsconfig = require('./typescript/tsconfig.json');export class ReactExtension {// ...
  static async provider([envs, react]: [EnvsMain, ReactMain]) {    const newReactEnv = react.compose([      react.overrideTsConfig(tsconfig)    ]);}// ...

overrideBuildTsConfig(tsconfig: TsConfigSourceFile): EnvTransformer

Merges the environment's default TypeScript configuration with the contents of your typescript configuration file. This config affects transpilation of component code during the build process, i.e. in preparation for packaging and exporting the component. To override the local ts config used when rendering components in the local UI, please use overrideTsConfig above.

// ...const tsconfig = require('./typescript/tsconfig.json');export class ReactExtension {// ...
  static async provider([envs, react]: [EnvsMain, ReactMain]) {    const newReactEnv = react.compose([      react.overrideTsConfig(tsconfig)    ]);}// ...

overridePreviewConfig(config: Configuration): EnvTransformer

Merges the Webpack configuration for the 'Preview' environment service, with the contents of your webpack configuration file. This webpack configuration is used for building and rendering your components for production (during bit tag or bit build).

// ...const webpackConfig = require('./webpack/webpack.config');export class ReactExtension {// ...  static async provider([envs, react]: [EnvsMain, ReactMain]) {    const newReactEnv = react.compose([      react.overridePreviewConfig(webpackConfig)    ]);}// ...

overrideDevServerConfig(config: Configuration): EnvTransformer

Merges the Webpack configuration for the 'DevServer' environment service, with the contents of your webpack configuration file. This configuration is used for building and rendering your components in the local dev server.

// ...const webpackConfig = require('./webpack/webpack.config');export class ReactExtension {// ...  static async provider([envs, react]: [EnvsMain, ReactMain]) {    const newReactEnv = react.compose([      react.overrideDevServerConfig(webpackConfig)    ]);}// ...

overrideJestConfig(jestConfigPath: string): EnvTransformer

Merges the default configuration for the Jest test runner with the contents of your (jest.config configuration file).

// ...const jestConfig = require.resolve('./jest/jest.config');export class ReactExtension {// ...  static async provider([envs, react]: [EnvsMain, ReactMain]) {    const newReactEnv = react.compose([      react.overrideJestConfig(jestConfig)    ]);}// ...

overrideBuildPipe(tasks: BuildTask[]): EnvTransformer

This method receives an array of build tasks. It merges the provided tasks with the environment's default build pipeline (initiated either on a bit tag or bit build command).

// ...// Import the taskimport { CustomTask } from './custom.task';export class CustomReact {  // ...  static async provider([envs, react]: [EnvsMain, ReactMain]) {    // Get the environment's default build pipeline using the 'getBuildPipe' service handler    const reactPipe = react.env.getBuildPipe();    // Add the custom task to the end of the build tasks sequence.    const tasks = [...reactPipe, new CustomTask()];    const newReactEnv = react.compose([react.overrideBuildPipe(tasks)]);    // ...  }}

overrideDependencies(dependencyPolicy: DependenciesPolicy): EnvTransformer

This method receives a dependency-policy object and merges it with the environment's default dependency policy for components using this environment. Each key-value pair in a dependency-policy object signifies the package and the version to be used. Use also the - and + notation to signify a module should moved between dependency types (dev, peer or standard).

// ...const newDependencies = {  dependencies: {    react: '-',  },  devDependencies: {    '@types/jest': '~26.0.9',  },  peerDependencies: {    react: '^17.0.2',  },};
export class CustomReact {  // ...  static async provider([envs, react]: [EnvsMain, ReactMain]) {    const newReactEnv = react.compose([react.overrideDependencies(newDependencies)]);    // ...  }}

The above example shows the 'React' library being removed as a (runtime) dependency and added as a peer dependency.

overridePackageJsonProps(props: PackageJsonProps): EnvTransformer

Merges the provide props with the default properties added to the package.json file of every package generated from components using this environment.

// ...const newPackageProps = {  main: 'dist/{main}.js',  types: '{main}.ts',};
export class CustomReact {  // ...  static async provider([envs, react]: [EnvsMain, ReactMain]) {    const newReactEnv = react.compose([react.overridePackageJsonProps(newPackageProps)]);    // ...  }}