rc-packagr

Transpile your libraries to React Package Format

Credits

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Installation

npm install -D rc-packagr

Usage Example

Let's walk through a getting started that'll build an React library from TypeScript sources and create a distribution-ready npm package: create a package.json file, add the custom rcPackage property, and eventually run rc-packagr -p package.json – Here we go:

{
  "$schema": "./node_modules/rc-packagr/package.schema.json",
  "name": "@my/foo",
  "version": "1.0.0",
  "rcPackage": {
    "lib": {
      "entryFile": "public_api.ts"
    }
  }
}

Note 1: Paths in the rcPackage section are resolved relative to the location of the package.json file. In the above example, public_api.ts is the entry file to the library's sources and must be placed next to package.json (a sibling in the same folder).

Note 2: referencing the $schema enables JSON editing support (auto-completion for configuration) in IDEs like VSCode.

You can easily run rc-packagr through a npm/yarn script:

{
  "scripts": {
    "build": "rc-packagr -p package.json"
  }
}

Now, execute the build with the following command:

$ yarn build

The build output is written to the dist folder, containing all those binaries to meet the React Package Format specification. You'll now be able to go ahead and npm publish dist your React library to the npm registry.

Do you like to publish more libraries? Is your code living in a monorepo? Create one package.json per npm package, run rc-packagr for each!

Features

• :gift: Implements React Package Format
  • :checkered_flag: Bundles your library in FESM2015, FESM5, and UMD formats
  • :school_satchel: npm package can be consumed by React CLI, Webpack, or SystemJS
  • :dancer: Creates type definitions (.d.ts)
  • :runner: Generates Ahead-of-Time metadata (.metadata.json)
  • :trophy: Auto-discovers and bundles secondary entry points such as @my/foo, @my/foo/testing, @my/foo/bar
• :mag_right: Creates scoped and non-scoped packages for publishing to npm registry
• :surfer: Inlines Templates and Stylesheets
• :sparkles: CSS Features
  • :camel: Runs SCSS preprocessor, supporting the relative ~ import syntax and custom include paths
  • :elephant: Runs less preprocessor, supports the relative ~ import syntax
  • :snake: Runs Stylus preprocessor, resolves relative paths relative to rc-package.json
  • :monkey: Adds vendor-specific prefixes w/ autoprefixer and browserslist — just tell your desired .browserslistrc
  • :tiger: Embed assets data w/ postcss-url

How to…

• Embed Assets in CSS
• Managing Dependencies
• Change the Entry File of a Library
• Change Configuration Locations
• Override tsconfig
• Add Style Include Paths
• Change ECMAScript Language Level
• Package Secondary Entrypoints (sub packages)
• Enable JSX Templates, Bridging the Gap Between React and React

Advanced Use Cases

Examples and Tutorials

A great step-by-step example of making an React CLI project with a library distributed separate from the app, by Jason Aden

Nikolas LeBlanc wrote a tutorial on building an React 4 Component Library with the React CLI and rc-packagr

Here is a demo repository showing rc-packagr and React CLI in action.

What about rc-packagr alongside Nx Workspace? Well, they work well together!

Further user questions and issue-driven documentation

We keep track of user questions in GitHub's issue tracker and try to build a documentation from it. Explore issues w/ label documentation.

Contributing to rc-packagr

General contribution guidelines

If you like to submit a pull request, you'll find it helpful to take a look at the initial design document where it all started.

To orchestrate the different tools, rc-packagr features a custom transformation pipeline. The transformation pipeline is built on top of RxJS and React Dependency Injection concepts.

Knowledge

React Package Format v6.0, design document at Google Docs

Packaging React Libraries - Jason Aden at React Mountain View Meetup (Jan 2018, 45min talk)

Create and publish React libs like a Pro - Juri Strumpflohner at NG-BE (Dec 2017, 30min talk)

Packaging React - Jason Aden at ng-conf 2017 (28min talk)

Create and publish React libs like a Pro - Juri Strumpflohner at ngVikings, this time demoing building React libraries with rc-packagr, with NX as well as Bazel (March 2018, 30min talk)