Learn React
React Compiler

Library Authors Guide

This guide helps library authors understand how to use React Compiler to ship optimized library code to their users.

You will learn

  • Why libraries should ship compiled code
  • How to set up compilation in your build pipeline
  • Testing strategies for compiled libraries
  • Publishing and documentation best practices

Why Ship Compiled Code?

As a library author, you can compile your library code before publishing to npm. This provides several benefits:

  • Performance improvements for all users - Your library users get optimized code without needing to enable the compiler themselves
  • No configuration required by users - The optimizations work out of the box
  • Consistent behavior - All users get the same optimized version regardless of their build setup

Setting Up Compilation

Add React Compiler to your library’s build process:

Terminal
npm install -D babel-plugin-react-compiler@rc

Configure your build tool to compile the library code. For example, with Babel:

// babel.config.js
module.exports = {
  plugins: [
    'babel-plugin-react-compiler',
  ],
  // ... other config
};

Backwards Compatibility

If your library supports React versions below 19, you’ll need additional configuration:

1. Install the runtime package

We recommend installing react-compiler-runtime as a direct dependency:

Terminal
npm install react-compiler-runtime@rc
{
  "dependencies": {
    "react-compiler-runtime": "^19.1.0-rc.2"
  },
  "peerDependencies": {
    "react": "^17.0.0 || ^18.0.0 || ^19.0.0"
  }
}

2. Configure the target version

Set the minimum React version your library supports:

// babel.config.js
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      target: '17', // Minimum React version
    }],
  ],
};

Testing Strategy

Test your library both with and without compilation to ensure compatibility. Run your existing test suite against the compiled code, and also create a separate test configuration that bypasses the compiler. This helps catch any issues that might arise from the compilation process and ensures your library works correctly in all scenarios.

Next Steps

PreviousDebugging and Troubleshooting