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.

/* types/global.d.ts */

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
  }
}

If you are using <template> tag, you are good to go! Use the named import to consume things.

/* app/components/hello-world.css */
.container {
  padding: 1rem;
}

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

import styles from './hello-world.css';

<template>
  <div class={{localClass styles "container"}}>
    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 apply multiple styles when a conditional statement holds, use the {{array}} helper.

Example

{{! app/templates/products.hbs }}
<div
  class={{local
    this.styles
    (if
      this.isInExperimentalGroup
      (array "shared-layout" "products-with-details")
      (array "shared-layout" "products")
    )
    "sticky-container"
  }}
>
  ...
</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-auto-import@v2¹
Ember.js v4.4 or above²
Node.js v18 or above

^{1. embroider-css-modules is a v2 addon. This means, your project must have ember-auto-import@v2. If you are momentarily stuck with ember-auto-import@v1, you can use ember-css-modules to implement CSS modules.}

^{2. Older versions may work but won't be supported.}

Contributing

See the Contributing guide for details.

License

This project is licensed under the MIT License.