|
| 1 | +# Build a React Native library |
| 2 | + |
| 3 | +When code is in non-standard syntaxes such as JSX, TypeScript etc, it needs to be compiled before it can run. Configuring this manually can be error-prone and annoying. `react-native-builder-bob` aims to simplify this process by wrapping `babel` and `tsc` and taking care of the configuration. See [this section](./faq.md#why-should-i-compile-my-project-with-react-native-builder-bob) for a longer explanation. |
| 4 | + |
| 5 | +Supported targets are: |
| 6 | + |
| 7 | +- Generic CommonJS build |
| 8 | +- ES modules build for bundlers such as [webpack](https://webpack.js.org) |
| 9 | +- [TypeScript](https://www.typescriptlang.org/) definitions |
| 10 | +- Flow definitions (copies .js files to .flow files) |
| 11 | + |
| 12 | +If you created a project with [`create-react-native-library`](./create.md), `react-native-builder-bob` is **already pre-configured to build your project**. You don't need to configure it again. |
| 13 | + |
| 14 | +The following configuration steps are for projects not created with `create-react-native-library`. |
| 15 | + |
| 16 | +## Automatic configuration |
| 17 | + |
| 18 | +To automatically configure your project to use `react-native-builder-bob`, open a Terminal and run: |
| 19 | + |
| 20 | +```js |
| 21 | +npx react-native-builder-bob@latest init |
| 22 | +``` |
| 23 | + |
| 24 | +This will ask you a few questions and add the required configuration and scripts for building the code. You can find details on what exactly it adds in the [Manual configuration](#manual-configuration) section. |
| 25 | + |
| 26 | +## Manual configuration |
| 27 | + |
| 28 | +To configure your project manually, follow these steps: |
| 29 | + |
| 30 | +1. First, install `react-native-builder-bob` in your project. Open a Terminal in your project, and run: |
| 31 | + |
| 32 | +```sh |
| 33 | +yarn add --dev react-native-builder-bob |
| 34 | +``` |
| 35 | + |
| 36 | +1. In your `package.json`, specify the targets to build for: |
| 37 | + |
| 38 | + ```json |
| 39 | + "react-native-builder-bob": { |
| 40 | + "source": "src", |
| 41 | + "output": "lib", |
| 42 | + "targets": [ |
| 43 | + "commonjs", |
| 44 | + "module", |
| 45 | + "typescript", |
| 46 | + ] |
| 47 | + } |
| 48 | + ``` |
| 49 | + |
| 50 | + See the [Options](#options) section for more details. |
| 51 | + |
| 52 | +1. Add `bob` to your `prepare` or `prepack` step: |
| 53 | + |
| 54 | + ```js |
| 55 | + "scripts": { |
| 56 | + "prepare": "bob build" |
| 57 | + } |
| 58 | + ``` |
| 59 | + |
| 60 | + Note that there is a difference between `prepare` and `prepack` scripts: |
| 61 | + |
| 62 | + - `prepare` is run when the package is published, as well as when its is installed from a git URL. It may also run when dependencies are installed based on the package manager. |
| 63 | + - `prepack` only runs when the package is packed for publishing. |
| 64 | + |
| 65 | + If you are not sure which one to use, we recommend going with `prepare`. |
| 66 | + |
| 67 | +1. Configure the appropriate entry points: |
| 68 | + |
| 69 | + ```json |
| 70 | + "main": "lib/commonjs/index.js", |
| 71 | + "module": "lib/module/index.js", |
| 72 | + "react-native": "src/index.ts", |
| 73 | + "types": "lib/typescript/src/index.d.ts", |
| 74 | + "source": "src/index.ts", |
| 75 | + "files": [ |
| 76 | + "lib", |
| 77 | + "src" |
| 78 | + ] |
| 79 | + ``` |
| 80 | + |
| 81 | + Here is what each of these fields mean: |
| 82 | + |
| 83 | + - `main`: The entry point for the commonjs build. This is used by Node - such as tests, SSR etc. |
| 84 | + - `module`: The entry point for the ES module build. This is used by bundlers such as webpack. |
| 85 | + - `react-native`: The entry point for the React Native apps. This is used by Metro. It's common to point to the source code here as it can make debugging easier. |
| 86 | + - `types`: The entry point for the TypeScript definitions. This is used by TypeScript to type check the code using your library. |
| 87 | + - `source`: The path to the source code. It is used by `react-native-builder-bob` to detect the correct output files and provide better error messages. |
| 88 | + - `files`: The files to include in the package when publishing with `npm`. |
| 89 | + |
| 90 | + Make sure to change specify correct files according to the targets you have enabled. |
| 91 | + |
| 92 | + **NOTE**: If you're building TypeScript definition files, also make sure that the `types` field points to a correct path. Depending on the project configuration, the path can be different for you than the example snippet (e.g. `lib/typescript/index.d.ts` if you have only the `src` directory and `rootDir` is not set). |
| 93 | + |
| 94 | +1. Add the output directory to `.gitignore` and `.eslintignore` |
| 95 | + |
| 96 | + ```gitignore |
| 97 | + # generated files by bob |
| 98 | + lib/ |
| 99 | + ``` |
| 100 | + |
| 101 | + This makes sure that you don't accidentally commit the generated files to git or get lint errors for them. |
| 102 | + |
| 103 | +1. Add the output directory to `jest.modulePathIgnorePatterns` if you use [Jest](https://jestjs.io) |
| 104 | + |
| 105 | + ```json |
| 106 | + "modulePathIgnorePatterns": ["<rootDir>/lib/"] |
| 107 | + ``` |
| 108 | + |
| 109 | + This makes sure that Jest doesn't try to run the tests in the generated files. |
| 110 | + |
| 111 | +And we're done 🎉 |
| 112 | + |
| 113 | +## Options |
| 114 | + |
| 115 | +The options can be specified in the `package.json` file under the `react-native-builder-bob` property, or in a `bob.config.js` file in your project directory. |
| 116 | + |
| 117 | +### `source` |
| 118 | + |
| 119 | +The name of the folder with the source code which should be compiled. The folder should include an `index` file. |
| 120 | + |
| 121 | +### `output` |
| 122 | + |
| 123 | +The name of the folder where the compiled files should be output to. It will contain separate folder for each target. |
| 124 | + |
| 125 | +### `exclude` |
| 126 | + |
| 127 | +Glob pattern to be used while filtering the unnecessary files. Defaults to `'**/{__tests__,__fixtures__,__mocks__}/**'` if not specified. |
| 128 | + |
| 129 | +Example: |
| 130 | + |
| 131 | +```json |
| 132 | +{ |
| 133 | + "exclude": "ignore_me/**" |
| 134 | +} |
| 135 | +``` |
| 136 | + |
| 137 | +> This option only works with `commonjs` and `module` targets. To exclude files while building `typescript`, please see [the tsconfig exclude field](https://www.typescriptlang.org/tsconfig#exclude). |
| 138 | +
|
| 139 | +### `targets` |
| 140 | + |
| 141 | +Various targets to build for. The available targets are: |
| 142 | + |
| 143 | +#### `commonjs` |
| 144 | + |
| 145 | +Enable compiling source files with Babel and use commonjs module system. |
| 146 | + |
| 147 | +This is useful for running the code in Node (SSR, tests etc.). The output file should be referenced in the `main` field of `package.json`. |
| 148 | + |
| 149 | +By default, the code is compiled to support last 2 versions of modern browsers. It also strips TypeScript and Flow annotations, and compiles JSX. You can customize the environments to compile for by using a [browserslist config](https://github.com/browserslist/browserslist#config-file). |
| 150 | + |
| 151 | +In addition, the following options are supported: |
| 152 | + |
| 153 | +- `configFile` & `babelrc` (`boolean`): To customize the babel config used, you can pass the [`configFile`](https://babeljs.io/docs/en/options#configfile) option as `true` if you have a `babel.config.js` or [`babelrc`](https://babeljs.io/docs/en/options#babelrc) option if you have a `.babelrc`. This may break the default configuration, so use these options only if you know what you're doing. |
| 154 | + |
| 155 | +- `copyFlow` (`boolean`): If your source code is written in [Flow](http://www.typescriptlang.org/), You can specify the `copyFlow` option to copy the source files as `.js.flow` to the output folder. If the `main` entry in `package.json` points to the `index` file in the output folder, the flow type checker will pick these files up to use for type definitions. |
| 156 | + |
| 157 | +- `sourceMaps` (`boolean`): Sourcemaps are generated by default alongside the compiled files. You can disable them by setting the `sourceMaps` option to `false`. |
| 158 | + |
| 159 | +Example: |
| 160 | + |
| 161 | +```json |
| 162 | +["commonjs", { "configFile": true, "copyFlow": true }] |
| 163 | +``` |
| 164 | + |
| 165 | +#### `module` |
| 166 | + |
| 167 | +Enable compiling source files with Babel and use ES module system. This is essentially same as the `commonjs` target and accepts the same options, but leaves the `import`/`export` statements in your code. |
| 168 | + |
| 169 | +This is useful for bundlers which understand ES modules and can tree-shake. The output file should be referenced in the `module` field of `package.json`. |
| 170 | + |
| 171 | +Example: |
| 172 | + |
| 173 | +```json |
| 174 | +["module", { "configFile": true }] |
| 175 | +``` |
| 176 | + |
| 177 | +#### `typescript` |
| 178 | + |
| 179 | +Enable generating type definitions with `tsc` if your source code is written in [TypeScript](http://www.typescriptlang.org/). |
| 180 | + |
| 181 | +The following options are supported: |
| 182 | + |
| 183 | +- `project` (`string`): By default, the `tsconfig.json` file in the root of your project is used to generate the type definitions. You can specify a path to a different config by using the `project` option. This can be useful if you need to use different configs for development and production. |
| 184 | + |
| 185 | +- `tsc` (`string`): The path to the `tsc` binary is automatically detected and defaults to the one installed in your project. You can use the `tsc` option to specify a different path. |
| 186 | + |
| 187 | +Example: |
| 188 | + |
| 189 | +```json |
| 190 | +["typescript", { "project": "tsconfig.build.json" }] |
| 191 | +``` |
| 192 | + |
| 193 | +## Commands |
| 194 | + |
| 195 | +The `bob` CLI exposes the following commands: |
| 196 | + |
| 197 | +### `init` |
| 198 | + |
| 199 | +This configures an existing project to use `bob` by adding the required configuration and dependencies. This is usually run with `npx`: |
| 200 | + |
| 201 | +```sh |
| 202 | +npx react-native-builder-bob@latest init |
| 203 | +``` |
| 204 | + |
| 205 | +### `build` |
| 206 | + |
| 207 | +This builds the project according to the configuration. This is usually run as part of the package's publishing flow, i.e. in the `prepare` or `prepack` scripts. |
| 208 | + |
| 209 | +```json |
| 210 | +"scripts": { |
| 211 | + "prepare": "bob build" |
| 212 | +} |
| 213 | +``` |
0 commit comments