ember-cli-typescript

⚠️ MAINTENANCE MODE: This addon is now in maintenance mode. TypeScript support has been integrated directly into Ember CLI as of newer versions, and this addon is no longer needed for new projects. It remains available for legacy projects and specific use cases.

ember-cli-typescript is an Ember CLI addon that provides comprehensive TypeScript support for Ember.js applications and addons. It integrates TypeScript compilation into the Ember build pipeline, provides blueprints for project setup, includes CLI commands for declaration management, and offers development-time type checking with error display.

Package Information

• Package Name: ember-cli-typescript
• Package Type: npm
• Language: JavaScript/TypeScript
• Installation: ember install ember-cli-typescript
• Node.js Requirements: >= 12.*
• Ember CLI Requirements: >= 3.5.0 (recommended)
• Babel Requirements: >= 7.17.0 (required)

Core Imports

This addon is primarily consumed as an Ember CLI addon and does not require direct imports in typical usage. The addon automatically integrates with Ember's build system once installed.

For advanced use cases (developing custom addons or build tools), internal utilities can be imported:

// Advanced: Internal utility functions for addon development
import { addon, command } from "ember-cli-typescript/ts/lib/utilities/ember-cli-entities";
import { copyDeclarations } from "ember-cli-typescript/ts/lib/utilities/copy-declarations";

Basic Usage

Installation and Setup

Install the addon using Ember CLI, which automatically runs the blueprint and sets up TypeScript configuration:

ember install ember-cli-typescript

This command:

1. Installs the addon and required TypeScript packages
2. Automatically runs the blueprint to configure TypeScript
3. Generates tsconfig.json and type declaration files
4. Sets up build pipeline integration

The addon provides:

• Automatic TypeScript compilation during builds
• Development-time type checking with browser error display
• CLI commands for declaration file management
• Blueprint-generated TypeScript project setup

CLI Commands

# Generate TypeScript declaration files for publishing
ember ts:precompile

# Clean up generated declaration files
ember ts:clean

Architecture

ember-cli-typescript is built around several key components:

• Ember CLI Addon: Main integration point with Ember's build system and hooks
• TypeScript Compiler Integration: Background worker for continuous type checking
• CLI Commands: Tools for declaration file management during publishing
• Blueprint System: Automated project setup and configuration
• Development Middleware: Browser-based error display during development

Capabilities

CLI Commands

Provides ember CLI commands for TypeScript declaration file management during addon publishing workflows.

interface Command {
  name: string;
  works: string;
  description: string;
  availableOptions: Array<{ name: string; type: any; default?: any }>;
  run(options: any): Promise<void> | void;
}

CLI Commands

Addon Integration

Core Ember CLI addon hooks and methods for integrating TypeScript support into the build pipeline.

interface AddonHooks {
  included(): void;
  includedCommands(): Record<string, any> | undefined;
  blueprintsPath(): string;
  serverMiddleware(config: { app: Application; options?: any }): void;
  testemMiddleware(app: Application, options?: any): void;
  postBuild(): Promise<void>;
  setupPreprocessorRegistry(type: string, registry: PreprocessRegistry): void;
  shouldIncludeChildAddon(addon: Addon): boolean;
}

Addon Integration

Type Checking System

Background TypeScript compilation and error reporting system for development-time feedback.

interface TypecheckStatus {
  errors: string[];
  failed: boolean;
}

class TypecheckWorker {
  start(projectRoot: string): void;
  getStatus(): Promise<TypecheckStatus>;
  onTypecheck(listener: (status: TypecheckStatus) => void): void;
}

Type Checking

Blueprint System

Automated project setup and configuration for TypeScript in Ember projects.

interface BlueprintLocals {
  includes: string;
  pathsFor: (dasherizedName: string) => string;
  indexDeclarations: (dasherizedName: string) => string;
  globalDeclarations: (dasherizedName: string) => string;
}

Blueprints

Types

// Core addon constant
const ADDON_NAME: "ember-cli-typescript";

// Precompile manifest path
const PRECOMPILE_MANIFEST: "dist/.ts-precompile-manifest";

// Live reload path excluded from typecheck middleware
const LIVE_RELOAD_PATH: "/ember-cli-live-reload.js";

// Configuration helper functions
function addon<T extends ExtendOptions<Addon>>(options: T & ExtendThisType<Addon, T>): T;
function command<T extends ExtendOptions<Command>>(options: T & ExtendThisType<Command, T>): T;

// Utility function for copying declaration files during addon publishing
function copyDeclarations(
  pathRoots: string[],
  paths: Record<string, string[]>,
  packageName: string,
  destDir: string
): string[];

// Utility function for forking child processes (used for typecheck worker)
function fork(modulePath: string): ChildProcess;