<template> quickstart

Photo by Rene Böhmer

This is a quick reference guide for getting started with gjs/gts aka <template>.

The RFC that concluded the research in to this new file format is RFC#779 First-Class Component Templates

For all projects

  1. For syntax highlighting:

  2. For type checking gts, you'll use glint instead of tsc. Ember Glint documentation is here on the Glint docs site.


Ensure that your tsconfig.json has

```json 
{
  "compilerOptions": { /* ... */ },
  "glint": {
    "environment": [
      "ember-loose",
      "ember-template-imports"
    ]
  }
}
```
<br>
Note that in Glint projects, you'll want to disable `tsserver`, so you don't have double-reported errors.

3. For linting, there are two paths: - Quickest:
use configs.ember() from @nullvoxpopuli/eslint-configs - Modifying you're existing lint command:
bash eslint . --ext js,ts,gjs,gts if you otherwise don't specify extensions, having a sufficiently new enough lint config from the app blueprint should "just work" - make sure you have at least [email protected] - use the ember eslint parser in your eslint config, (mentioned in the eslint-plugin-ember README)

   ```js
   module.exports = {
      // ...
      overrides: [
        // ...
        {
          files: ['**/*.gts'],
          plugins: ['ember'],
          parser: 'ember-eslint-parser',
        },
        {
          files: ['**/*.gjs'],
          plugins: ['ember'],
          parser: 'ember-eslint-parser',
        },
      ],
   };
   ```

To get linting working in VSCode, you'll need to modify your settings (and be sure to include the defaults as well for both of these settings):
```json 
"eslint.probe": [
 // ...
 "glimmer-js", 
 "glimmer-ts"
],
"eslint.validate": [
  // ...
  "glimmer-js",
  "glimmer-ts"
],
// ...
"prettier.documentSelectors": ["**/*.gjs", "**/*.gts"],
```

For neovim,
```lua 
local lsp = require('lspconfig')
  
-- ✂️ 

local eslint = lsp['eslint']
  
eslint.setup({
  filetypes = { 
    "javascript", "typescript", 
    "typescript.glimmer", "javascript.glimmer", 
    "json", 
    "markdown" 
  },
  on_attach = function(client, bufnr)
    vim.api.nvim_create_autocmd("BufWritePre", {
      buffer = bufnr,
      command = "EslintFixAll",
    })
  end,
})
```
neovim has support for `typescript.glimmer` and `javascript.glimmer` built in. [`vim-polyglot`](https://github.com/sheerun/vim-polyglot) breaks neovim's built-in syntax resolving, so uninstall that if you have it (neovim ships with treesitter which has very extensive language support).

4. For prettier/formatting, you'll need prettier-plugin-ember-template-tag And for the best experience / workflow, run eslint and prettier separately (without the popular eslint-plugin-prettier)

In an App

  1. Install ember-template-imports.

  2. If you use TypeScript,

    1. update your babel config to have:
      "plugins": [
        [
          "@babel/plugin-transform-typescript",
          { "allExtensions": true, "onlyRemoveTypeImports": true, "allowDeclareFields": true }
        ],
        // ...
    1. update your tsconfig.json to have (in compilerOptions)
    "verbatimModuleSyntax": true,

In a v1 Addon

  1. Install ember-template-imports.

    npm add ember-template-imports

    it is important that this library be in dependencies, not devDependencies

  2. If you use TypeScript,

    1. update your babel config to have:
      "plugins": [
        [
          "@babel/plugin-transform-typescript",
          { "allExtensions": true, "onlyRemoveTypeImports": true, "allowDeclareFields": true }
        ],
        // ...
    1. update your tsconfig.json to have (in compilerOptions)
    "verbatimModuleSyntax": true,
    "allowImportingTsExtensions": true,

In a v2 Addon

  1. @embroider/addon-dev provides a addon.gjs() plugin.

Usage and Patterns

See the interactive glimmer tutorial: https://tutorial.glimdown.com

Notes

ember-template-imports easily provides a prototype of the features described by RFC#779, but embber-template-imports is not the final form of the <template> feature -- it as an easy way to set up the support today, but future techniques for enabling <template> will be easier. When reviewing the README for ember-template-imports, ignore everything about hbs, it will not be supported.

Example Projects using gjs/gts

Each of these projects is setup with linting, typechecking, etc

Hopefully they can be a reference for when issues are encountered upon setup