Embed-TypeScript

3.1.0 verified Fri May 01 auth: no javascript

A library for embedding the TypeScript compiler directly into Node.js or browser applications, providing programmatic compilation, custom transformers, and detailed diagnostics. Current stable version is 3.1.0, with monthly updates. It supports dynamic code compilation without external build tools, includes a CLI for collecting external type definitions from npm packages, and offers a rich diagnostic API. Compared to alternatives like ts-node or esbuild-register, it is designed for in-process compilation with fine-grained control over transformations and error reporting.

Common errors

error Cannot find module 'typescript' ↓

cause typescript is a peer dependency and not installed automatically

fix

Run: npm install typescript

error TypeError: EmbedTypeScript is not a constructor ↓

cause Using default import instead of named import

fix

Change to: import { EmbedTypeScript } from 'embed-typescript'

error error TS2315: Type 'IEmbedTypeScriptResult' is not generic. ↓

cause Using IEmbedTypeScriptResult incorrectly or with old version

fix

Ensure embed-typescript >=3.0.0 and import type correctly: import type { IEmbedTypeScriptResult } from 'embed-typescript'

error Error: Cannot find module 'embed-typescript' ↓

cause Package not installed or incorrect import path

fix

Run: npm install embed-typescript

Warnings

breaking Requires TypeScript >=5.0.0 <7.0.0 as peer dependency ↓

fix Install TypeScript 5.x or 6.x: npm install typescript@^5.0.0

gotcha CLI command changed from npx embed-typescript collect to npx embed-typescript external ↓

fix Use npx embed-typescript external --input <dir> --output <file>

gotcha External type definitions must be collected manually via CLI; automatic resolution not supported ↓

fix Use npx embed-typescript external to generate external.json from npm packages

gotcha skipLibCheck must be set to true in compilerOptions to avoid lib check errors ↓

fix Set skipLibCheck: true in EmbedTypeScript constructor options

deprecated IEmbedTypeScriptFountain type is marked as experimental and may change ↓

fix Watch changelog for updates or avoid using fountain function in production

Install

npm install embed-typescript

yarn add embed-typescript

pnpm add embed-typescript

Imports

EmbedTypeScript

wrong

const EmbedTypeScript = require('embed-typescript').EmbedTypeScript

correct

import { EmbedTypeScript } from 'embed-typescript'

ESM-only; default export is not available. Use named import.

IEmbedTypeScriptResult

wrong

import { IEmbedTypeScriptResult } from 'embed-typescript'

correct

import type { IEmbedTypeScriptResult } from 'embed-typescript'

TypeScript type; prefer type import to avoid runtime overhead.

EmbedEsLint
```
import { EmbedEsLint } from 'embed-typescript'
```
Module available since v2.0.0; used for embedding ESLint in the same project.
IEmbedTypeScriptFountain
```
import type { IEmbedTypeScriptFountain } from 'embed-typescript'
```
Type for the fountain function output; added in v1.3.2.

Quickstart

Creates an EmbedTypeScript instance with TypeScript options and external type definitions, compiles a string, and handles success or failure.

import { EmbedTypeScript } from 'embed-typescript';
import ts from 'typescript';
import external from './external.json' assert { type: 'json' };

const compiler = new EmbedTypeScript({
  external: external as Record<string, string>,
  compilerOptions: {
    target: ts.ScriptTarget.ES2015,
    module: ts.ModuleKind.CommonJS,
    downlevelIteration: true,
    esModuleInterop: true,
    skipLibCheck: true,
    strict: true,
  },
});

const result = compiler.compile({
  'example.ts': 'const msg: string = "Hello, world!";\nconst x: number = 42;\nconsole.log(msg);',
});

if (result.type === 'success') {
  console.log('Compiled JavaScript:', result.javascript);
} else {
  console.error('Compilation failed:', result.diagnostics);
}