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

• 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.

{{! 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>

{{! 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.

{{! 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 above1
• 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.