diff --git a/README.md b/README.md index b58bd29..ad23694 100644 --- a/README.md +++ b/README.md @@ -1,126 +1,43 @@ - + + + + CSS Modules Logo + # CSS Modules -A **CSS Module** is a CSS file in which all class names and animation names are scoped locally by default. All URLs (`url(...)`) and `@imports` are in module request format (`./xxx` and `../xxx` means relative, `xxx` and `xxx/yyy` means in modules folder, i. e. in `node_modules`). +A **CSS Module** is a CSS file where all class names and animation names are scoped locally by default. All URLs (`url(...)`) and `@imports` are in module request format (`./xxx` and `../xxx` means relative, `xxx` and `xxx/yyy` means in modules folder, i.e. in `node_modules`). -CSS Modules compile to a low-level interchange format called ICSS or [Interoperable CSS](https://github.com/css-modules/icss), but are written like normal CSS files: +CSS Modules compile to a low-level interchange format called ICSS (or [Interoperable CSS](https://github.com/css-modules/icss)) but are written like normal CSS files: -``` css +```css /* style.css */ .className { color: green; } ``` -When importing the **CSS Module** from a JS Module, it exports an object with all mappings from local names to global names. +When importing a **CSS Module** from a JavaScript Module, it exports an object with all mappings from local names to global names. -``` js -import styles from "./style.css"; -// import { className } from "./style.css"; +```js +import styles from './style.css'; element.innerHTML = '
'; ``` -## Naming +## Table of Contents -For local class names camelCase naming is recommended, but not enforced. +- [Get Started & Examples](/docs/get-started.md) +- [Naming](/docs/naming.md) +- [Composition](/docs/composition.md) +- [Local Scope](/docs/local-scope.md) +- [History](/docs/history.md) +- [Pseudo Class Selectors](/docs/pseudo-class-selectors.md) +- [Theming](/docs/theming.md) -## Exceptions +## Why CSS Modules? -`:global` switches to global scope for the current selector resp. identifier. `:global(.xxx)` resp. `@keyframes :global(xxx)` declares the stuff in brackets in the global scope. - -Similar `:local` and `:local(...)` for local scope. - -If the selector is switched into global mode, global mode is also activated for the rules. (this allows to make `animation: abc;` local) - -Example: `.localA :global .global-b .global-c :local(.localD.localE) .global-d` - -## Composition - -It's possible to compose selectors. - -``` css -.className { - color: green; - background: red; -} - -.otherClassName { - composes: className; - color: yellow; -} -``` - -There can be multiple `composes` rules, but `composes` rules must be before other rules. Extending works only for local-scoped selectors and only if the selector is a single class name. When a class name composes another class name, the **CSS Module** exports both class names for the local class. This can add up to multiple class names. - -It's possible to compose multiple classes with `composes: classNameA classNameB;`. - -## Dependencies - -It's possible to compose class names from other **CSS Modules**. - -``` css -.otherClassName { - composes: className from "./style.css"; -} -``` - -Note that when composing multiple classes from different files the order of appliance is *undefined*. Make sure to not define different values for the same property in multiple class names from different files when they are composed in a single class. - -Note that composing should not form a circular dependency. Elsewise it's *undefined* whether properties of a rule override properties of a composed rule. The module system may emit an error. - -Best if classes do a single thing and dependencies are hierarchic. - - -## Usage with preprocessors - -Preprocessors can make it easy to define a block global or local. - -i. e. with less.js - -``` less -:global { - .global-class-name { - color: green; - } -} -``` - -## Why? - -**modular** and **reusable** CSS! - -* No more conflicts. -* Explicit dependencies. -* No global scope. - -## Examples - -* [css-modules/webpack-demo](https://github.com/css-modules/webpack-demo) -* [Theming](examples/theming.md) - - -## History - -* 04/2015: `placeholders` feature in css-loader (webpack) allows local scoped selectors (later renamed to `local scope`) by @sokra -* 05/2015: `postcss-local-scope` enables `local scope` by default (see [blog post](https://medium.com/seek-ui-engineering/the-end-of-global-css-90d2a4a06284)) by @markdalgleish -* 05/2015: `extends` feature in css-loader allow to compose local or imported class names by @sokra -* 05/2015: First CSS Modules spec document and github organization with @sokra, @markdalgleish and @geelen -* 06/2015: `extends` renamed to `composes` -* 06/2015: PostCSS transformations to transform CSS Modules into an intermediate format (ICSS) -* 06/2015: Spec for ICSS as common implementation format for multiple module systems by @geelen -* 06/2015: Implementation for jspm by @geelen and @guybedford -* 06/2015: Implementation for browserify by @joshwnj, @joshgillies and @markdalgleish -* 06/2015: webpack's css-loader implementation updated to latest spec by @sokra - - -## Implementations - -### webpack - -Webpack's [css-loader](https://github.com/webpack/css-loader) in module mode replaces every local-scoped identifier with a global unique name (hashed from module name and local identifier by default) and exports the used identifier. - -Extending adds the source class name(s) to the exports. - -Extending from other modules first imports the other module and then adds the class name(s) to the exports. +- **Local Scope Prevents Clashes:** CSS Modules use local scope to avoid style conflicts across different project parts, allowing component-scoped styling. +- **Clear Style Dependencies:** Importing styles into their respective components clarifies which styles impact which areas, enhancing code readability and maintenance. +- **Solves Global Scope Problems:** CSS Modules prevent the common issue of styles in one file affecting the entire project by localizing styles to specific components. +- **Boosts Reusability and Modularity:** CSS Modules allow the same class names in different modules, promoting modular, reusable styling. diff --git a/docs/composition.md b/docs/composition.md new file mode 100644 index 0000000..f30e87e --- /dev/null +++ b/docs/composition.md @@ -0,0 +1,111 @@ + + + + CSS Modules Logo + + +# Composition + +You can compose selectors together with `composes`: + +```css +.className { + color: green; + background: red; +} + +.otherClassName { + composes: className; + color: yellow; +} +``` + +There can be multiple `composes` rules, but `composes` rules must be before other rules. Extending works only for local-scoped selectors and only if the selector is a single class name. When a class name composes another class name, the **CSS Module** exports both class names for the local class. This can add up to multiple class names. + +It's also possible to compose multiple classes with `composes: classNameA classNameB;`. + +### Pseudo classes + +Classes which have pseudo selectors attached will be brought along when used in +a `composes` statement. + +In the example below, `otherClassName` will also be given the `:hover` pseudo +class defined on `className`. + +```css +.className { + color: green; +} + +.className:hover { + color: red; +} + +.otherClassName { + composes: className; + background: black; +} +``` + +`otherClassName` above is the same as defining: + +```css +.otherClassName { + color: green; + background: black; +} + +.otherClassName:hover { + color: red; +} +``` + +## Dependencies + +### Composing from other files + +It's possible to compose class names from other **CSS Modules**. + +```css +.otherClassName { + composes: className from './style.css'; +} +``` + +When composing multiple classes from different files, the order of appliance is _undefined_. Do not define different values for the same property in multiple class names from different files when they are composed in a single class. + +Composing should not form a circular dependency. Otherwise, it's _undefined_ whether properties of a rule override properties of a composed rule. The module system may emit an error. + +We recommend that classes do a single thing and dependencies are hierarchic. + +### Composing from global class names + +It's possible to compose from **global** class names. + +```css +.otherClassName { + composes: globalClassName from global; +} +``` + +## Exceptions + +`:global` switches to global scope for the current selector respective identifier. `:global(.xxx)` respective `@keyframes :global(xxx)` declares the stuff in parenthesis in the global scope. + +Similarly, `:local` and `:local(...)` for local scope. + +```css +:global(.some-selector) { + /* ... */ +} +``` + +If the selector is switched into global mode, global mode is also activated for the rules. (This allows us to make `animation: abc;` local.) + +Example: `` + +```css +.localA :global .global-b .global-c :local(.localD.localE) .global-d { + /* ... */ +} +``` diff --git a/docs/get-started.md b/docs/get-started.md index c8da915..7f48a35 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,43 +1,77 @@ - + + + + CSS Modules Logo + # Setting up CSS Modules CSS Modules works by compiling individual CSS files into both CSS and data. The CSS output is normal, global CSS, which can be injected directly into the browser or concatenated together and written to a file for production use. The data is used to map the human-readable names you've used in the files to the globally-safe output CSS. -There are currently 4 ways to integrate CSS Modules into your project. You should look to each of these projects for more detailed setup instructions. +## Tools + +### Bun + +Bun supports CSS Modules. [Learn more](https://bun.sh/docs/bundler). + +### Lightning CSS + +Lightning CSS supports almost all features of CSS Modules. [Learn more](https://lightningcss.dev/css-modules.html). + +### Parcel + +Parcel supports CSS Modules. [Learn more](https://parceljs.org/languages/css/#css-modules). + +### PostCSS + +PostCSS supports CSS Modules through the plugin `postcss-modules`. [Learn more](https://www.npmjs.com/package/postcss-modules). + +### Rspack + +Rspack supports CSS Modules. [Learn more](https://www.rspack.dev/guide/language-support#css-modules). ### Webpack -The [css-loader](https://github.com/webpack/css-loader) has CSS Modules built-in. Simply activate it by using the `?modules` flag. We maintain an example project using this at [css-modules/webpack-demo](https://github.com/css-modules/webpack-demo). +The [css-loader](https://github.com/webpack/css-loader) has CSS Modules built-in. Simply activate it by using the `?modules` flag. We maintain an example project using this at [css-modules/webpack-demo](https://css-modules.github.io/webpack-demo/). + +### Vite + +Vite supports CSS Modules through Lightning CSS. [Learn more](https://vitejs.dev/guide/features#css-modules). + +## Frameworks + +### Angular + +Angular supports CSS Modules through `postcss-modules` and `posthtml-css-modules`. [Learn more](https://angularindepth.com/posts/1294/angular-css-modules). + +### Astro + +Astro supports CSS Modules. [Learn more](https://docs.astro.build/en/guides/styling/). -### Browserify +### Create React App -The plugin [css-modulesify](https://github.com/css-modules/css-modulesify) gives your Browserify build the ability to `require` a CSS file and compile it as a CSS Module. For an example project using this setup, check out [css-modules/browserify-demo](https://github.com/css-modules/browserify-demo). +Create React App supports CSS Modules. [Learn more](https://create-react-app.dev/docs/adding-a-css-modules-stylesheet/). -### JSPM +### Ember -The experimental JSPM loader [jspm-loader-css-modules](https://github.com/geelen/jspm-loader-css-modules) adds CSS Modules support to SystemJS & JSPM. There's a simple project using this at [css-modules/jspm-demo](https://github.com/css-modules/jspm-demo). - -### NodeJS +Ember supports CSS Modules through `ember-css-modules`. [Learn more](https://github.com/salsify/ember-css-modules). -The [css-modules-require-hook](https://github.com/css-modules/css-modules-require-hook) works similarly to the Browserify plugin, but patches NodeJS's `require` to interpret CSS files as CSS Modules. This gives complete flexibility in how the output is handled, ideal for server-side rendering. +### Next.js -## Language integrations +Next.js supports CSS Modules for both webpack and Turbopack (`next dev --turbo`). [Learn more](https://nextjs.org/docs/app/building-your-application/styling/css-modules). -### React +### Nuxt -If you're using React, CSS Modules is a great fit. The [react-css-modules](https://github.com/gajus/react-css-modules) adds a `CSSModules` higher-order component or `@CSSModules` annotation for better integrating CSS Modules & React. +Nuxt supports CSS Modules. [Learn more](https://nuxt.com/docs/getting-started/styling#css-modules). -## Example projects +### Remix -As we find examples in the wild, we'll add them here (or edit this and add a PR). +Remix supports CSS Modules. [Learn more](https://remix.run/docs/en/main/styling/css-modules). -* [cssmodul.es](https://github.com/StevenIseki/cssmodul.es) - search for css modules on npm +### Solid -### Webpack Boilerplates +Solid supports CSS Modules. [Learn more](https://docs.solidjs.com/guides/how-to-guides/styling-in-solid/css-modules). -- [ultimate hot reloading example](https://github.com/glenjamin/ultimate-hot-reloading-example) by Glen Mailer -- [neob](https://github.com/juliocesar/neob) by Julio Ody -- [ng-modular](https://github.com/nkbt/ng-modular) by Nik Butenko -- [angular-cssmodules-example-app](https://github.com/jonathaningram/angular-cssmodules-example-app) by Jonathan Ingram +### Svelte +Svelte supports CSS Modules through the preprocessor `svelte-preprocess-cssmodules`. [Learn more](https://github.com/micantoine/svelte-preprocess-cssmodules). diff --git a/docs/history.md b/docs/history.md new file mode 100644 index 0000000..1ba1285 --- /dev/null +++ b/docs/history.md @@ -0,0 +1,18 @@ + + + + CSS Modules Logo + + +# History + +- 04/2015: `placeholders` feature in css-loader (webpack) allows local scoped selectors (later renamed to `local scope`) by @sokra +- 05/2015: `postcss-local-scope` enables `local scope` by default (see [blog post](https://medium.com/seek-ui-engineering/the-end-of-global-css-90d2a4a06284)) by @markdalgleish +- 05/2015: `extends` feature in css-loader allow to compose local or imported class names by @sokra +- 05/2015: First CSS Modules spec document and github organization with @sokra, @markdalgleish and @geelen +- 06/2015: `extends` renamed to `composes` +- 06/2015: PostCSS transformations to transform CSS Modules into an intermediate format (ICSS) +- 06/2015: Spec for ICSS as common implementation format for multiple module systems by @geelen +- 06/2015: Implementation for jspm by @geelen and @guybedford +- 06/2015: Implementation for browserify by @joshwnj, @joshgillies and @markdalgleish +- 06/2015: webpack's css-loader implementation updated to latest spec by @sokra diff --git a/docs/import-multiple-css-modules.md b/docs/import-multiple-css-modules.md new file mode 100644 index 0000000..de77da7 --- /dev/null +++ b/docs/import-multiple-css-modules.md @@ -0,0 +1,48 @@ + + + + CSS Modules Logo + + +# Import multiple css modules into a component + +You can import multiple CSS Modules into a component or function using `Object.assign`. + +For example, if you import a button CSS Module to your `Demo` component, add this to the components default styles. + +```js +let styles = {}; +import demo from './Demo.css'; +import fancyButton from 'css-fancy-button'; +Object.assign(styles, fancyButton, demo); +``` + +You can even import css modules installed from npm. e.g. [pure-css](https://github.com/StevenIseki/pure-css) + +```sh +npm install pure-css --save-dev +``` + +Then in your component, start using pure CSS styles. + +```js +import { buttons, grids } from 'pure-css'; +``` + +A full example of a demo component with 2 css modules imported. + +```jsx +import React from 'react'; +let styles = {}; +import demo from './Demo.css'; +import fancyButton from 'css-fancy-button'; +Object.assign(styles, fancyButton, demo); + +export default function Demo() { + return ( +
+ +
+ ); +} +``` diff --git a/docs/local-scope.md b/docs/local-scope.md index 83b60b1..2d6180b 100644 --- a/docs/local-scope.md +++ b/docs/local-scope.md @@ -1,28 +1,35 @@ - + + + + CSS Modules Logo + # CSS Modules — Local Scope -The first and most fundamental feature of CSS Modules is that class selectors, by default, are **local**. So, if you write: +CSS Modules have class selectors scoped locally by default. For example, the following classes `backdrop`, `prompt` & `pullquote` are _local to that file_. ```css -.backdrop {} -.prompt {} -.pullquote {} +.backdrop { +} +.prompt { +} +.pullquote { +} ``` -the classes `backdrop`, `field` & `pullquote` are *local to that file*. That means they don't pollute the global namespace, so you're free to use any name you like. You compile them by importing or requiring them in your JS file. These examples will be using React syntax, but of course it's not tied to React in any particular way. +They do not pollute the global namespace, so you're free to use any name you like. You compile them by importing or requiring them in your JavaScript file. ```js -import styles from "./style.css" +import styles from './style.css'; -const Component = props => { +export function Component(props) { return (
-
-
-
-
-
- ) +
+
+
+ ); } ``` + +> **Note:** These examples use React syntax, but of course it's not tied to React in any particular way. diff --git a/docs/naming.md b/docs/naming.md new file mode 100644 index 0000000..0730c38 --- /dev/null +++ b/docs/naming.md @@ -0,0 +1,11 @@ + + + + CSS Modules Logo + + +# Naming + +We recommend camelCase for local class names. + +While not enforced, camelCase is preferred as kebab-case may cause unexpected behavior when trying to access `styles.class-name` with dot notation. You can still work around kebab-case with bracket notation (e.g. `styles['class-name']`) but `styles.className` is preferred. diff --git a/docs/pseudo-class-selectors.md b/docs/pseudo-class-selectors.md new file mode 100644 index 0000000..8d17466 --- /dev/null +++ b/docs/pseudo-class-selectors.md @@ -0,0 +1,31 @@ + + + + CSS Modules Logo + + +# Pseudo class selectors + +CSS Modules also support adding pseudo class selectors: + +```css +/* component/text.css */ +.text { + color: #777; + font-weight: 24px; +} + +.text:hover { + color: #f60; +} +``` + +```js +/* component/text.js */ +import styles from './text.css'; +import React from 'react'; + +export function Text() { + return

Text with hover

; +} +``` diff --git a/docs/theming.md b/docs/theming.md new file mode 100644 index 0000000..63d574b --- /dev/null +++ b/docs/theming.md @@ -0,0 +1,52 @@ + + + + CSS Modules Logo + + +# Theming + +Instead of importing a style in the component, the component can take a style as property. This way different themes can be used. The user can even define custom themes. + +```css +/* component/theme-a.css */ +.outer { + background: green; +} +.inner { + color: blue; +} +``` + +```css +/* component/theme-b.css */ +.outer { + background: red; +} +.inner { + color: yellow; +} +``` + +```js +/* component/index.js */ +export function Component({ theme }) { + return ( +
+
+
+ ); +} +``` + +```js +import themeA from 'component/theme-a.css'; +import themeB from 'component/theme-b.css'; +import customTheme from './custom-theme.css'; + +import {Component} from 'component'; + + + + +``` diff --git a/docs/using-css-modules-with-angular.md b/docs/using-css-modules-with-angular.md deleted file mode 100644 index 2e947b6..0000000 --- a/docs/using-css-modules-with-angular.md +++ /dev/null @@ -1,35 +0,0 @@ - - -# Using CSS Modules with Angular - -```css -.bacon { /* ... */ } -.pancakes { /* ... */ } -``` - -```js -import styles from "./component.css" - -angular.module('myApp').controller('MyController', ($scope) => { - $scope.styles = styles -}) -``` - -```html -
-
-
-

- -

-
-
-``` - ---- - -**This needs expansion/revision by someone who really knows angular. Maybe that's you!** - -- [ ] Controller vs Directive examples/rationale -- [ ] Angular 2.0 syntax -- [ ] Is that even how people are doing Angular 1 these days? It's been so long. diff --git a/docs/values-variables.md b/docs/values-variables.md new file mode 100644 index 0000000..17bf006 --- /dev/null +++ b/docs/values-variables.md @@ -0,0 +1,68 @@ + + + + CSS Modules Logo + + +# Exporting values variables + +You can export values with css modules similar to using variables in less or sass. + +Just ensure you are using postcss and the [postcss-modules-values](https://github.com/css-modules/postcss-modules-values) plugin + +Now you set up your values/variables + +**colors.css** + +```css +@value blue: #0c77f8; +@value red: #ff0000; +@value green: #aaf200; +``` + +then import them into your components css module + +**demo.css** + +```css +/* import your colors... */ +@value colors: "./colors.css"; +@value blue, red, green from colors; + +.button { + color: blue; + display: inline-block; +} +``` + +## Example webpack.config for postcss-modules-values + +```js +var path = require('path'); +var webpack = require('webpack'); +var ExtractTextPlugin = require('extract-text-webpack-plugin'); +var values = require('postcss-modules-values'); + +module.exports = { + entry: ['./src/index'], + output: { + filename: 'bundle.js', + path: path.join(__dirname, 'public'), + publicPath: '/public/', + }, + module: { + loaders: [ + { test: /\.js$/, loader: 'babel-loader', exclude: /node_modules/ }, + { + test: /\.css$/, + loader: ExtractTextPlugin.extract( + 'style-loader', + 'css-loader?modules&importLoaders=1&localIdentName=[name]__[local]___[hash:base64:5]!postcss-loader' + ), + }, + ], + }, + postcss: [values], + plugins: [new ExtractTextPlugin('style.css', { allChunks: true })], +}; +``` diff --git a/examples/pseudo-class-selectors.md b/examples/pseudo-class-selectors.md deleted file mode 100644 index b2be85a..0000000 --- a/examples/pseudo-class-selectors.md +++ /dev/null @@ -1,29 +0,0 @@ -### Pseudo class selectors -Because css modules works by adding classes to your elements you can easily add pseudo class selectors. - -```css -/* component/text.css */ -.text { - color: #777; - font-weight: 24px; -} -.text:hover { - color: #f60; -} -``` -``` js -/* component/text.js */ -import styles from './text.css'; - -import React, { Component } from 'react'; - -export default class Text extends Component { - - render() { - return ( -

Text with hover

- ); - } - -}; -``` diff --git a/examples/theming.md b/examples/theming.md deleted file mode 100644 index 7d74d08..0000000 --- a/examples/theming.md +++ /dev/null @@ -1,44 +0,0 @@ -### Theming - -Instead of importing a style in the component, the component can take a style as property. This way different themes can be used. The user can even define custom themes. - -``` css -/* component/theme-a.css */ -.outer { background: green; } -.inner { color: blue; } -``` - -``` css -/* component/theme-b.css */ -.outer { background: red; } -.inner { color: yellow; } -``` - -``` js -/* component/index.js */ -export default class Component { - constructor(theme) { - this.theme = theme; - } - render() { - var theme = this.theme; - return '
' + - '
' + - '
'; - } -} -``` - -``` js -/* application */ -import themeA from "component/theme-a.css"; -import themeB from "component/theme-b.css"; -import customTheme from "./custom-theme.css"; - -import Component from "component"; - -// use the Component -new Component(themeA); -new Component(themeB); -new Component(customTheme); -```