Ember CLI TypeScript Blueprint Polyfill

Common errors

• TypeError: typescriptBlueprintPolyfill is not a function

  cause This usually indicates that the `require()` statement failed to correctly import the function, perhaps due to a typo in the package name or an issue with the package's export.
  fix Verify the package is installed (`npm list ember-cli-typescript-blueprint-polyfill`) and the `require()` path/syntax is correct: `const typescriptBlueprintPolyfill = require('ember-cli-typescript-blueprint-polyfill');`.

• Blueprint does not transform TypeScript files into JavaScript.

  cause The `shouldTransformTypeScript: true` flag is missing or incorrectly set in the blueprint's `index.js`, or the polyfill's `init` call is missing/incorrect.
  fix Ensure `shouldTransformTypeScript: true,` is present and `typescriptBlueprintPolyfill(this);` is called within the `init()` method.

Warnings

• deprecated This polyfill is generally no longer needed for Ember CLI versions that natively support TypeScript blueprints (Ember CLI v4.x and above). Using it in modern projects is redundant and could potentially lead to unexpected behavior if not carefully managed alongside native features.
  Fix: For new projects or projects on Ember CLI v4.x+, remove `ember-cli-typescript-blueprint-polyfill` and ensure your Ember CLI setup is configured for native TypeScript blueprint support (via `isTypeScriptProject` flag in `.ember-cli.js` or `ember new --typescript`).
• gotcha For the polyfill to work, the `shouldTransformTypeScript: true` property must be explicitly set in the blueprint's `module.exports` object. Forgetting this flag will prevent TypeScript files from being processed.
  Fix: Add `shouldTransformTypeScript: true,` to your blueprint's `module.exports` object.
• gotcha The `typescriptBlueprintPolyfill` function must be called within the blueprint's `init` method, and the blueprint instance (`this`) must be passed as its argument. Incorrect invocation or passing the wrong context will prevent the polyfill from applying transformations.
  Fix: Ensure your `init` method includes `typescriptBlueprintPolyfill(this);` after calling `this._super && this._super.init.apply(this, arguments);`.

Install

• npm install ember-cli-typescript-blueprint-polyfill npm
• yarn add ember-cli-typescript-blueprint-polyfill yarn
• pnpm add ember-cli-typescript-blueprint-polyfill pnpm

Imports

• typescriptBlueprintPolyfill
  wrong:

  import typescriptBlueprintPolyfill from 'ember-cli-typescript-blueprint-polyfill';

  correct:

  const typescriptBlueprintPolyfill = require('ember-cli-typescript-blueprint-polyfill');

  Blueprints' `index.js` files are executed in a CommonJS environment, thus `require()` is the correct import method. ESM `import` statements are not supported in this context for blueprint files.

Quickstart

Demonstrates how to integrate the `typescriptBlueprintPolyfill` into an Ember CLI blueprint's `index.js` file, enabling TypeScript file transformation for that blueprint. This example configures the blueprint to process `.ts` files and ensures the polyfill is initialized correctly within the `init` hook.

// my-app/blueprints/foo/index.js
const typescriptBlueprintPolyfill = require('ember-cli-typescript-blueprint-polyfill');

module.exports = {
  // Required flag to indicate that the blueprint contains TypeScript files
  shouldTransformTypeScript: true,

  init() {
    // Ensure the super class's init method is called if it exists
    this._super && this._super.init.apply(this, arguments);
    // Call the polyfill with 'this' (the blueprint instance) as the argument
    typescriptBlueprintPolyfill(this);
  },

  // Other blueprint methods like locals, fileMapTokens, etc.
  // ...
};