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.

  /* 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.