ember-css-modules

Ember-flavored support for CSS Modules. For an overview of some of the motivations for the CSS Modules concept, see this blog post.

If you have ideas or questions that aren't addressed here, try #topic-css on the Ember Discord Server.

• Installation
• What and Why?
• Usage
  • Simple Example
  • "Classic" Structure Applications
  • Styling Reuse
  • Programmatic Styles Access
  • Global Classes
  • Values
• Usage in Addons
• Plugins
• Advanced Configuration
  • Where to Specify Options
  • Scoped Name Generation
  • Source Maps
• Ember Support

Installation

ember install ember-css-modules

What and Why?

When you build a component, you drop a .js file and a .hbs file in your app directory, and your tooling takes care of the rest. Babel takes your fancy ES6 module and restructures it into nice browser-friendly code, while still giving you isolation and modularity guarantees. Meanwhile, the rest of the Ember CLI build pipeline picks up these new files and automatically incorporates them into your final JS artifact. And when it's time to come back and tweak your component, you (just like the Ember resolver) know exactly where those files live based just on the name of the component.

With ember-css-modules, your styling is a first-class citizen alongside your templates and JavaScript. You have one .css file per component (or route controller), in the same structure you're already using in the rest of your app. Every class you write is local to that file by default, with explicit mechanisms for opting into sharing, just like your JavaScript modules. And just like all your JS modules are automatically included in .js, your CSS modules will automatically be included in .css.

Usage

Simple Example

With ember-css-modules, you define styles on a per-component (or -controller) basis. You define these styles using the same file layout you use for templates; for example, in pod structure you'd put styles.css alongside template.hbs in the component's pod. The classes in that stylesheet are then automatically namespaced to the corresponding component or controller. In order to reference them, you use the local-class attribute rather than the standard class.

{{! app/components/my-component/template.hbs }}
<div>Hello, world!</div>

/* app/components/my-component/styles.css */
.hello-class {
  font-weight: bold;
}

Similarly, if you were styling e.g. your application controller, you would place your styles alongside controller.js in /application/styles.css.

"Classic" Structure Applications

In classic structure, all your modules are grouped by type rather than related functionality. Just like all your templates live in app/templates and all your routes live in app/routes, all your styles will live in app/styles. When determining where to put your CSS for a given controller or component, you should mirror the location of the corresponding template.

For example, the component given above in pod structure would look like this in classic structure:

{{! app/templates/components/my-component.hbs }}
<div>Hello, world!</div>

/* app/styles/components/my-component.css */
.hello-class {
  font-weight: bold;
}

Similarly, if you were styling e.g. your application controller, you would mirror the template at app/templates/application.hbs and put your CSS at app/styles/application.css.

Component Colocation in Octane Applications

In Octane apps, where component templates can be colocated with their backing class, your styles module for a component takes the same name as the backing class and template files:

{{! app/components/my-component.hbs }}
<div>Hello, world!</div>

/* app/components/my-component.css */
.hello-class {
  font-weight: bold;
}

Styling Reuse

In the example above, hello-class is rewritten internally to something like _hello-class_1dr4n4 to ensure it doesn't conflict with a hello-class defined in some other module.

For cases where class reuse is desired, there's the composes property. Suppose you have a title in your component that you'd like to inherit your app-wide "secondary header" styling, which itself uses generic styling shared by all headers:

/* app/styles/headers.css */
.header {
  font-weight: bold;
  text-decoration: underline;
}

.secondary-header {
  composes: header;
  color: #339;
}

/* app/components/my-component/styles.css */
.component-title {
  composes: secondary-header from 'my-app-name/styles/headers';
  background-color: #eee;
}

In the template for my-component, an element with local-class="component-title" will end up with an actual class string like _component-title_1dr4n4 _secondary-header_1658xu _header_1658xu, incorporating styles from all of the composing classes.

Note that you may also use relative paths to specify the source modules for composition.

Finally, you can compose local classes from global un-namespaced ones that are provided e.g. by a CSS framework by specifying global as the source of the class:

/* vendor/some-lib.css */
.super-important {
  color: orange;
}

/* app/components/my-component/styles.css */
.special-button {
  composes: super-important from global;
}

Programmatic Styles Access

Currently the local-class attribute is honored on HTML elements and component invocations, e.g. <div> and {{input local-class="baz"}}. It is not (currently) supported in subexpressions like the (component) helper.

If you need to access a local class in a template in other scenarios (such as passing in a class name as a property or reusing a class from another module), there is also a local-class helper you can use. For example, the "secondary-header" example above can be written as:

{{! app/components/my-component/template.hbs }}
<div class="{{local-class 'secondary-header' from='my-app-name/styles/headers'}}">Hello, world!</div>

Note that the from parameter is optional; by default classes will come from the current module, as with the local-class attribute.

In a JavaScript context, the class mappings can also be imported directly from whatever path the corresponding CSS module occupies, e.g.

import styles from 'my-app-name/components/my-component/styles';
console.log(styles['hello-class']);
// => "_hello-class_1dr4n4"

Note: by default, the import path for a styles module does not include the .css (or equivalent) extension. However, if you set includeExtensionInModulePath: true, then you'd instead write:

import styles from 'my-app-name/components/my-component/styles.css';

Note that the extension is always included for styles modules that are part of an Octane "colocated" component, to avoid a conflict with the import path for the component itself.

Applying Classes to a Component's Root Element

There is no root element, if you are using either of the following:

• Glimmer components (@glimmer/component)
• template-only components
• tag-less components

In this case, you can ignore this complete section and just use the local-class attribute or helper.

Ember Object Model

Just like using classNames and classNameBindings to set global classes on a component's root element, the localClassNames and localClassNameBindings properties allow you to set local classes on the root element.

For instance, to statically set a local my-component class on your component:

export default Ember.Component.extend({
  localClassNames: 'my-component'
});

To dynamically set one or more classes on your component based on the boolean value of a given property:

export default Ember.Component.extend({
  localClassNameBindings: ['propA', 'propB:special', 'propC:yes:no'],
  propA: true,
  propB: true,
  propC: true
});

• If propA is true, a local prop-a class will be applied. If it's false, no additional classes will be applied.
• If propB is true, a local special class will be applied. If it's false, no additional classes will be applied.
• If propC is true, a local yes class will be applied. If it's false, a local no class will be applied.

Native ES6 Class Syntax

The trusty Ember Object Model, that predates native ES6 class syntax, has served the community well over the years. But it's on its way out and you can already use the new native syntax in your apps today!

Instead of setting classNames and classNameBindings properties, you would use @classNames and @className decorators from the amazing ember-decorators addon. ember-css-modules provides the exact same decorators, but for local classes.

For instance, to statically set a local my-component class on your component, you use the @localClassNames decorator:

import Component from '@ember/component';
import { localClassNames } from 'ember-css-modules';

@localClassNames('my-component')
export default class ExampleComponent extends Component {
  // your kickass code here
}

Just as with @classNames you can pass as many classes as you like:

import Component from '@ember/component';
import { localClassNames } from 'ember-css-modules';

@localClassNames('my-component', 'make-it-pop', 'vibrant-colors')
export default class ExampleComponent extends Component {
  // your sensational code here
}

And just like you'd use @className to dynamically toggle classes on your component based on the boolean value of a given property, you use @localClassName for local classes:

import Component from '@ember/component';
import { localClassName } from 'ember-css-modules';

export default class ExampleComponent extends Component {
  @localClassName propA;
  @localClassName('special') propB;
  @localClassName('yes', 'no') propC;
}

• If propA is true, a local prop-a class will be applied. If it's false, no additional classes will be applied.
• If propB is true, a local special class will be applied. If it's false, no additional classes will be applied.
• If propC is true, a local yes class will be applied. If it's false, a local no class will be applied.

This is especially beautiful when combined with other decorators or computed properties:

import Component from '@ember/component';
import { computed } from '@ember-decorators/object';
import { notEmpty } from '@ember-decorators/object/computed';
import { localClassName } from 'ember-css-modules';

export default class ExampleComponent extends Component {
  user; // provided as an attr to the component

  @localClassName
  @notEmpty('user.lastName')
  hasLastName;

  @localClassName('the-good-stuff', 'soda-pop')
  @computed('user.age')
  get isOldEnoughToDrink() {
    return this.user.age >= 21;
  }
}

• If the property user.lastName is not empty, a local has-last-name class will be applied.
• If the user is at least of age 21, a local the-good-stuff class is applied, otherwise a local soda-pop class is applied.

You can even return strings from computed properties or decorate string properties in order to set local classes in a fully dynamic fashion:

import Component from '@ember/component';
import { computed } from '@ember-decorators/object';
import { reads } from '@ember-decorators/object/computed';
import { localClassName } from 'ember-css-modules';

export default class ExampleComponent extends Component {
  user; // provided as an attr to the component

  @localClass somethingDynamic = 'hello-world';

  @localClass
  @reads('user.favoriteColor')
  favoriteColor;

  @localClass
  @computed('user.usedTechnologies.[]')
  get coolness() {
    const { usedTechnologies } = this.user;
    const coolTech = ['TypeScript', 'Ember.js', 'ember-css-modules'];
    const coolUsedTech = coolTech.filter(t => usedTechnologies.includes(t));

    switch (coolUsedTech.length) {
      case 1: return 'cool';
      case 2: return 'pretty-rad'
      case 3: return 'rockstar';
    }

    return null;
  }
}

• The local hello-world class will be applied.
• If the property user.favoriteColor is 'red', a local red class will be applied.
• If the user uses all the cool technologies, the local rockstar class will be applied. If the user uses no cool technoloy, no further local class will be applied.

Global Classes

Some libraries provide explicit class names as part of their public interface in order to allow customization of their look and feel. If, for example, you're wrapping such a library in a component, you need to be able to reference those unscoped class names in the context of your component styles. The :global pseudoselector allows for this:

.my-component :global(.some-library-class) {
  color: orange;
}

For more details on :local and :global exceptions, see the CSS Modules documentation.

Values

For exposing data other than class names across module boundaries, you can use @value.

/* app/styles/colors.css */
@value primary-color: #8af;
@value secondary-color: #fc0;

/* app/some-route-pod/styles.css */
@value primary-color, secondary-color from 'my-app-name/styles/colors';

.blurb {
  color: primary-color;
  background-color: secondary-color;
}

Note that values are also exposed on the styles object for a given module, so they are also accessible from JavaScript if you need to coordinate between the two. As a contrived example:

// app/some-route-pod/controller.js
import styles from 'app/some-route-pod/styles';

export default Ember.Controller.extend({
  logColor() {
    console.log('primary color is', styles['primary-color']);
  }
});

Usage in Addons

You can also use ember-css-modules in addons that expose components to their consuming application. To do this you'll need to move ember-css-modules out of devDependencies and into dependencies in your addon's package.json (see issue #8).

Note also that your addon must have an addon/styles directory in order to trigger CSS processing in Ember CLI. In order for the directory to be preserved when you publish your addon, you can create an empty .placeholder file (.gitkeep won't work; by default, the .npmignore for your addon will prevent files with that name from being published).

Plugins

Ember CSS Modules has a plugin ecosystem that allows for people to bundle up common configurations and extensions for easy reuse and distribution. For example, if your organization has a common set of PostCSS plugins you always use, you could package those as a plugin and then just drop that into any Ember project and have it automatically take effect.

For details on developing your own, see the plugins mini-guide. You can also look at the following examples of what plugin implementations can look like:

• ember-css-modules-sass
• ember-css-modules-stylelint
• ember-css-modules-reporter

You can find a list of all publicly available plugins by browsing the npm ember-css-modules-plugin keyword.

Advanced Configuration

Details about specific advanced configuration options are broken out into smaller mini-guides that each focus on a single topic:

• Using CSS Modules with other preprocessors
• Working with PostCSS plugins
• Module ordering
• Defining values at build time with virtual modules
• Authoring ember-css-modules plugins

Where to Specify Options

For applications, custom configuration for ember-css-modules may be specified in ember-cli-build.js:

new EmberApp(defaults, {
  // ...
  cssModules: {
    // config
  }
});

For addons, configuration may be specified in your addon's index.js instead:

module.exports = {
  // ...
  options: {
    cssModules: {
      // config
    }
  }
};

Extensions in Module Paths

When importing a CSS module's values from JS, or referencing it via @value or composes:, by default you do not include the .css extension in the import path. The exception to this rule is for modules that are part of an Octane-style colocated component, as the extension is the only thing to differentiate the styles module from the component module itself.

If you wish to enable this behavior for all modules, you can set the includeExtensionInModulePath flag in your configuration:

new EmberApp(defaults, {
  cssModules: {
    includeExtensionInModulePath: true,
  },
});

Scoped Name Generation

By default, ember-css-modules produces a unique scoped name for each class in a module by combining the original class name with a hash of the path of the containing module. You can override this behavior by passing a generateScopedName function in the configuration.

new EmberApp(defaults, {
  cssModules: {
    generateScopedName(className, modulePath) {
      // Your logic here
    }
  }
});

Source Maps

Ember CLI allows you to specify source map settings for your entire build process, and ember-css-modules will honor that configuration. For instance, to enable source maps in all environments for both JS and CSS files, you could put the following in your ember-cli-build.js:

sourcemaps: {
  enabled: true,
  extensions: ['js', 'css']
}

Notes

• You should specify the css extension in your source map configuration even if you're using a different extension for your modules themselves, since the final output file will be a .css file.
• Currently CSS source maps (for any Ember CLI preprocessor) only work for applications, not for addons. Watch ember-cli/broccoli-concat#58 for progress on that front.
• Enabling source maps for CSS can cause Ember CLI to output an invalid comment at the end of your vendor.css file. This is harmless in many situations, but can cause issues with tools that postprocess your css, like ember-cli-autoprefixer. ember-cli/broccoli-concat#58 is the root cause of this issue as well.

Ember Support

This addon is tested against and expected to work with Ember's active LTS releases as well as the current release, beta, and canary builds.

Note that if you're using ember-css-modules with a version of Ember CLI prior to 2.13, you'll need to add the following to your app.js:

import 'ember-css-modules/extensions';
```</div>