CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ember-cli-typescript

Ember CLI addon that provides comprehensive TypeScript support for Ember.js applications and addons.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

blueprints.mddocs/

Blueprints

ember-cli-typescript provides comprehensive blueprints for automatically setting up TypeScript in Ember projects, including configuration files, type definitions, and dependency installation.

Capabilities

Main Blueprint

The ember-cli-typescript blueprint handles complete TypeScript setup for both applications and addons.

interface Blueprint {
  /** Blueprint description */
  description: "Initialize files needed for typescript compilation";
  
  /** Installation hook for pre-setup logic */
  install(options: { project: Project; dummy?: boolean }): Promise<void>;
  
  /** Template variables for file generation */
  locals(): BlueprintLocals;
  
  /** Custom file path tokens */
  fileMapTokens(): Record<string, (options: any) => string>;
  
  /** Pre-installation package setup */
  beforeInstall(): Promise<void>;
  
  /** Path to blueprint template files */
  filesPath(): string;
  
  /** List of files to generate */
  files(): string[];
}

Blueprint Template Variables

The blueprint generates dynamic configuration based on project type and structure.

interface BlueprintLocals {
  /** JSON string of directories to include in TypeScript compilation */
  includes: string;
  
  /** Function to generate tsconfig path mappings for a project */
  pathsFor: (dasherizedName: string) => string;
  
  /** Function to generate app-specific type declarations */
  indexDeclarations: (dasherizedName: string) => string;
  
  /** Function to generate global template type declarations */
  globalDeclarations: (dasherizedName: string) => string;
}

Usage in Templates:

Blueprint templates use these variables to generate customized configuration:

// tsconfig.json template
{
  "compilerOptions": {
    "paths": {{{pathsFor dasherizedModuleName}}}
  },
  "include": {{{includes}}}
}

Project Structure Analysis

The blueprint analyzes project structure to determine appropriate configuration.

/**
 * Determines TypeScript include paths based on project type
 * @returns Array of glob patterns for directories to include
 */
function determineIncludes(): string[];

/**
 * Generates TypeScript path mappings for module resolution
 * @param dasherizedName - Project name in dasherized format
 * @returns JSON string of path mappings for tsconfig.json
 */
function generatePathMappings(dasherizedName: string): string;

Include Path Logic:

  • Apps: ["app/**/*", "tests/**/*", "types/**/*"]
  • Addons: ["app/**/*", "addon/**/*", "tests/**/*", "test-support/**/*", "addon-test-support/**/*", "types/**/*"]
  • Additional paths for Mirage, in-repo addons

Path Mapping Logic:

  • Apps: Maps app modules to app/*, tests to tests/*
  • Addons: Maps addon modules to addon/*, dummy app to tests/dummy/app/*
  • Universal: Maps TypeScript types to types/*

Type Declaration Generation

The blueprint generates TypeScript declaration files for Ember-specific types.

// Standard app-level declarations
const APP_DECLARATIONS: string;

/**
 * Generates template type declarations based on project layout
 * @param projectName - Name of the project
 * @param layout - Project layout type ('classic' or 'pods')
 * @returns TypeScript declaration string for templates
 */
function buildTemplateDeclarations(projectName: string, layout: 'classic' | 'pods'): string;

App Declarations:

// Generated app.d.ts content
import Ember from 'ember';

declare global {
  interface Array<T> extends Ember.ArrayPrototypeExtensions<T> {}
}

Template Declarations:

  • Classic layout: declare module 'app-name/templates/*'
  • Pods layout: declare module 'app-name/*/template'

Dependency Management

The blueprint automatically installs required TypeScript packages.

/**
 * Core TypeScript packages installed for all projects
 */
const CORE_PACKAGES: string[];

/**
 * Conditional packages based on project dependencies
 */
interface ConditionalPackages {
  emberData: string[];
  testing: string[];
  jquery: string[];
}

Package Installation:

  • Core: typescript, @tsconfig/ember, @types/ember, etc.
  • Conditional: @types/ember-data (if Ember Data present)
  • Testing: @types/ember-qunit or @types/ember-mocha
  • Legacy: @types/jquery (if jQuery addon present)

File Path Tokens

Custom tokens for generating files in correct locations.

interface FileMapTokens {
  /** Application name token - 'dummy' for addons, project name for apps */
  __app_name__(options: { inAddon: boolean; dasherizedModuleName: string }): string;
  
  /** Configuration root path - 'tests/dummy/app' for addons, 'app' for apps */
  __config_root__(options: { inAddon: boolean }): string;
}

Addon-Specific Setup

For addon projects, the blueprint performs additional configuration.

/**
 * Transforms addon package.json for TypeScript publishing
 * - Adds prepack/postpack scripts for declaration generation
 * - Moves ember-cli-typescript from devDependencies to dependencies
 */
function transformAddonPackage(): void;

/**
 * Adds or validates npm scripts in package.json
 * @param scripts - Existing scripts object
 * @param type - Script type ('prepack' or 'postpack')
 * @param script - Script command to add
 */
function addScript(scripts: Record<string, string>, type: string, script: string): void;

Addon Publishing Scripts:

{
  "scripts": {
    "prepack": "ember ts:precompile",
    "postpack": "ember ts:clean"
  }
}

Path Updates for In-Repo Addons

Utility for updating TypeScript path mappings when in-repo addons are present.

/**
 * Updates tsconfig path mappings to include in-repo addon modules
 * @param paths - Existing path mappings object
 * @param addonName - Name of the in-repo addon
 * @param appName - Name of the host application
 */
function updatePathsForAddon(
  paths: Record<string, string[]>,
  addonName: string,
  appName: string
): void;

Blueprint Files

The blueprint generates several TypeScript configuration and declaration files:

Generated Files

  • tsconfig.json - TypeScript compiler configuration
  • types/global.d.ts - Global type declarations
  • types/ember-data/types/registries/model.d.ts - Ember Data model registry (if present)
  • app.d.ts - App-specific type declarations

Template Variables in Files

  • {{dasherizedModuleName}} - Project name
  • {{includes}} - Directories to include
  • {{{pathsFor dasherizedModuleName}}} - Path mappings
  • {{{indexDeclarations dasherizedModuleName}}} - App declarations
  • {{{globalDeclarations dasherizedModuleName}}} - Template declarations

Constants

// Standard app-level TypeScript declarations
const APP_DECLARATIONS: string;

// Blueprint name reference
const ADDON_NAME: "ember-cli-typescript";

The blueprint system ensures that TypeScript is properly configured for any Ember project type, with appropriate type definitions, compiler settings, and build integration.

Install with Tessl CLI

npx tessl i tessl/npm-ember-cli-typescript

docs

addon-integration.md

blueprints.md

cli-commands.md

index.md

type-checking.md

tile.json