Build a React Native library
+Build a React Native library
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 for a longer explanation.
Supported targets are:
-
@@ -40,8 +40,8 @@
"source": "src", "output": "lib", "targets": [ - "commonjs", - "module", + ["commonjs", { "esm" : true }], + ["module", { "esm" : true }], "typescript", ] }
Configure the appropriate entry points:
-"main": "lib/commonjs/index.js",
-"module": "lib/module/index.js",
-"types": "lib/typescript/src/index.d.ts",
-"source": "src/index.ts",
+"source": "./src/index.tsx",
+"main": "./lib/commonjs/index.cjs",
+"module": "./lib/module/index.mjs",
+"types": "./lib/typescript/src/index.d.ts",
+"exports": {
+ ".": {
+ "types": "./typescript/src/index.d.ts",
+ "require": "./commonjs/index.cjs",
+ "import": "./module/index.mjs"
+ }
+},
"files": [
"lib",
"src"
]
Here is what each of these fields mean:
+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.main: The entry point for the commonjs build. This is used by Node - such as tests, SSR etc.module: The entry point for the ES module build. This is used by bundlers such as webpack.types: The entry point for the TypeScript definitions. This is used by TypeScript to type check the code using your library.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.files: The files to include in the package when publishing with npm.exports: The entry points for tools that support the exports field in package.json - such as Node.js 12+ & modern browsers.
Make sure to change specify correct files according to the targets you have enabled.
-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).
+
+The exports field also requires the esm option to be enabled for the commonjs and module targets. In addition, the file extensions of the generated files will be .js instead of .cjs and .mjs if the esm option is not enabled.
+
+
+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).
+
Add the output directory to .gitignore and .eslintignore
@@ -122,11 +135,14 @@ Various targets to build for. The available targets are:
commonjs
Enable compiling source files with Babel and use commonjs module system.
-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.
-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 (opens in a new tab).
+This is useful for running the code in Node (SSR, tests etc.). The output file should be referenced in the main field and exports['.'].require (when esm: true) field of package.json.
+By default, the code is compiled to support the last 2 versions of modern browsers. It also strips TypeScript and Flow annotations as well as compiles JSX. You can customize the environments to compile for by using a browserslist config (opens in a new tab).
In addition, the following options are supported:
-
+
esm (boolean): Enabling this option will output ES modules compatible code for Node.js 12+, modern browsers and other tools that support package.json's exports field. This mainly adds file extensions to the imports and exports. Note that file extensions are not added when importing a file that may have platform-specific extensions (e.g. .android.ts). In addition, the generated files will have .cjs (commonjs) and .mjs (modules) extensions instead of .js - this is necessary to disambiguate between the two formats.
+
+-
configFile (boolean | string): To customize the babel config used, you can pass the configFile (opens in a new tab) option as true if you have a babel.config.js or a path to a custom config file. This will override the default configuration. You can extend the default configuration by using the react-native-builder-bob/babel-preset (opens in a new tab) preset.
-
@@ -140,12 +156,12 @@
Example:
-["commonjs", { "configFile": true, "copyFlow": true }]
+["commonjs", { "esm": true, "copyFlow": true }]
module
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.
-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.
+This is useful for bundlers which understand ES modules and can tree-shake. The output file should be referenced in the module field and exports['.'].import (when esm: true) field of package.json.
Example:
-["module", { "configFile": true }]
+["module", { "esm": true, "sourceMaps": false }]
typescript
Enable generating type definitions with tsc if your source code is written in TypeScript (opens in a new tab).
The following options are supported:
@@ -159,6 +175,7 @@ Example:
["typescript", { "project": "tsconfig.build.json" }]
+
The output file should be referenced in the types field or exports['.'].types field of package.json.
Commands
The bob CLI exposes the following commands:
init
@@ -169,4 +186,4 @@ "scripts": {
"prepare": "bob build"
}
