# @embroider/util

> Utilities for app and addon authors.

Latest version **1.13.5** (published 2025-12-02) · MIT license · 0 weekly downloads

## Install

```sh
npm install @embroider/util
pnpm add @embroider/util
yarn add @embroider/util
bun add @embroider/util
```

## Health

**Score 65/100 (B)** — status: stable.

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

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 1.13.5 |
| Published | 2025-12-02 |
| First published | 2020-11-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | 12.* \|\| 14.* \|\| >= 16 |
| Dependencies | 3 |
| Unpacked size | 12.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 354 |
| Maintainers | nullvoxpopuli, simonihmig, ef4, stefanpenner, turbo87, jenweber, rwjblue, katiegengler, real_ate |
| Keywords | ember-addon |

## Links

- npm: https://www.npmjs.com/package/@embroider/util
- Repository: https://github.com/embroider-build/embroider
- Homepage: https://github.com/embroider-build/embroider#readme
- Issues: https://github.com/embroider-build/embroider/issues
- npm.io page: https://npm.io/package/@embroider/util

## Dependencies (3)

- [broccoli-funnel](https://npm.io/package/broccoli-funnel.md) ^3.0.5
- [ember-cli-babel](https://npm.io/package/ember-cli-babel.md) ^7.26.11
- [@embroider/macros](https://npm.io/package/@embroider/macros.md) ^1.18.1

## Recent versions

- 1.13.5 (latest) — 2025-12-02
- 1.14.1-unstable.f26a1e3 (unstable) — 2025-03-20
- 1.14.0-alpha.2 (alpha) — 2025-03-14
- 1.13.4 — 2025-08-06
- 1.13.3 — 2025-06-18
- 1.14.1-unstable.c928e51 — 2025-03-20
- 1.14.1-unstable.5328667 — 2025-03-20
- 1.14.1-unstable.d6a5c13 — 2025-03-20
- 1.14.1-unstable.c065604 — 2025-03-20
- 1.14.1-unstable.93899f2 — 2025-03-18
- 1.14.1-unstable.13e4ba7 — 2025-03-18
- 1.14.1-unstable.cd221ee — 2025-03-18
- 1.14.1-unstable.bf0b55f — 2025-03-17
- 1.14.1-unstable.674bf3c — 2025-03-15
- 1.14.1-unstable.9587f29 — 2025-03-14
- … 492 more at https://npm.io/package/@embroider/util/versions

## README

# @embroider/util

Utilities to help apps and addons with Embroider support.

## Compatibility

- Ember.js v3.13 or above
- Ember CLI v2.13 or above
- Node.js v10 or above

## Installation

```
ember install @embroider/util
```

## The Utilities

### `ensureSafeComponent`

**This function is intended to help addon authors who still need to support Ember < 3.25**. In all other cases, instead of using this you should directly pass components around as values (not as strings) and invoke them directly with angle brackets (not the `{{component}}` helper).

For the full explanation of why and how you would use this, see [the Addon Author Guide](https://github.com/embroider-build/embroider/blob/main/docs/replacing-component-helper.md).

Example usage in Javascript:

```js
import { ensureSafeComponent } from '@embroider/util';
import Component from '@glimmer/component';
import DefaultTitleComponent from './default-title';

export default class extends Component {
  get title() {
    return ensureSafeComponent(this.args.title || DefaultTitleComponent, this);
  }
}
```

```hbs
<this.title />
```

Example usage in a template:

```hbs
{{#let
  (ensure-safe-component (or @title (component 'default-title')))
  as |Title|
}}
  <Title />
{{/let}}
```

The first argument is allowed to be:

- a string. If we see a string, we will emit a deprecation warning because passing components-as-strings doesn't work safely under Embroider with `staticComponents` enabled. We will return a value that is safe to invoke (via angle brackets) on your current Ember version.
- a curried component definition (which is the kind of value you receive when someone does `<YourComponent @customThing={{component "fancy"}}/>`). These are returned unchanged, because they're always safe to invoke.
- a component class, in which case if your ember version does not yet support directly invoking component classes, we will convert it to a curried component definition for you.

In the Javascript version, you must pass a second argument that is any object with an owner (a `Component` instance works great).

## Glint usage
If you are using [Glint](https://typed-ember.gitbook.io/glint/) and `environment-ember-loose`, you can add all the macros to your app at once by adding

```ts
import type { EmbroiderUtilRegistry } from "@embroider/util";
```
to your app's e.g. `types/glint.d.ts` file, and making sure your registry extends from EmbroiderMacrosRegistry:

```ts
declare module '@glint/environment-ember-loose/registry' {
  export default interface Registry
    extends EmbroiderUtilRegistry, /* other registries here */ {
      // ...
    }
}
```

## Contributing

See the [Contributing](CONTRIBUTING.md) guide for details.

## License

This project is licensed under the [MIT License](LICENSE.md).

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