embroider-css-modules

CSS modules for Embroider projects

1. What is it?
2. Installation
3. API
   • Helper: {{local}}
4. Compatibility
5. Contributing
6. 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.