typeroll

library0.7.7jsnpmunverified

Typeroll is a high-performance TypeScript declaration file generator and bundler designed to consolidate all `.d.ts` files into a single output. It focuses on speed and simplicity, making it ideal for library authors who need to ship a unified declaration file for their packages. Currently at version 0.7.7, it is under active development with a release cadence typically tied to critical bug fixes, performance enhancements, and compatibility with newer TypeScript versions. Its primary differentiator is the ability to produce a highly optimized, single declaration file, often outperforming the built-in `tsc --emitDeclarationOnly` for bundling scenarios, especially in larger projects. It provides a programmatic API for integration into build workflows.

devops

npm install typeroll

github ↗package ↗

INSTALL

IMPORT

SIG · TYPEROLL

typeroll

devopsjavascriptv0.7.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

bundle

✓ import { bundle } from 'typeroll';

✗ const { bundle } = require('typeroll');

Typeroll is primarily an ESM package. While CommonJS `require` might work in some environments via transpilation, direct ESM import is the intended and safest method. Ensure your project is configured for ESM.

BundleOptions

✓ import type { BundleOptions } from 'typeroll';

✗ import { BundleOptions } from 'typeroll';

Use `import type` for importing interfaces or types to prevent them from being accidentally bundled into your runtime code, aligning with modern TypeScript best practices.

TyperollError

✓ import { TyperollError } from 'typeroll';

Import the custom error class for more specific error handling during programmatic bundling operations.

This quickstart demonstrates how to programmatically use Typeroll to bundle TypeScript declaration files. It creates a small dummy project with a `tsconfig.json` and two `.ts` files, then calls the `bundle` function to output a single `.d.ts` file.

import { bundle } from 'typeroll'; import * as path from 'path'; import * as fs from 'fs/promises'; const projectRoot = path.resolve(__dirname, 'my-project'); const entryFile = path.join(projectRoot, 'src', 'index.ts'); const outputDir = path.join(projectRoot, 'dist'); const outputFile = path.join(outputDir, 'my-lib.d.ts'); // Create dummy project files for demonstration async function setupDummyProject() { await fs.mkdir(path.join(projectRoot, 'src'), { recursive: true }); await fs.mkdir(outputDir, { recursive: true }); await fs.writeFile(path.join(projectRoot, 'tsconfig.json'), JSON.stringify({ "compilerOptions": { "target": "es2018", "module": "esnext", "declaration": true, "declarationMap": true, "outDir": "./dist", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true }, "include": ["src"] }, null, 2)); await fs.writeFile(path.join(projectRoot, 'src', 'index.ts'), 'export * from "./utils";\nexport const version = "1.0.0";\n'); await fs.writeFile(path.join(projectRoot, 'src', 'utils.ts'), 'export function greet(name: string): string { return `Hello, ${name}!`; }\n'); } async function runBundle() { await setupDummyProject(); try { console.log(`Bundling declarations from ${entryFile}...`); const result = await bundle({ entryPoints: [entryFile], tsConfigPath: path.join(projectRoot, 'tsconfig.json'), outputFile, cwd: projectRoot, // Optional: Set to false to disable declaration map generation // declarationMap: false, }); console.log(`Declaration bundle written to ${outputFile}`); console.log(` Generated Content Preview:\n---\n${(await fs.readFile(outputFile, 'utf-8')).slice(0, 300)}...\n---`); // Clean up dummy project await fs.rm(projectRoot, { recursive: true, force: true }); } catch (error) { console.error('Error bundling declarations:', error); await fs.rm(projectRoot, { recursive: true, force: true }); process.exit(1); } } runBundle();

Debug

Known issues

breakingAs a 0.x.x version package, Typeroll may introduce breaking changes in minor versions (e.g., 0.6.x to 0.7.x). Always review the changelog when upgrading to avoid unexpected issues with API changes or option modifications.

fix

Always pin to exact minor versions (e.g., `"typeroll": "~0.7.0"` or `"^0.7.x"` if comfortable with patch fixes only) and consult the project's GitHub releases or changelog before updating.

affects: >=0.0.0

gotchaTyperoll relies heavily on your `tsconfig.json` configuration. Incorrect settings, especially related to `rootDir`, `outDir`, `declaration`, `declarationMap`, or `paths` aliases, can lead to unexpected output or compilation errors within Typeroll.

fix

Ensure your `tsconfig.json` is correctly configured for declaration generation (`declaration: true`). For complex path aliases, explicitly define `paths` in `tsconfig.json` and ensure they resolve correctly within your project structure. Using `cwd` in bundle options can help resolve paths correctly.

affects: >=0.1.0

gotchaTyperoll has a peer dependency on `typescript`. Mismatches between the `typescript` version installed in your project and the version Typeroll expects can lead to subtle compilation errors or unexpected behavior due to API differences in the TypeScript compiler.

fix

Check Typeroll's `package.json` for the exact `typescript` peer dependency range. Ensure your project's `typescript` version falls within this range. If issues persist, try aligning your `typescript` version exactly with the one Typeroll was tested against, if specified.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Cannot find module 'typeroll' from '<your-project-path>'

This typically occurs when attempting to import Typeroll using CommonJS `require()` syntax in an ESM-only context, or if the package is not correctly installed.

fix

Ensure you are using ESM `import` syntax: `import { bundle } from 'typeroll';`. Also, verify `typeroll` is listed in your `package.json` dependencies and installed correctly (`npm install` or `yarn install`).

TypeScript diagnostic error: 'Duplicate identifier <SymbolName>.'

When bundling, if multiple entry points or internal modules declare the same global symbol (e.g., a global interface, type, or variable in non-module files), Typeroll (or the underlying TypeScript compiler) will report a conflict.

fix

Ensure all files intended for bundling are proper modules (have `import` or `export` statements). If global declarations are intentional, consider carefully how they are exposed and ensure uniqueness, or adjust your bundling strategy to avoid including conflicting global scripts.

TypeError: Cannot read properties of undefined (reading 'getEmitOutput')

This error often indicates an internal issue within Typeroll related to the TypeScript compiler API, frequently caused by an incompatible `typescript` version or a severely misconfigured `tsconfig.json` that prevents successful initial compilation.

fix

Verify your `typescript` peer dependency matches Typeroll's requirements. Double-check your `tsconfig.json` for any syntax errors or logical inconsistencies that might prevent `tsc` from compiling your source files successfully on its own. Run `tsc --noEmit` on your source to diagnose underlying TS errors.

Upgrade

Version history

0.7.7latest on npm

Audit

Dependencies

typescriptrequiredRequired as a peer dependency for compilation, type resolution, and declaration generation. Typeroll leverages the TypeScript compiler API.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/arshad-yaseen/typeroll ↗

packagehttps://www.npmjs.com/package/typeroll ↗