or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

addon-integration.md blueprints.md cli-commands.md index.md type-checking.md

tile.json

Addon Integration

ember-cli-typescript integrates with Ember CLI through the standard addon system, providing hooks and methods that extend the build pipeline with TypeScript support.

Capabilities

Core Addon Hooks

The main addon class implements several key Ember CLI hooks to integrate TypeScript compilation and checking.

interface EmberCLIAddon {
  /** Called when the addon is included in a build */
  included(): void;
  
  /** Provides custom CLI commands to the host application */
  includedCommands(): Record<string, any> | undefined;
  
  /** Returns the path to addon blueprints */
  blueprintsPath(): string;
  
  /** Registers middleware with the development server */
  serverMiddleware(config: { app: Application; options?: any }): void;
  
  /** Registers middleware with the test server */
  testemMiddleware(app: Application, options?: any): void;
  
  /** Runs after the build completes */
  postBuild(): Promise<void>;
  
  /** Sets up preprocessors in the registry */
  setupPreprocessorRegistry(type: string, registry: PreprocessRegistry): void;
  
  /** Filters which child addons should be included */
  shouldIncludeChildAddon(addon: Addon): boolean;
}

Included Hook

Called when the addon is included in the build. Performs initial setup and validation.

/**
 * Main inclusion hook - sets up TypeScript integration
 * Checks development setup, addon app files, and Babel version compatibility
 * Starts typecheck worker for direct dependencies
 */
included(): void;

Validation performed:

Checks if running in development with correct file sources
Validates that addon app directories don't contain TypeScript files
Ensures compatible Babel version (>= 7.17.0)
Verifies Ember CLI version compatibility (>= 3.5.0 recommended)
Checks addon installation location (dependencies vs devDependencies)

Command Integration

Provides CLI commands when the host is an Ember CLI addon.

/**
 * Provides CLI commands for addon projects
 * @returns Object with ts:precompile and ts:clean commands, or undefined for apps
 */
includedCommands(): Record<string, any> | undefined;

Returns commands only for addon projects:

ts:precompile - Generate declaration files for publishing
ts:clean - Clean up generated files

Blueprint Path

Specifies the location of addon blueprints for project setup.

/**
 * Returns path to blueprint files
 * @returns Absolute path to blueprints directory
 */
blueprintsPath(): string;

Development Server Integration

Adds TypeScript error checking middleware to development and test servers.

/**
 * Registers typecheck middleware with development server
 * @param config - Server configuration with Express app and options
 */
serverMiddleware(config: { app: Application; options?: any }): void;

/**
 * Registers typecheck middleware with test server  
 * @param app - Express application instance
 * @param options - Optional configuration
 */
testemMiddleware(app: Application, options?: any): void;

Middleware is skipped when serving from a specific path (e.g., proxy scenarios).

Build Integration

Performs type checking after builds complete.

/**
 * Runs TypeScript checking after build completion
 * @returns Promise that rejects if type checking fails
 * @throws Error if type checking fails with noEmitOnError
 */
postBuild(): Promise<void>;

Process:

Gets status from typecheck worker
Waits for any in-progress type checking to complete
Throws error if type checking failed and noEmitOnError is enabled
Errors are already displayed by the worker, so only throws for build failure

Preprocessor Registry

Sets up file collision detection for JavaScript/TypeScript file conflicts.

/**
 * Registers preprocessors with the build pipeline
 * @param type - Registry type (only processes 'parent')
 * @param registry - Preprocessor registry instance
 */
setupPreprocessorRegistry(type: string, registry: PreprocessRegistry): void;

Adds collision detection preprocessor that warns about files with the same name but different extensions (.js vs .ts).

Child Addon Filtering

Controls which child addons are included in the build.

/**
 * Determines whether a child addon should be included
 * @param addon - Child addon to evaluate
 * @returns false for test fixture addons, true otherwise
 */
shouldIncludeChildAddon(addon: Addon): boolean;

Excludes test fixture addons (in-repo-a, in-repo-b) to avoid circular dependencies.

Configuration Helpers

Addon Configuration Function

Helper function for creating type-safe Ember CLI addon configurations.

/**
 * Configuration helper for defining Ember CLI addons with proper typing
 * @param options - Addon configuration object
 * @returns Same configuration object with proper typing
 */
function addon<T extends ExtendOptions<Addon>>(options: T & ExtendThisType<Addon, T>): T;

Usage Example:

import { addon } from "ember-cli-typescript/ts/lib/utilities/ember-cli-entities";

export default addon({
  name: "my-typescript-addon",
  
  included() {
    this._super.included.apply(this, arguments);
    // Custom inclusion logic
  },
  
  // Other addon hooks...
});

Constants

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

Private Implementation Details

The addon maintains internal state and helper methods:

_typecheckWorker - Cached promise for the background typecheck worker
_getTypecheckWorker() - Lazy initialization of typecheck worker
_forkTypecheckWorker() - Creates new worker child process
_addTypecheckMiddleware() - Adds middleware to Express applications
Various validation methods for development-time checks

Version

Tile

Files