Using Rollup to Package Libraries for TypeScript and JavaScript

Introduction

In the modern web development landscape, reusable code libraries have become the backbone of efficient software delivery. Whether you are crafting a suite of React components, building a utility library with helper functions, or developing a full-featured module for the JavaScript ecosystem, the ability to package and distribute your code effectively directly impacts how quickly your work reaches other developers. Among the tools available for this purpose, Rollup has established itself as the definitive choice for library authors who prioritize performance, tree-shaking, and clean, maintainable output.

Rollup was designed from the ground up with a fundamentally different philosophy than other bundlers. While tools like webpack initially focused on application bundling with all their complexity, Rollup recognized that libraries have requirements that differ significantly from applications. A library author needs to produce output that is not only functional but also consumable in a way that allows other developers to extract maximum value. This means enabling tree-shaking so that consumers only pay for the code they actually use, generating clean and readable output that maintains the structure of the original source, and supporting multiple module formats to ensure compatibility across different environments.

This guide explores how to configure Rollup for TypeScript and JavaScript libraries, covering essential plugins like @rollup/plugin-typescript and rollup-plugin-dts, output format strategies for ESM, CommonJS, and UMD, and optimization techniques that will help you create professional-grade packages. By the end of this guide, you will have a comprehensive understanding of how to leverage Rollup to build libraries that integrate seamlessly with modern development workflows and deliver exceptional value to your consumers.

For teams looking to streamline their JavaScript development workflow, our web development services can help you implement these best practices across your entire codebase.

Understanding Module Formats

The Role of Module Formats in Library Distribution

The JavaScript ecosystem has evolved through several module systems over the years, and understanding these formats is fundamental to effective library bundling. Supporting multiple module formats in your library ensures maximum compatibility for consumers working across different environments, build tools, and runtime environments. When you design your library with format flexibility in mind, you open your work to a much wider audience without requiring separate build pipelines or multiple source trees.

ESM (ECMAScript Modules) represents the modern standard for JavaScript modules, using native import and export syntax that browsers and modern bundlers support directly. When you target ESM as your output format, consumers can take full advantage of tree-shaking since the static nature of ESM imports allows bundlers to analyze usage patterns and eliminate dead code. According to the Rollup official documentation, ESM is the format that enables the most sophisticated optimizations because of this analyzability. The import and export statements remain intact in ESM output, allowing the consuming bundler to understand exactly which parts of your library are being used.

CommonJS remains essential despite being the older module format, as it is the standard used by Node.js and many existing build setups. CommonJS relies on require() for imports and module.exports for exports. While this format is less amenable to static analysis and therefore limits tree-shaking effectiveness, CommonJS output is crucial for Node.js applications, server-side code, and older build environments that have not yet adopted ESM. When producing CommonJS output, Rollup converts ESM imports to require() calls and exports to module.exports assignments, maintaining semantic equivalence while adapting to the target format.

UMD (Universal Module Definition) serves as a fallback format that provides the broadest possible compatibility. UMD bundles work in browsers as global scripts when loaded via script tag, in CommonJS environments through require(), and in AMD loaders. This format is particularly valuable for libraries that need to work without any module system at all, such as legacy applications or environments with strict limitations on build tooling. When using UMD, you must specify a name that will be used as the global variable when the library is loaded in a browser context, and you should externalize dependencies that consumers might also be using to prevent namespace conflicts.

By supporting all three formats simultaneously from a single source tree, your library can meet developers wherever they are in their tooling journey while always providing the most optimized path for modern applications.

Tree-Shaking Fundamentals

How Tree-Shaking Impacts Bundle Size

Tree-shaking represents one of the most compelling reasons to choose Rollup for library development. The term originates from the concept of shaking dead leaves from a tree, where unused code is removed from the final bundle. In practice, this means that if a consumer imports your library but only uses a specific function, only that function and its dependencies will appear in their bundle. This optimization happens automatically in consumer applications using modern bundlers like Rollup, webpack, or Vite, provided the library was built with ESM and tree-shaking in mind.

The key to effective tree-shaking lies in how your source code is structured. For Rollup to analyze and eliminate unused exports, your source must use ESM syntax exclusively throughout the dependency graph. CommonJS require() calls and module.exports cannot be analyzed statically, which prevents Rollup from determining what is actually used by the consumer. Similarly, you should avoid using export default with object literals, as Rollup cannot determine which properties of that object are accessed by consumer code. The solution is to prefer named exports for everything you want to be tree-shakeable.

Code that tree-shakes effectively:

export function add(a: number, b: number): number {
 return a + b;
}

export function multiply(a: number, b: number): number {
 return a * b;
}

export function subtract(a: number, b: number): number {
 return a - b;
}

When a consumer imports only the add function, Rollup's static analysis determines that multiply and subtract are never referenced and removes them entirely from the output bundle. The consumer receives only the minimal code needed for their specific use case.

Code that prevents tree-shaking:

// This pattern prevents tree-shaking entirely
export default {
 add: (a: number, b: number) => a + b,
 multiply: (a: number, b: number) => a * b,
 subtract: (a: number, b: number) => a - b
}

In this pattern, Rollup sees that the entire default export object is imported, and because it cannot analyze property access at runtime, it must include all functions in the bundle. As documented by LogRocket's analysis of Rollup bundling, this aggregation pattern completely defeats the purpose of tree-shaking.

The impact on consumers can be substantial in real-world scenarios. A utility library with dozens of functions might total 50KB in uncompressed size, but a consumer who only uses three specific functions might end up with a bundle of only 5KB after tree-shaking. This difference directly translates to faster page load times, reduced bandwidth consumption, and better runtime performance in the applications using your library.

If you're building a JavaScript application that relies heavily on external libraries, our custom web development services can help you optimize your bundle size and implement these same principles across your entire codebase.

Core Configuration and Essential Plugins

Setting Up Your Rollup Configuration

A minimal Rollup configuration for library bundling starts with defining an entry point and output format. The entry point is typically your main source file, often src/index.ts in TypeScript projects. From there, Rollup analyzes the dependency graph and produces the bundled output. However, real-world library development requires additional plugins to handle TypeScript compilation, Node module resolution, and CommonJS transformations that inevitably appear in dependency trees.

Essential Plugins for TypeScript Library Bundling:

1. @rollup/plugin-typescript - As documented in the official TypeScript plugin documentation, this plugin handles TypeScript compilation within the Rollup pipeline. It reads your tsconfig.json configuration and compiles TypeScript source files to JavaScript while preserving type information for declaration generation. The plugin integrates tightly with Rollup's watch mode for development and produces consistent output across different environments.

2. @rollup/plugin-node-resolve - This essential plugin resolves Node modules in your library dependencies. When your library imports from node_modules, this plugin tells Rollup where to find those packages and includes them in the bundle when appropriate. For libraries, you typically want to either bundle dependencies or mark them as external depending on your distribution strategy.

3. @rollup/plugin-commonjs - Since Rollup uses ESM natively, any CommonJS packages or modules must be converted before Rollup can process them. This plugin performs the conversion, enabling Rollup to analyze and bundle mixed module type projects effectively.

Complete Configuration Example:

import typescript from '@rollup/plugin-typescript';
import resolve from '@rollup/plugin-node-resolve';
import commonjs from '@rollup/plugin-commonjs';

export default {
 input: 'src/index.ts',
 output: [
 {
 file: 'dist/library-name.esm.js',
 format: 'esm',
 sourcemap: true
 },
 {
 file: 'dist/library-name.cjs.js',
 format: 'cjs',
 sourcemap: true
 }
 ],
 plugins: [
 resolve(),
 commonjs(),
 typescript({ tsconfig: './tsconfig.json' })
 ]
};

The plugin order in the configuration matters significantly. The resolve plugin should typically come first to locate all module dependencies, followed by commonjs to convert any CommonJS modules to ESM format, and finally typescript to compile your TypeScript source. This chain ensures that each plugin operates on the output of the previous one in a predictable sequence.

For teams building automated systems with JavaScript libraries, our AI automation services can help you integrate library distribution into your CI/CD pipelines and development workflows.

TypeScript Configuration for Libraries

Essential tsconfig.json Settings

Your tsconfig.json plays a crucial role in Rollup-based library builds. The compilerOptions directly affect how TypeScript is compiled and what output Rollup receives. Understanding these settings and their impact on the build process is essential for creating libraries that work correctly and provide full type safety to consumers.

Critical Configuration for Library Development:

{
 "compilerOptions": {
 "target": "ES2015",
 "module": "ES2015",
 "declaration": true,
 "declarationDir": "dist/types",
 "outDir": "dist",
 "rootDir": "src",
 "strict": true,
 "esModuleInterop": true,
 "skipLibCheck": true,
 "forceConsistentCasingInFileNames": true,
 "moduleResolution": "node"
 },
 "include": ["src/**/*"],
 "exclude": ["node_modules", "dist"]
}

Key Options Explained:

• declaration: true - This setting generates .d.ts files alongside your JavaScript output, providing type information for TypeScript consumers of your library. Without declarations, TypeScript users lose type safety when using your library.

• declarationDir - Specifies where type definition files are placed. Separating declaration files into their own directory makes it easier to bundle them later using rollup-plugin-dts.

• module - This should match your output format. ES2015 or ESNext works well for ESM output, while CommonJS suits the cjs format. The module setting determines what TypeScript compiles to, which Rollup then processes.

• moduleResolution - Affects how TypeScript resolves imports. The node setting matches traditional Node.js behavior, while node16 matches newer ESM-aware resolution required when using ESM in Node.js environments.

• strict: true - Enables all strict type-checking options, ensuring your library code is as type-safe as possible and catching potential issues early in development.

The combination of these settings ensures that your TypeScript source is compiled correctly for Rollup processing while generating the comprehensive type definitions that TypeScript consumers of your library need to get the full benefit of your type-safe code.

Configuring Multiple Output Formats

Building ESM, CommonJS, and UMD from Single Source

A robust library configuration typically produces multiple output formats to ensure compatibility across different environments. Rather than maintaining separate source trees or build pipelines for each format, Rollup configurations can define an array of output configurations, each specifying a different format and destination file. This approach allows you to build ESM, CommonJS, and UMD versions simultaneously from a single source tree, ensuring consistency while maximizing compatibility.

Comprehensive Multiple Output Configuration:

export default {
 input: 'src/index.ts',
 output: [
 {
 file: 'dist/library-name.esm.js',
 format: 'esm',
 sourcemap: true
 },
 {
 file: 'dist/library-name.cjs.js',
 format: 'cjs',
 sourcemap: true,
 exports: 'named'
 },
 {
 file: 'dist/library-name.umd.js',
 format: 'umd',
 name: 'LibraryName',
 sourcemap: true,
 globals: {
 react: 'React'
 }
 }
 ],
 plugins: [
 resolve(),
 commonjs(),
 typescript({ tsconfig: './tsconfig.json' })
 ],
 external: ['react']
};

Format Selection Guidelines:

• ESM (format: 'esm') - This is the preferred format for modern applications using bundlers that support tree-shaking. The output preserves import and export statements, allowing the consuming bundler to analyze usage and eliminate unused code. ESM output is typically the smallest because it does not include any module system overhead.

• CommonJS (format: 'cjs') - Required for Node.js applications and older build setups that do not support ESM natively. When producing CommonJS output, setting exports to 'named' ensures that named exports are properly exposed to consumers using require().

• UMD (format: 'umd') - Use this format when you need your library to work in browsers as a global script without any module system. The name option specifies the global variable that will be created, and you should externalize large dependencies that consumers might also be using.

The globals Object:

When building UMD bundles or when you want to provide clear external dependency expectations, the globals object maps module IDs to the global variables they represent. This helps consumers understand what global variables their application needs to have available, and it ensures consistent behavior across different loading scenarios.

By producing all three formats from a single build, you ensure that your library works seamlessly across the entire JavaScript ecosystem while maintaining a single source of truth for your code.

Generating TypeScript Declarations

Creating and Bundling Type Definition Files

TypeScript declaration files (.d.ts) are essential for providing type information to TypeScript consumers of your library. When someone imports your library in a TypeScript project, the type checker reads these declaration files to understand the shapes of your exported functions, classes, and types. Without declarations, TypeScript users lose type safety when using your library, and their IDEs cannot provide autocomplete or error checking for your API. As documented by the rollup-plugin-dts documentation, proper type definitions are a hallmark of professional library distribution.

The Two-Pass Build Pattern:

Creating complete type definitions for distribution requires a two-pass build approach. The first pass compiles TypeScript to JavaScript and generates individual declaration files. The second pass bundles all declaration files into a single index.d.ts file that consumers can easily import and reference.

Complete Build Configuration:

import typescript from '@rollup/plugin-typescript';
import dts from 'rollup-plugin-dts';

export default [
 {
 input: 'src/index.ts',
 output: [
 { file: 'dist/index.esm.js', format: 'esm' },
 { file: 'dist/index.cjs.js', format: 'cjs' }
 ],
 plugins: [
 typescript({ 
 declaration: true, 
 declarationDir: 'dist/types',
 tsconfig: './tsconfig.json'
 })
 ]
 },
 {
 input: 'dist/types/index.d.ts',
 output: {
 file: 'dist/index.d.ts',
 format: 'esm'
 },
 plugins: [dts()]
 }
];

How rollup-plugin-dts Works:

The rollup-plugin-dts handles the bundling of declaration files into a single type definition. Unlike simple file concatenation, this plugin understands TypeScript declaration semantics and properly handles re-exports, ambient declarations, and complex type relationships. It merges overlapping declarations, handles conflicts appropriately, and produces a declaration file that accurately represents your library's public API.

The plugin takes the individual .d.ts files produced by the TypeScript compiler in the first pass and combines them into a single dist/index.d.ts file. This bundled declaration file is what you reference in your package.json's types field, providing a single entry point for TypeScript to understand your entire library.

As outlined in the Nx documentation on compiling TypeScript libraries, this two-pass approach is the industry-standard method for producing professional-grade TypeScript libraries with full type support.

Package.json Configuration

Configuring Entry Points and Type References

Your package.json must correctly reference type definitions and entry points for TypeScript consumers to get the full benefit of your library. The fields in your package.json serve as the contract between your library and the tools that consume it, determining which files are loaded, where type definitions are located, and how exports are structured for different module systems.

Essential package.json Fields for Libraries:

{
 "name": "your-library-name",
 "version": "1.0.0",
 "main": "dist/index.cjs.js",
 "module": "dist/index.esm.js",
 "types": "dist/index.d.ts",
 "files": ["dist"],
 "exports": {
 ".": {
 "types": "./dist/index.d.ts",
 "import": "./dist/index.esm.js",
 "require": "./dist/index.cjs.js"
 },
 "./package.json": "./package.json"
 },
 "scripts": {
 "build": "rollup -c",
 "dev": "rollup -c -w"
 },
 "peerDependencies": {
 "react": ">=17.0.0"
 }
}

Field Explanations:

• types - Points to your bundled declaration file for TypeScript consumers. This is the field that TypeScript reads to understand your library's API surface.

• main - The CommonJS entry point for Node.js require(). This is the file that loads when someone runs require('your-library-name').

• module - The ESM entry point preferred by modern bundlers. When webpack, Rollup, or Vite see this field, they prefer it over main for ESM-aware builds.

• files - Specifies which files and directories are included when the package is published to npm. The dist directory should be included to publish your compiled output.

• exports - Provides fine-grained control over what is exposed at different entry points. The exports field supports conditions that allow you to specify different files for different module systems, with types, import, and require conditions all pointing to the appropriate output files.

• peerDependencies - Dependencies that consumers must install separately. This is the appropriate pattern for libraries that depend on frameworks like React, ensuring that the consumer's framework instance is used rather than bundling a duplicate.

The exports field with its conditions-based syntax is the modern standard for library configuration, providing the most flexible and explicit control over how your library is consumed across different environments.

Performance Optimization and Best Practices

Creating Optimal Library Bundles

Optimizing your library build involves more than just producing correct output. The goal is to create bundles that are as small as possible while remaining functional, debuggable, and maintainable. Tree-shaking, dead code elimination, minification, and source map generation all contribute to creating optimal bundles that provide the best experience for your consumers.

Tree-Shaking Best Practices:

1. Always use named exports - Named exports are fully tree-shakeable because Rollup can analyze exactly which exports are used and eliminate the rest.

2. Avoid default exports with object literals - Default exports that aggregate multiple functions into an object prevent tree-shaking entirely because Rollup cannot determine which properties are accessed.

3. Export individual functions and classes - By exporting individual pieces, consumers only import what they need, and unused exports are eliminated.

4. Use barrel files strategically - Re-export from individual modules in your index.ts to maintain clean public APIs while keeping implementation details private.

Minification and Source Maps:

Minification reduces file size by removing whitespace, shortening variable names, and applying other size-saving transformations. For libraries, you should typically minify production builds while keeping development builds unminified for easier debugging:

import terser from '@rollup/plugin-terser';

export default {
 input: 'src/index.ts',
 output: [
 {
 file: 'dist/index.esm.js',
 format: 'esm'
 },
 {
 file: 'dist/index.min.cjs.js',
 format: 'cjs',
 plugins: [terser()]
 }
 ]
};

Source maps enable debugging even in production environments by mapping minified and bundled code back to the original source. During development, source maps are invaluable for tracing errors through your library code. In production, source maps can be uploaded to services like Sentry or stored separately for debugging crash reports. Both @rollup/plugin-typescript and Rollup itself support source map generation through the sourcemap option.

Development with Watch Mode:

Rollup's watch mode monitors your source files and rebuilds automatically when changes are detected, enabling rapid iteration during library development:

rollup -c --watch
# or in package.json
"dev": "rollup -c -w"

Watch mode configuration allows you to specify which files to watch, which to exclude, and how to handle build failures. For larger libraries, incremental builds cache previously compiled chunks and only rebuild what changed, significantly reducing build times during development.

By following these optimization practices, you create libraries that are a pleasure to consume: small in bundle size, fast to load, and easy to debug when issues arise.

Optimizing library performance also improves SEO outcomes, as smaller bundle sizes contribute to faster page load times and better Core Web Vitals scores. Our SEO services can help you implement comprehensive performance optimization strategies across your entire web presence.

Common Patterns and Advanced Configuration

React Libraries, Peer Dependencies, and Externalization

Building different types of libraries requires specific configuration considerations beyond the basic setup. React component libraries, utility libraries, and framework-specific packages all have unique requirements that your Rollup configuration must address.

React Component Library Configuration:

React component libraries require special consideration because they typically include JSX syntax that must be compiled to JavaScript. The @rollup/plugin-babel handles JSX transformation when configured with appropriate Babel presets:

import commonjs from '@rollup/plugin-commonjs';
import resolve from '@rollup/plugin-node-resolve';
import typescript from '@rollup/plugin-typescript';
import babel from '@rollup/plugin-babel';

export default {
 input: 'src/index.ts',
 external: ['react', 'react-dom'],
 output: [
 { file: 'dist/index.esm.js', format: 'esm' },
 { file: 'dist/index.cjs.js', format: 'cjs' }
 ],
 plugins: [
 resolve(),
 commonjs(),
 babel({
 babelHelpers: 'bundled',
 exclude: 'node_modules/**',
 presets: ['@babel/preset-react']
 }),
 typescript({
 tsconfig: './tsconfig.json',
 jsx: 'react'
 })
 ]
};

Peer Dependencies Pattern:

Peer dependencies represent a common pattern for libraries that depend on framework packages. When your React component library depends on React, marking React as a peer dependency rather than a regular dependency ensures that the consumer's React instance is used:

{
 "peerDependencies": {
 "react": ">=17.0.0",
 "react-dom": ">=17.0.0"
 }
}

This prevents multiple React instances from being loaded, which can cause issues with hooks, context, and other React features that depend on a single React runtime.

Externalizing Dependencies:

External dependencies are packages that you reference in your source but do not want included in the bundle. This is appropriate for peer dependencies, very large packages that consumers likely already have, or packages that must be loaded separately:

export default {
 input: 'src/index.ts',
 external: ['react', 'react-dom', 'lodash'],
 output: {
 file: 'dist/index.cjs.js',
 format: 'cjs',
 globals: {
 react: 'React',
 'react-dom': 'ReactDOM',
 lodash: '_'
 }
 }
};

The globals object provides a mapping between the module IDs used in imports and the global variables that will be available at runtime, ensuring that UMD and browser global builds work correctly.

Troubleshooting Common Issues

Solutions to Frequent Library Build Problems

Even with proper configuration, library development inevitably encounters issues that require debugging. Understanding common problems and their solutions helps you maintain a smooth development workflow and resolve issues quickly when they arise.

Import Resolution Problems:

Import resolution problems often manifest as "module not found" errors during build. These issues typically stem from incorrect module resolution configuration in either Rollup or TypeScript:

// Correct plugin order matters for resolution
plugins: [
 resolve({ browser: true, preferBuiltins: false }),
 commonjs(),
 typescript({ tsconfig: './tsconfig.json' })
]

Ensure that @rollup/plugin-node-resolve is configured to handle your module resolution preferences and that TypeScript's moduleResolution setting matches your build targets. The browser option in the resolve plugin handles browser-specific resolution, while preferBuiltins determines whether Node.js built-in modules are resolved or externalized.

Declaration File Issues:

TypeScript errors in consuming projects about missing types are one of the most common issues library authors face. Problems include missing declarations, incorrect types, or declaration files that do not match compiled JavaScript. Verify that declaration generation is enabled in your tsconfig.json, that rollup-plugin-dts is correctly bundling declarations in your second build pass, and that your package.json's types field points to the bundled declaration file.

Circular Dependencies:

Circular dependencies require careful handling in library code. While Node.js supports some circular dependencies through CommonJS require(), ESM and Rollup handle circular imports differently:

// Problematic pattern - circular dependency
// a.ts
import { b } from './b';
export const a = () => b();

// b.ts 
import { a } from './a';
export const b = () => a();

// Solution - refactor to remove circular dependency

Circular dependencies can cause unexpected behavior where imported values are undefined at import time because the module has not finished initializing. Refactoring to eliminate circular dependencies is usually the best solution, either by merging the dependent modules or extracting shared functionality into a third module.

Export Issues:

Consumers cannot access expected exports or default exports are not working as intended. Verify that your exports field in package.json is correctly configured and that your source uses the export syntax that matches your intended use case. Named exports work consistently across formats, while default exports require careful configuration for CommonJS compatibility:

// Always prefer named exports for tree-shaking
export function myFunction() { }
export class MyClass { }

// Avoid default exports with aggregated objects
export default { myFunction, MyClass }; // Prevents tree-shaking

By understanding these common issues and their solutions, you can maintain a robust build pipeline and quickly resolve issues as they arise during library development.

Conclusion

Rollup provides a powerful foundation for building professional TypeScript and JavaScript libraries that integrate seamlessly with modern development workflows. Its focus on ES modules as the native format enables effective tree-shaking, while its clean output and flexible configuration make it suitable for projects of any size, from small utility libraries to large enterprise component frameworks.

The investment in proper library configuration pays dividends throughout the lifecycle of your project. Consumers benefit from smaller bundle sizes and better developer experience through comprehensive type definitions. Maintainers enjoy consistent builds, easier debugging through source maps, and the flexibility to support multiple module formats from a single source tree. By understanding the core concepts of module formats, plugin configuration, declaration generation, and optimization strategies, you can create libraries that deliver exceptional value to everyone who uses them.

Key takeaways from this guide include prioritizing named exports for maximum tree-shaking effectiveness, generating comprehensive TypeScript declarations using the two-pass build pattern, supporting multiple output formats for broad compatibility, and properly configuring package.json fields to ensure correct resolution across different module systems. These practices, combined with a robust build pipeline and attention to common troubleshooting scenarios, result in libraries that are a pleasure to consume.

As the JavaScript ecosystem continues to evolve with new frameworks, tools, and best practices, Rollup remains a reliable choice for library authors who prioritize quality and performance. Whether you are building utility functions for internal use, React components for a design system, or complex enterprise libraries for distribution, the principles covered in this guide provide a solid foundation for creating professional-grade packages that stand the test of time.

For organizations looking to implement these practices across their entire development workflow, our team can help you establish library development standards, build custom tooling, and train your developers on these techniques. Contact us to learn how our custom software development services can accelerate your library development pipeline.

Sources

1. Rollup Official Documentation
2. LogRocket: Using Rollup to package a library for TypeScript and JavaScript
3. Krython: Rollup Configuration - Library Bundling
4. @rollup/plugin-typescript NPM
5. rollup-plugin-dts NPM
6. Nx Documentation: Compile TypeScript Libraries to Multiple Formats