{"id":15877,"library":"typeroll","title":"Typeroll","description":"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.","status":"active","version":"0.7.7","language":"javascript","source_language":"en","source_url":"https://github.com/arshad-yaseen/typeroll","tags":["javascript","typescript","dts","declaration","declaration map","declaration map generation"],"install":[{"cmd":"npm install typeroll","lang":"bash","label":"npm"},{"cmd":"yarn add typeroll","lang":"bash","label":"yarn"},{"cmd":"pnpm add typeroll","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for compilation, type resolution, and declaration generation. Typeroll leverages the TypeScript compiler API.","package":"typescript","optional":false}],"imports":[{"note":"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.","wrong":"const { bundle } = require('typeroll');","symbol":"bundle","correct":"import { bundle } from 'typeroll';"},{"note":"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.","wrong":"import { BundleOptions } from 'typeroll';","symbol":"BundleOptions","correct":"import type { BundleOptions } from 'typeroll';"},{"note":"Import the custom error class for more specific error handling during programmatic bundling operations.","symbol":"TyperollError","correct":"import { TyperollError } from 'typeroll';"}],"quickstart":{"code":"import { bundle } from 'typeroll';\nimport * as path from 'path';\nimport * as fs from 'fs/promises';\n\nconst projectRoot = path.resolve(__dirname, 'my-project');\nconst entryFile = path.join(projectRoot, 'src', 'index.ts');\nconst outputDir = path.join(projectRoot, 'dist');\nconst outputFile = path.join(outputDir, 'my-lib.d.ts');\n\n// Create dummy project files for demonstration\nasync function setupDummyProject() {\n  await fs.mkdir(path.join(projectRoot, 'src'), { recursive: true });\n  await fs.mkdir(outputDir, { recursive: true });\n  await fs.writeFile(path.join(projectRoot, 'tsconfig.json'), JSON.stringify({\n    \"compilerOptions\": {\n      \"target\": \"es2018\",\n      \"module\": \"esnext\",\n      \"declaration\": true,\n      \"declarationMap\": true,\n      \"outDir\": \"./dist\",\n      \"strict\": true,\n      \"esModuleInterop\": true,\n      \"skipLibCheck\": true,\n      \"forceConsistentCasingInFileNames\": true\n    },\n    \"include\": [\"src\"]\n  }, null, 2));\n  await fs.writeFile(path.join(projectRoot, 'src', 'index.ts'), 'export * from \"./utils\";\\nexport const version = \"1.0.0\";\\n');\n  await fs.writeFile(path.join(projectRoot, 'src', 'utils.ts'), 'export function greet(name: string): string { return `Hello, ${name}!`; }\\n');\n}\n\nasync function runBundle() {\n  await setupDummyProject();\n  try {\n    console.log(`Bundling declarations from ${entryFile}...`);\n    const result = await bundle({\n      entryPoints: [entryFile],\n      tsConfigPath: path.join(projectRoot, 'tsconfig.json'),\n      outputFile,\n      cwd: projectRoot,\n      // Optional: Set to false to disable declaration map generation\n      // declarationMap: false,\n    });\n    console.log(`Declaration bundle written to ${outputFile}`);\n    console.log(`\nGenerated Content Preview:\\n---\\n${(await fs.readFile(outputFile, 'utf-8')).slice(0, 300)}...\\n---`);\n    // Clean up dummy project\n    await fs.rm(projectRoot, { recursive: true, force: true });\n  } catch (error) {\n    console.error('Error bundling declarations:', error);\n    await fs.rm(projectRoot, { recursive: true, force: true });\n    process.exit(1);\n  }\n}\n\nrunBundle();\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"As 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.","severity":"breaking","affected_versions":">=0.0.0"},{"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.","message":"Typeroll 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Typeroll 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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`).","cause":"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.","error":"Error: Cannot find module 'typeroll' from '<your-project-path>'"},{"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.","cause":"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.","error":"TypeScript diagnostic error: 'Duplicate identifier <SymbolName>.'"},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'getEmitOutput')"}],"ecosystem":"npm"}