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.12 or above
Node.js v20 or above

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.