Building a Modern React Library Starter: A Comprehensive Guide

Introduction

Creating a modern React library requires careful consideration of build tools, development experience, and output optimization. This guide will walk you through building a professional React library starter using TypeScript, SWC, and Rollup—a powerful combination that offers superior performance, reliability, and developer experience.

Why These Tools Matter

TypeScript: Type Safety and Developer Experience

• Static Type Checking: Catch errors during development rather than runtime

• Enhanced IDE Support: Better autocomplete, refactoring, and code navigation

• Self-Documenting Code: Types serve as living documentation

• Improved Maintenance: Makes large codebases more manageable

• Growing Community: Extensive type definitions for popular libraries

SWC: Next-Generation Compilation

• Rust-Powered Performance: Up to 20x faster than Babel
• Drop-in Replacement: Compatible with existing Babel configurations
• Low Memory Footprint: More efficient resource utilization
• Native TypeScript Support: Direct compilation without intermediate steps
• Active Development: Regular updates and improvements

Rollup: Optimized Library Bundling

• Tree Shaking: Advanced dead code elimination
• Multiple Output Formats: ESM, CommonJS, and UMD support
• Smaller Bundle Size: No unnecessary runtime code
• Plugin Ecosystem: Rich set of official and community plugins
• Code Splitting: Efficient chunk management

Project Setup Guide

1. Initialize Project Structure

mkdir react-library cd react-library npm init -y # Create essential directories mkdir src 

2. Install Dependencies

# Core dependencies npm install react react-dom --save-peer # Development dependencies npm install --save-dev typescript @types/react @types/react-dom \ @swc/core @swc/helpers \ rollup @rollup/plugin-swc @rollup/plugin-node-resolve \ @rollup/plugin-commonjs rollup-plugin-peer-deps-external 

3. TypeScript Configuration

Create tsconfig.json:

{ "compilerOptions": { "target": "ES2018", "module": "ESNext", "lib": ["DOM", "DOM.Iterable", "ESNext"], "declaration": true, "declarationDir": "dist/types", "emitDeclarationOnly": true, "jsx": "react-jsx", "strict": true, "moduleResolution": "node", "allowSyntheticDefaultImports": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "resolveJsonModule": true, "isolatedModules": true, "noUnusedLocals": true, "noUnusedParameters": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true }, "include": ["src"], "exclude": ["node_modules", "dist"] } 

4. Rollup Configuration

Create rollup.config.js:

import resolve from '@rollup/plugin-node-resolve'; import commonjs from '@rollup/plugin-commonjs'; import { swc, defineRollupSwcOption } from '@rollup/plugin-swc'; import peerDepsExternal from 'rollup-plugin-peer-deps-external'; import terser from '@rollup/plugin-terser'; const packageJson = require('./package.json'); const swcConfig = defineRollupSwcOption({ jsc: { parser: { syntax: 'typescript', tsx: true, }, transform: { react: { runtime: 'automatic', development: false, refresh: false, }, }, target: 'es2018', }, minify: false, }); export default [ // ESM build { input: 'src/index.tsx', output: [ { file: packageJson.module, format: 'esm', sourcemap: true, }, ], plugins: [ peerDepsExternal(), resolve({ extensions: ['.ts', '.tsx', '.js', '.jsx'], }), commonjs(), swc(swcConfig), terser(), ], external: ['react', 'react-dom'], }, // CommonJS build { input: 'src/index.tsx', output: [ { file: packageJson.main, format: 'cjs', sourcemap: true, exports: 'auto', }, ], plugins: [ peerDepsExternal(), resolve({ extensions: ['.ts', '.tsx', '.js', '.jsx'], }), commonjs(), swc(swcConfig), terser(), ], external: ['react', 'react-dom'], }, ]; 

5. Package.json Configuration

Update your package.json:

{ "name": "your-library-name", "version": "1.0.0", "main": "dist/cjs/index.js", "module": "dist/esm/index.js", "types": "dist/types/index.d.ts", "files": [ "dist" ], "sideEffects": false, "scripts": { "build": "rollup -c", "types": "tsc", "prepare": "npm run types && npm run build", "lint": "eslint ." }, "peerDependencies": { "react": ">=17.0.0 <19.0.0", "react-dom": ">=17.0.0 <19.0.0" }, } 

Writing Library Code

Component Example

Create src/index.tsx:

import React from "react"; export interface HelloProps { name: string; } export default function Hello({ name }: HelloProps) { return <div>Hello {name}!</div>; } 

Best Practices

1. Development Workflow

• Use Git hooks (husky) for pre-commit linting and testing
• Implement semantic versioning
• Set up continuous integration/deployment

2. Documentation

• Include detailed README.md
• Provide usage examples
• Document peer dependencies

3. Performance

• Keep bundle size minimal
• Implement tree-shaking friendly exports
• Avoid runtime dependencies when possible

Publishing

1. Update version in package.json
2. Build the library: npm run build
3. Test the build: npm pack
4. Publish: npm publish

Add working example

Setup a vite app for providing example, and testing code changes in the repo itself. This can also be done with a storybook.

npm create vite@latest example -- --template react-ts 

add your package in the dependencies section of the example package.json

"react-library-starter": "file:../" 

Import your component and test it in the example project.

Your React library is now ready for publishing! 🎉

If you’d like to dive in with a ready-to-use setup, check out the complete starter template here: https://github.com/Abhirup-99/react-library-starter-template. This template includes everything we’ve covered and is designed to help you kickstart your React library development with minimal setup.

Happy coding!