diff --git a/docs/contents.md b/docs/contents.md index 654687fe2..7ac3fc3ee 100644 --- a/docs/contents.md +++ b/docs/contents.md @@ -23,6 +23,7 @@ * [Rendering Tests](ember/rendering-tests.md) * [Using Addons](ember/using-addons.md) * [Authoring Addons](ember/authoring-addons.md) + * [Template Imports](ember/template-imports.md) * [GlimmerX](using-glint/glimmerx/README.md) * [Installation](glimmerx/installation.md) * [Component Signatures](glimmerx/component-signatures.md) diff --git a/docs/ember/installation.md b/docs/ember/installation.md index 07b1ae820..d40cf5bca 100644 --- a/docs/ember/installation.md +++ b/docs/ember/installation.md @@ -35,27 +35,13 @@ npm install -D @glint/core @glint/template @glint/environment-ember-loose {% endcode %} -
+{% hint style="info" %} -Using ember-template-imports? +Using `ember-template-imports`? See [Ember: Template Imports][etii] for additional installation steps. -If you are using `ember-template-imports` in your project, you also need to install the `@glint/environment-ember-template-imports` package and configure it in `tsconfig.json` under `glint.environment`: +[etii]: ../ember/template-imports.md#installation -{% code title="tsconfig.json" %} -```json -{ - "compilerOptions": { /* ... */ }, - "glint": { - "environment": [ - "ember-loose", - "ember-template-imports", - ] - } -} -``` -{% endcode %} - -
+{% endhint %} Note that, by default, Glint will assume you want it to analyze all templates in the codebase that are covered by your `tsconfig.json`. To ignore any type errors up front so that you can incrementally migrate your project to typesafe templates, consider using [the `auto-glint-nocheck` script](https://github.com/typed-ember/glint/tree/main/packages/scripts#auto-glint-nocheck) to add [`@glint-nocheck` comments](../directives.md#glint-nocheck) to your existing templates that would produce errors. @@ -65,12 +51,6 @@ Finally, ensure you've added the following statement somewhere in your project's import '@glint/environment-ember-loose'; ``` -If using `ember-template-imports`, add a corresponding line for that environment as well: - -```typescript -import '@glint/environment-ember-template-imports'; -``` - You may also choose to disable TypeScript's "unused symbol" warnings in your editor, since Glint will flag any symbols that are actually unused, while `tsserver` won't understand any symbol usage that only occurs in templates. {% hint style="info" %} diff --git a/docs/ember/template-imports.md b/docs/ember/template-imports.md new file mode 100644 index 000000000..40d6c5864 --- /dev/null +++ b/docs/ember/template-imports.md @@ -0,0 +1,73 @@ +When adding Glint to an Ember project with `ember-template-imports` installed, there are a few additional things to consider. + +## Installation + +In addition to the `@glint/core`, `@glint/template` and `@glint/environment-ember-loose` packages, you also need to install the `@glint/environment-ember-template-imports` package and configure it in `tsconfig.json` under `glint.environment`: + +{% tabs %} +{% tab title="Yarn" %} + +```sh +yarn add --dev @glint/core @glint/template @glint/environment-ember-loose @glint/environment-ember-template-imports +``` + +{% endtab %} +{% tab title="npm" %} + +```sh +npm install -D @glint/core @glint/template @glint/environment-ember-loose @glint/environment-ember-template-imports +``` + +{% endtab %} +{% endtabs %} + +{% code title="tsconfig.json" %} + +```javascript +{ + "compilerOptions": { /* ... */ }, + "glint": { + "environment": [ + "ember-loose", + "ember-template-imports", + ] + } +} +``` + +Additionally, ensure you've added the following statement somewhere in your project's source files or ambient type declarations: + +```typescript +import '@glint/environment-ember-template-imports'; +``` + +{% endcode %} + +## Template-Only Components + +When using `ember-template-imports`, you can declare the type of a `