nullvoxpopuli.com

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

For syntax highlighting:
- in neovim and VSCode, see here
- on the web,
  - highlight.js via highlightjs-glimmer
  - shiki has gjs support built in
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
```
{
  "compilerOptions": { /* ... */ },
  "glint": {
    "environment": [
      "ember-loose",
      "ember-template-imports"
    ]
  }
}
```
Note that in Glint projects, you'll want to disable tsserver, so you don't have double-reported errors.

For linting, there are two paths:

Quickest:
use configs.ember() from @nullvoxpopuli/eslint-configs
Modifying you're existing lint command:

  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)

   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):

"eslint.probe": [
 // ...
 "glimmer-js", 
 "glimmer-ts"
],
"eslint.validate": [
  // ...
  "glimmer-js",
  "glimmer-ts"
],
// ...
"prettier.documentSelectors": ["**/*.gjs", "**/*.gts"],

For neovim,

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 breaks neovim's built-in syntax resolving, so uninstall that if you have it (neovim ships with treesitter which has very extensive language support).

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

Install ember-template-imports.

If you use TypeScript,

update your babel config to have:

    "plugins": [
      [
        "@babel/plugin-transform-typescript",
        { "allExtensions": true, "onlyRemoveTypeImports": true, "allowDeclareFields": true }
      ],
      // ...

update your tsconfig.json to have (in compilerOptions)

  "verbatimModuleSyntax": true,

In a v1 Addon

Install ember-template-imports.
```
npm add ember-template-imports
```
it is important that this library be in dependencies, not devDependencies

If you use TypeScript,

update your babel config to have:

    "plugins": [
      [
        "@babel/plugin-transform-typescript",
        { "allExtensions": true, "onlyRemoveTypeImports": true, "allowDeclareFields": true }
      ],
      // ...

update your tsconfig.json to have (in compilerOptions)

  "verbatimModuleSyntax": true,
  "allowImportingTsExtensions": true,

In a v2 Addon

@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

<template> quickstart