embroider-css-modules

CSS modules for Embroider projects

What is it?
Installation
API
- Helper: {{local}}
Compatibility
Contributing
License

What is it?

embroider-css-modules provides a set of tools and conventions to help you implement CSS modules. It is compatible with "bleeding-edge" Ember:

Embroider on the strictest settings (including route splitting)
TypeScript + Glint
<template> tag

Installation

ember install embroider-css-modules

Use Glint or <template> tag? ✨

Update your template registry to extend this addon's. Check the Glint documentation for more information.

import '@glint/environment-ember-loose';

import type EmbroiderCssModulesRegistry from 'embroider-css-modules/template-registry';

declare module '@glint/environment-ember-loose/registry' {
  export default interface Registry extends EmbroiderCssModulesRegistry, /* other addon registries */ {
    // local entries
  }
}

In a <template> tag, use the named import to consume the {{local}} helper.

/* app/components/hello.css */
.message {
  align-items: center;
  display: flex;
  height: 100%;
  justify-content: center;
}

.emphasize {
  font-size: 64px;
  font-style: italic;
}

/* app/components/hello.gts */
import { local } from 'embroider-css-modules';

import styles from './hello.css';

<template>
  <div class={{local styles "message" "emphasize"}}>
    Hello world!
  </div>
</template>

API

The addon provides 1 helper:

{{local}}

Throughout the section, you can assume that there is a styles object, which maps local class names to global ones.

// An example
const styles = {
  'container': 'lzeQ4',
  'is-inline': 'mJGCE',
  'is-wide': '_2lPSR',
  'no-feedback': 'YpQbt',
};

Helper: {{local}}

Why use it?

The {{local}} helper is useful when you want to apply multiple styles.

Before: With the {{concat}} helper

{{! app/components/ui/form/field.hbs }}
<div
  class={{concat
    this.styles.container
    " "
    (if @isInline this.styles.is-inline)
    " "
    (if @isWide this.styles.is-wide)
    " "
    (unless @errorMessage this.styles.no-feedback)
  }}
>
  ...
</div>

After: With the {{local}} helper

{{! app/components/ui/form/field.hbs }}
<div
  class={{local
    this.styles
    "container"
    (if @isInline "is-inline")
    (if @isWide "is-wide")
    (unless @errorMessage "no-feedback")
  }}
>
  ...
</div>

To conditionally apply multiple styles, use the {{array}} helper.

Example

{{! app/components/hello.hbs }}
<div
  class={{local
    this.styles
    "message"
    (if this.someCondition (array "hide" "after-3-sec"))
  }}
>
  Hello world!
</div>

Arguments

The {{local}} helper uses positional arguments so that styles are applied in sequence. Pass the styles object first, then the local class name(s).

Outputs

The {{local}} helper returns a concatenated string. The string lists the global class names in the same order as the local ones.

Compatibility

Ember.js v4.4 or above¹
Node.js v18 or above

^{1. embroider-css-modules works on older versions (e.g. 3.28), but issues that arise from these may not be supported.}

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.