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

Type Checking

ember-cli-typescript provides a sophisticated background type checking system that runs TypeScript compilation in a separate worker process, providing real-time error feedback during development.

Capabilities

TypeScript Worker

The core type checking functionality runs in a background worker that monitors file changes and provides continuous type checking.

interface TypecheckStatus {
  /** Array of formatted TypeScript error messages */
  errors: string[];
  /** Whether the type check failed (true if errors exist and noEmitOnError is enabled) */
  failed: boolean;
}

class TypecheckWorker {
  /**
   * Begin project typechecking, loading TypeScript from the given project root
   * @param projectRoot - Absolute path to the project root directory
   */
  start(projectRoot: string): void;

  /**
   * Returns the current typechecking status, blocking until complete if a check is in progress
   * @returns Promise resolving to current type check status
   */
  getStatus(): Promise<TypecheckStatus>;

  /**
   * Accepts a callback that will be invoked any time a check completes
   * @param listener - Callback function receiving TypecheckStatus payload
   */
  onTypecheck(listener: (status: TypecheckStatus) => void): void;
}

Initialization:

import TypecheckWorker from "ember-cli-typescript/ts/lib/typechecking/worker";

const worker = new TypecheckWorker();
worker.start("/path/to/project");

// Listen for type check results
worker.onTypecheck((status) => {
  if (status.failed) {
    console.error("Type checking failed:");
    status.errors.forEach(error => console.error(error));
  }
});

Development Middleware

Express middleware that displays TypeScript errors in the browser during development.

class TypecheckMiddleware {
  /**
   * Creates middleware instance
   * @param project - Ember CLI project instance
   * @param workerPromise - Promise resolving to typecheck worker
   */
  constructor(project: Project, workerPromise: Promise<Remote<TypecheckWorker>>);

  /**
   * Register middleware with Express application
   * @param app - Express application instance
   */
  register(app: Application): void;
}

Behavior:

Intercepts HTML requests (excludes non-HTML and live-reload requests)
Checks current TypeScript status from worker
Displays formatted error page if type checking has failed
Passes through to normal application if no errors

Usage Example:

import TypecheckMiddleware from "ember-cli-typescript/ts/lib/typechecking/middleware";

const middleware = new TypecheckMiddleware(project, workerPromise);
middleware.register(app);

Error Display

The middleware renders TypeScript errors as formatted HTML pages during development.

/**
 * Renders HTML error page for TypeScript compilation errors
 * @param errors - Array of formatted error messages from TypeScript
 * @param environmentInfo - Version information for TypeScript and ember-cli-typescript
 * @returns HTML string for error display page
 */
function renderErrorPage(errors: string[], environmentInfo: string): string;

Error Page Features:

Syntax-highlighted TypeScript errors
File locations and line numbers
Environment version information
Clean formatting optimized for development

Worker Management

The type checking system uses child processes for isolation and performance.

/**
 * Fork utility for creating child processes
 * @param modulePath - Path to the module to run in child process
 * @returns Child process instance
 */
function fork(modulePath: string): ChildProcess;

Worker Launch Process:

Forks a new Node.js child process
Establishes communication channel using Stagehand
Initializes TypeScript compiler in watch mode
Sets up file system watchers for project files
Begins continuous type checking

Implementation Details

File System Watching

The worker integrates with TypeScript's built-in file system watching:

Monitors all TypeScript files in the project
Watches tsconfig.json for configuration changes
Tracks file additions and deletions in watched directories
Debounces multiple file changes to avoid excessive type checking

Compiler Integration

interface CompilerHost {
  /** Watch individual files for changes */
  watchFile: (path: string, callback: FileWatcherCallback, pollingInterval?: number) => FileWatcher;
  
  /** Watch directories for file additions/deletions */
  watchDirectory: (path: string, callback: DirectoryWatcherCallback, recursive?: boolean) => FileWatcher;
  
  /** Called after TypeScript program is created/updated */
  afterProgramCreate: (program: SemanticDiagnosticsBuilderProgram) => void;
}

Timing and Debouncing

The system includes intelligent timing to handle rapid file changes:

250ms debounce period matches TypeScript's internal timing
Timeout handling for file changes that don't trigger type checking
Status resolution for completed checks
Lazy evaluation to avoid unnecessary work

Error Formatting

TypeScript diagnostics are formatted using the compiler's built-in formatters:

Colored console output for terminal display
Context-aware error messages with file snippets
Canonical file name handling for cross-platform compatibility
Proper newline handling for different operating systems

Constants

// Timeout in milliseconds for typecheck debouncing
const TYPECHECK_TIMEOUT: 300;

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

Worker Communication

The system uses Stagehand for structured communication between the main process and worker:

Type-safe remote procedure calls
Promise-based async communication
Automatic serialization of complex objects
Error handling and process cleanup

This architecture ensures that type checking doesn't block the main Ember CLI process while providing real-time feedback to developers.