# ember-template-recast

> Non-destructive template transformer.

Latest version **6.1.5** (published 2024-07-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install ember-template-recast
pnpm add ember-template-recast
yarn add ember-template-recast
bun add ember-template-recast
```

Provides the command `ember-template-recast`.

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 6.1.5 |
| Published | 2024-07-24 |
| First published | 2018-05-16 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | 12.* \|\| 14.* \|\| >= 16.* |
| Dependencies | 11 |
| Unpacked size | 128.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Robert Jackson |
| Maintainers | rwjblue, scalvert, turbo87, bmishkin, krisselden, stefanpenner, dcyriller |
| Keywords | codemod, ember, glimmer, handlebars, recast, templates |

## Links

- npm: https://www.npmjs.com/package/ember-template-recast
- Repository: https://github.com/ember-template-lint/ember-template-recast
- Issues: https://github.com/ember-template-lint/ember-template-recast/issues
- npm.io page: https://npm.io/package/ember-template-recast

## Dependencies (11)

- [ora](https://npm.io/package/ora.md) ^5.4.0
- [tmp](https://npm.io/package/tmp.md) ^0.2.1
- [slash](https://npm.io/package/slash.md) ^3.0.0
- [colors](https://npm.io/package/colors.md) ^1.4.0
- [globby](https://npm.io/package/globby.md) ^11.0.3
- [commander](https://npm.io/package/commander.md) ^8.3.0
- [workerpool](https://npm.io/package/workerpool.md) ^6.4.0
- [@glimmer/syntax](https://npm.io/package/@glimmer/syntax.md) ^0.84.3
- [@glimmer/reference](https://npm.io/package/@glimmer/reference.md) ^0.84.3
- [@glimmer/validator](https://npm.io/package/@glimmer/validator.md) ^0.84.3
- [async-promise-queue](https://npm.io/package/async-promise-queue.md) ^1.0.5

## Recent versions

- 6.1.5 (latest) — 2024-07-24
- 6.1.4 — 2023-03-28
- 6.1.3 — 2022-01-14
- 6.1.2 — 2021-12-10
- 6.1.1 — 2021-12-08
- 6.1.0 — 2021-11-18
- 6.0.0 — 2021-11-08
- 5.0.3 — 2021-05-19
- 5.0.2 — 2021-05-19
- 5.0.1 — 2020-11-26
- 5.0.0 — 2020-11-04
- 4.3.0 — 2020-11-04
- 4.2.1 — 2020-10-14
- 4.2.0 — 2020-10-02
- 4.1.7 — 2020-10-02
- … 41 more at https://npm.io/package/ember-template-recast/versions

## README

# ember-template-recast

[![NPM version](https://img.shields.io/npm/v/ember-template-recast.svg?style=flat)](https://npmjs.org/package/ember-template-recast)

With ember-template-recast, transform a template's AST and reprint it. Its
formatting will be preserved.

For instance, it is possible to change a component's property while preserving
its formatting:

```js
const recast = require('ember-template-recast');

const template = `
<Sidebar
  foo="bar"
     item={{hmmm}}
/>
`;

// parse
let ast = recast.parse(template);

// transform
ast.body[1].attributes[1].value.path = builders.path('this.hmmm');

// print
let ouput = recast.print(ast);

output === `
<Sidebar
  foo="bar"
     item={{this.hmmm}}
/>
`; // is true!
```

## Command Line Usage

ember-template-recast comes with a binary for running a transform across multiple
files, similar to jscodeshift.

```sh
npx ember-template-recast directory/of/templates -t transform.js
```

Example transform plugin:

```js
module.exports = (env) => {
  let { builders: b } = env.syntax;

  return {
    MustacheStatement() {
      return b.mustache(b.path('wat-wat'));
    },
  };
};
```

## APIs

### parse

Used to parse a given template string into an AST. Generally speaking, this AST
can be mutated and passed into `print` (docs below).

```js
const templateRecast = require('ember-template-recast');
const template = `
{{foo-bar
  baz="stuff"
}}
`;
let ast = templateRecast.parse(template);
// now you can work with `ast`
```

### print

Used to generate a new template string representing the provided AST.

```js
const templateRecast = require('ember-template-recast');
const template = `
{{foo-bar
  baz="stuff"
}}
`;
let ast = templateRecast.parse(template);
ast.body[0].hash[0].key = 'derp';

templateRecast.print(ast);

    {{foo-bar
      derp="stuff"
    }}
```

### transform

Used to easily traverse (and possibly mutate) a given template. Returns the
resulting AST and the printed template.

The plugin argument has roughly the following interface:

```ts
export interface Syntax {
  parse: typeof preprocess;
  builders: typeof builders;
  print: typeof print;
  traverse: typeof traverse;
  Walker: typeof Walker;
}

export interface TransformPluginEnv {
  syntax: Syntax;
  contents: string;
  filePath?: string;
  parseOptions: {
    srcName?: string;
  };
}

export interface TransformPluginBuilder {
  (env: TransformPluginEnv): NodeVisitor;
}
```

The list of known builders on the `env.syntax.builders` are [found
here](https://github.com/glimmerjs/glimmer-vm/blob/v0.82.0/packages/%40glimmer/syntax/lib/v1/public-builders.ts#L530),
although there are a few small extensions related to formatting
[in `custom-nodes.ts`](src/custom-nodes.ts)

Example:

```js
const { transform } = require('ember-template-recast');

const template = `
{{foo-bar
  baz="stuff"
}}
`;

let { code } = transform({
  template,
  plugin(env) {
    let { builders: b } = env.syntax;

    return {
      MustacheStatement() {
        return b.mustache(b.path('wat-wat'));
      },
    };
  }
});

console.log(code); // => {{wat-wat}}
```

## SemVer Policy

Due to usage of TypeScript and bundling external APIs this project has somewhat
unique SemVer commitments. A high level summary is:

### Major Version

The following are scenarios that would cause a major version (aka breaking change) release:

* Dropping support for Node versions (e.g. dropping Node 12 support)
* Non-additive changes to the underlying AST (which we bundle from `@glimmer/syntax`)
* Breaking changes to the `@glimmer/syntax` builder APIs

### Minor Version

The following are scenarios that would cause a minor version (aka new feature) release:

* Changes to TypeScript version used internally by `ember-template-recast`
* Changes to make the types used by `ember-template-recast` to be more accurate
  (e.g. narrowing / broadening of previously published types).
* Adding new features

### Patch Version

The following are scenarios that would cause a patch release:

* Bug fixes to internal re-writing logic
* Bug fix releases of `@glimmer/syntax`

## License

This project is distributed under the MIT license, see [LICENSE](./LICENSE) for details.

---
_Source: https://npm.io/package/ember-template-recast · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._