esroll is a build tool that combines esbuild and rollup to bundle TypeScript and JavaScript projects. The tool generates TypeScript declaration files from source code and bundles them into a single declaration file using Microsoft's API Extractor. It optionally produces API documentation using API Extractor and tools from the remark ecosystem.
pnpm add -D esrollBundle TypeScript source files to an output directory with code splitting and source maps:
import { build } from 'esroll'
await build({
entryPoints: ['src/index.ts'],
outdir: 'dist',
sourcemap: true,
splitting: true,
treeShaking: true,
tsconfig: 'tsconfig.json',
})Generate TypeScript declarations, bundle them into a single file, and produce API documentation:
import { build } from 'esroll'
await build({
declaration: true,
declarationRollup: true,
documentation: true,
entryPoints: ['src/index.ts'],
tsconfig: 'tsconfig.json',
})function build ↗
Bundles source files, generates TypeScript declarations, and writes documentation based on the specified options.
export declare function build(options: BuildOptions): Promise<BuildResult>| Parameter | Type | Description |
|---|---|---|
options |
BuildOptions |
Build configuration including entry points, output settings, and compilation flags |
Build result containing errors, warnings, and paths to the generated output files
When the build process encounters fatal errors during bundling or declaration generation
Either options.outdir or options.declaration must be set. When options.outdir is specified, source files are bundled to the output directory.
When options.declaration is true, TypeScript declarations are generated and written to the directory specified by the tsconfig compilerOptions.declarationDir setting.
Setting options.documentation enables API documentation generation alongside declarations. Setting options.declarationRollup to true bundles the generated declarations.
When both options.outdir and options.declaration are set, bundling executes first, declaration generation runs second, and documentation writes last.
interface BuildOptions ↗
Configuration options for the build process.
Extends esbuild's build options while omitting options that conflict with the esroll's internal behavior. Adds support for declaration file generation, documentation extraction, and rollup integration.
export interface BuildOptions extends Omit<ESBuildOptions, BuildOptionsExcluded>Generate TypeScript declaration files (.d.ts).
declaration?: boolean;Either this property or outdir must be set. When enabled, declaration files are generated alongside documentation extraction.
Bundle declaration files.
declarationRollup?: boolean;Requires declaration to be true.
Package declarations to bundle with declaration rollup.
declarationRollupPackages?: string[];Requires declarationRollup to be true.
Generate API documentation.
documentation?: boolean | string;Requires declaration to be true. When set to true, documentation is generated and either replaces or appends the matching section in README.md. When set to a string, the value identifies an alternate markdown file that must sit directly inside the package directory and receives the same replacement or append behavior described by documentationHeading.
Markdown heading that identifies the API documentation section.
documentationHeading?: string;The value must include the leading # markers, whose count determines the required heading depth. External markdown provided through documentation must contain a heading whose depth and text match this configuration; matching sections are replaced and the content is appended when no matching heading exists. Applies when documentation is true or set to a string.
Include forgotten exports in the documentation.
documentationIncludeForgottenExports?: boolean;Requires documentation to be true.
Entry point files to bundle.
entryPoints: string[];Logging verbosity level.
logLevel?: 'error' | 'info' | 'silent';Output file directory for bundled source files.
outdir?: string;At least one of outdir or declaration must be set. When specified, source files are bundled to this directory.
Rollup bundler configuration.
rollup?: {
output?: {
generatedCode?: GeneratedCodeOptions;
} & Partial<Pick<OutputOptions, 'exports' | 'externalImportAttributes' | 'importAttributesKey' | 'minifyInternalExports' | 'sanitizeFileName'>>;
plugins?: Plugin[];
treeshake?: TreeshakingOptions;
} & Partial<Pick<RollupOptions, 'experimentalLogSideEffects' | 'maxParallelFileOps'>>;Source map generation mode.
sourcemap?: boolean | 'external' | 'inline' | 'linked';Controls whether and how source maps are generated for the bundled output.
- When set to false or undefined, no source maps are produced.
- When set to true or 'linked', the bundler generates separate .map files alongside the output files and appends a sourceMappingURL comment to each output file that references its corresponding map file location.
- The 'inline' mode embeds source maps directly into the output files as base64-encoded data URIs.
- The 'external' mode writes source maps to separate .map files alongside the output files but omits the sourceMappingURL comment
interface BuildResult ↗
Result of a build operation.
export interface BuildResultErrors that occurred during the build.
errors: PartialMessage[];Paths of generated output files.
outputFiles: Array<Pick<OutputFile, 'path'>>Warnings that occurred during the build.
warnings: PartialMessage[];type BuildOptionsExcluded ↗
ESBuild options that esroll manages internally and excludes from user configuration.
export type BuildOptionsExcluded =
| 'absPaths'
| 'allowOverwrite'
| 'bundle'
| 'entryPoints'
| 'format'
| 'globalName'
| 'metafile'
| 'minify'
| 'outdir'
| 'outfile'
| 'sourcemap'
| 'stdin'
| 'tsconfigRaw'
| 'write'