From 8ef2c808d05cfc1c8ed2d9ff1bea47b9395b80de Mon Sep 17 00:00:00 2001 From: ijlee2 Date: Fri, 15 Mar 2024 09:43:14 +0100 Subject: [PATCH 1/2] refactor: Updated documentations --- README.md | 6 +- .../migrate-from-ember-css-modules.md | 32 ++- .../migrate-from-ember-modern-css.md | 8 +- .../written-guides/set-up-css-modules-apps.md | 232 ++++++++++-------- .../set-up-css-modules-v2-addons.md | 62 +++-- packages/embroider-css-modules/README.md | 48 ++-- packages/type-css-modules/README.md | 29 +-- 7 files changed, 225 insertions(+), 192 deletions(-) diff --git a/README.md b/README.md index 1aca9831..9a0c7001 100644 --- a/README.md +++ b/README.md @@ -51,7 +51,9 @@ What `embroider-css-modules` looks like is: - Quite stable for apps - Quite stable for v2 addons -- Unknown for v1 addons (including engines) +- Unknown for v1 addons (including engines) - likely won't be implemented + +Non-Embroider projects can use [`ember-css-modules`](https://github.com/salsify/ember-css-modules). V2 addons that use `embroider-css-modules` do work on non-Embroider projects, i.e. you can use both addons at the same time. ## Contributing @@ -61,7 +63,7 @@ See the [Contributing](CONTRIBUTING.md) guide for details. ## Credits -The `webpack` implementation is possible, thanks to ideas from [Ember + Modern CSS](https://github.com/evoactivity/ember-modern-css) by [@evoactivity](https://github.com/evoactivity). Special thanks to the maintainers of [`ember-css-modules`](https://github.com/salsify/ember-css-modules), who paved the Ember way to CSS modules. +The `webpack` implementation is possible, thanks to ideas from [Ember + Modern CSS](https://github.com/evoactivity/ember-modern-css) by [@evoactivity](https://github.com/evoactivity). Special thanks to the maintainers of `ember-css-modules`, who paved the Ember way to CSS modules. ## License diff --git a/docs/written-guides/migrate-from-ember-css-modules.md b/docs/written-guides/migrate-from-ember-css-modules.md index 4c9c8558..86f56b96 100644 --- a/docs/written-guides/migrate-from-ember-css-modules.md +++ b/docs/written-guides/migrate-from-ember-css-modules.md @@ -1,21 +1,25 @@ # Migrate from ember-css-modules -You can reach `embroider-css-modules` in a few steps. (See [`ember-container-query`](https://github.com/ijlee2/ember-container-query/pull/167) for reference.) +Have an Embroider app that runs on `ember-css-modules`? In a few steps, you can replace it with `embroider-css-modules` so that you can enable stricter Embroider settings. -1. [Remove ember-css-modules](#remove-ember-css-modules) -1. [Configure Webpack](#configure-webpack) +1. [Remove ember-css-modules syntax](#remove-ember-css-modules-syntax) +1. [Update project configurations](#update-project-configurations) 1. [Enable stricter Embroider settings](#enable-stricter-embroider-settings) +> [!NOTE] +> If you get lost, you can check [`ember-container-query`](https://github.com/ijlee2/ember-container-query/pull/167) for reference. -## Remove ember-css-modules -Run `ember-codemod-remove-ember-css-modules` to remove `ember-css-modules` syntax. +## Remove ember-css-modules syntax + +Run the provided [codemod](../../packages/ember-codemod-remove-ember-css-modules/README.md) to get started. ```sh -npx ember-codemod-remove-ember-css-modules +# From the project root +npx ember-codemod-remove-ember-css-modules --type app ``` -For more information, please see [the codemod's `README`](../../packages/ember-codemod-remove-ember-css-modules/README.md). +You may also want to [refactor code](./refactor-code.md). ## Update project configurations @@ -25,13 +29,9 @@ Please follow steps 1-3 of [Set up CSS modules (apps)](./set-up-css-modules-apps ## Enable stricter Embroider settings -With `ember-css-modules` gone, you may be able to apply stricter settings for Embroider. - -
- -ember-cli-build.js +In `ember-cli-build.js`, you may now be able to apply stricter settings for Embroider. -For simplicity, only `options` is shown. (The rest of the code remains the same.) +For simplicity, only the [options for `@embroider/compat`](https://github.com/embroider-build/embroider/#options) are shown. (The rest of the file remains the same.) ```js const options = { @@ -41,11 +41,7 @@ const options = { staticAddonTrees: true, // <-- new staticComponents: true, // <-- new staticEmberSource: true, - staticHelpers: true, + staticHelpers: true, // <-- new staticModifiers: true, }; ``` - -
- -Learn more about the [options for Embroider](https://github.com/embroider-build/embroider/#options). diff --git a/docs/written-guides/migrate-from-ember-modern-css.md b/docs/written-guides/migrate-from-ember-modern-css.md index d0eb887f..97ca368b 100644 --- a/docs/written-guides/migrate-from-ember-modern-css.md +++ b/docs/written-guides/migrate-from-ember-modern-css.md @@ -29,12 +29,13 @@ pnpm install --dev \ embroider-css-modules type-css-modules ``` -1. Needed only if you have a TypeScript project +1. Needed only if you have a TypeScript project. ## Configure type-css-modules -⚠️ You may skip this step if your project doesn't support TypeScript. +> [!NOTE] +> You can skip this step if you don't have a TypeScript project. If you have typed `*.css` files, either by installing [`@types/css-modules`](https://www.npmjs.com/package/@types/css-modules) or defining the type to be `Record` in `types/global.d.ts`, please undo the change. @@ -108,7 +109,8 @@ Next, remove all `:local()` pseudo-class selectors. Instead, use the `:global()` ## Use the {{local}} helper -⚠️ You may skip this step if you didn't create the `{{styles}}` helper. +> [!NOTE] +> You can skip this step if you didn't create the `{{styles}}` helper. Remove the `{{styles}}` helper. To apply multiple styles, use the [`{{local}}` helper](../../packages/embroider-css-modules/README.md#helper-local) instead. diff --git a/docs/written-guides/set-up-css-modules-apps.md b/docs/written-guides/set-up-css-modules-apps.md index 31565b3e..4f72ee32 100644 --- a/docs/written-guides/set-up-css-modules-apps.md +++ b/docs/written-guides/set-up-css-modules-apps.md @@ -1,28 +1,30 @@ # Set up CSS modules (apps) -We will use Webpack and PostCSS to implement CSS modules. (If you get lost, you can check [`my-app`](../my-app) for reference.) +We will use Webpack and PostCSS to implement CSS modules. 1. [Install dependencies](#install-dependencies) 1. [Configure Webpack](#configure-webpack) - [Update ember-cli-build.js](#update-ember-cli-buildjs) - [Create postcss.config.js](#create-postcssconfigjs) -1. [Define entry point for CSS](#define-entry-point-for-css) - - [Create app/assets/app.css](#create-appassetsappcss) - - [Import app/assets/app.css](#import-appassetsappcss) +1. [Move app.css code](#move-appcss-code) 1. [Style your first component](#style-your-first-component) - [Glimmer components](#glimmer-components) - - [<template>-tag components](#template-tag-components) + - [<template> tag](#template-tag) - [CSS declaration files](#css-declaration-files) - [Do the file location and name matter?](#do-the-file-location-and-name-matter) - [Can I use the file extension \*.module.css?](#can-i-use-the-file-extension-modulecss) - [Write tests](#write-tests) 1. [Style your first route](#style-your-first-route) + - [<template> tag](#template-tag-1) - [Do the file location and name matter?](#do-the-file-location-and-name-matter-1) +> [!NOTE] +> If you get lost, you can check how [`my-app`](../my-app) is set up. + ## Install dependencies -If you have a new Ember app, you need these dependencies to build the app with Embroider. +If you have a new Ember app, you will need these dependencies to build it with Embroider. - `@embroider/compat` - `@embroider/core` @@ -49,14 +51,14 @@ pnpm install --dev \ embroider-css-modules type-css-modules ``` -1. Needed only if you have a TypeScript project +1. Needed only if you have a TypeScript project. -## Configure Webpack +## Configure Webpack and PostCSS -In this step, you will configure `ember-cli-build.js` and `postcss.config.js`. +In this step, you will update two files: `ember-cli-build.js` and `postcss.config.js`. -If you have a new Ember app, copy-paste the starter code for `ember-cli-build.js`. The code defines a variable called `options`, which you will update later. (Even if your app already runs with Embroider, it's a good idea to compare your `ember-cli-build.js` to the starter code so that we are on the same page.) +If you have a new Ember app, you can copy-paste the starter code for `ember-cli-build.js`. The code defines a variable called `options`, which you will update later.
@@ -96,16 +98,17 @@ module.exports = function (defaults) {
+> [!NOTE] +> Even if you already have an Embroider app, please do compare your `ember-cli-build.js` to the starter code so that we are on the same page. + ### Update ember-cli-build.js -In the variable `options`, define [`cssLoaderOptions`, `publicAssetURL`, and `webpackConfig` ](https://github.com/embroider-build/embroider/blob/main/packages/webpack/src/options.ts) for Embroider. +You'll need to set these [Webpack options](https://github.com/embroider-build/embroider/blob/main/packages/webpack/src/options.ts): `cssLoaderOptions`, `publicAssetURL`, and `webpackConfig`. You can do so by adding a key named `packagerOptions` to `options`.
-ember-cli-build.js - -For simplicity, only `options` is shown. (The rest of the code remains the same.) +options variable ```js const options = { @@ -142,7 +145,7 @@ const options = { ], }, /* - Add the following rule to load asset files, e.g. fonts, icons, etc. + Uncomment this rule to load asset files, e.g. fonts, icons, etc. See https://webpack.js.org/guides/asset-modules/ for more information. */ // { @@ -173,27 +176,18 @@ function mode(resourcePath) { } ``` -⚠️ If your app belongs to a monorepo, you must provide the relative path (from the workspace root to the app) to `hostAppLocation`. This way, Webpack can distinguish the CSS files from your app (local) from those from an addon in the monorepo (global). - -```js -function mode(resourcePath) { - // If your app is located in `apps/your-ember-app` - const hostAppLocation = `apps/your-ember-app/node_modules/.embroider/rewritten-app`; - - return resourcePath.includes(hostAppLocation) ? 'local' : 'global'; -} -``` +> [!IMPORTANT] +> If your app lives in a monorepo, please include the relative path from the workspace root to the app. This way, Webpack can distinguish CSS files from your app (local) from those from an addon in the monorepo (global). +> +> ```js +> // If your app is located at `docs-app` +> const hostAppLocation = 'docs-app/node_modules/.embroider/rewritten-app'; +> ``` ### Create postcss.config.js -List the PostCSS plugins that your app depends on. - -
- -postcss.config.js - -List the `autoprefixer` plugin. +In `postcss.config.js`, list the PostCSS plugins that you need (e.g. `autoprefixer`). ```js const env = process.env.EMBER_ENV ?? 'development'; @@ -208,13 +202,11 @@ module.exports = { }; ``` -
-
-.eslintrc.js +Use eslint-plugin-n? -Find the override for Node files. Add `postcss.config.js` to the list of files. +In `.eslintrc.js`, find the override rule for Node files. Add `postcss.config.js` to the list of files. ```js 'use strict'; @@ -236,43 +228,33 @@ module.exports = {
-## Define entry point for CSS - -For CSS modules to work, we need JS files to be able to import a CSS file. - -Unfortunately, as of Ember v5.6, we can't import CSS files located in `app/styles`. This somewhat limits where we can store files (e.g. stylesheets for routes). We can't delete `app/styles` either, as `ember-cli` expects [`app/styles/app.css`](https://cli.emberjs.com/release/advanced-use/stylesheets/) to exist. +## Move app.css code +To ensure the load order with Webpack, you will need to move the code in `app/styles/app.css` (e.g. global styles, `@import`, `@font-face`) to `app/assets/app.css`. -### Create app/assets/app.css - -Given the constraints above, let's define the entry point for CSS in a new folder, namely `app/assets/app.css`. (The location and name of the file do not matter.) - -
- -app/assets/app.css - -Here is the default file from `ember-cli`. - -```css -/* Ember supports plain CSS out of the box. More info: https://cli.emberjs.com/release/advanced-use/stylesheets/ */ +```sh +mkdir app/assets +cp app/styles/app.css app/assets/app.css ``` -
- -This file serves the same purpose as `app/styles/app.css`. That is, in `app/assets/app.css`, you can import stylesheets and define the global styles for type selectors (e.g. `h1`, `h2`). - +> [!IMPORTANT] +> Ember expects `app/styles/app.css` to exist. Instead of deleting the file, leave it empty. +> +> Here is the default file from `ember-cli`. +> +> ```css +> /* Ember supports plain CSS out of the box. More info: https://cli.emberjs.com/release/advanced-use/stylesheets/ */ +> ``` -### Import app/assets/app.css - -Once the file is created, import it in `app/app.ts`. +Next, import the stylesheet `app/assets/app.css` in `app/app.ts`.
app/app.ts -```ts -import './assets/app.css'; - +```diff ++ import './assets/app.css'; ++ import Application from '@ember/application'; import loadInitializers from 'ember-load-initializers'; import Resolver from 'ember-resolver'; @@ -290,31 +272,29 @@ loadInitializers(App, config.modulePrefix);
-By importing the file in `app/app.ts`, we can ensure the load order in production. Webpack injects `` tags in the order in which they are imported, and we want our entry point to be the first. (paraphrased from [ember-modern-css](https://github.com/evoactivity/ember-modern-css#importing-css)) - ## Style your first component -You can start styling your app! Let's create a Glimmer component to test CSS modules. +You can style your app now. Let's create a Glimmer component to test CSS modules. ```sh -ember g component hello-world -gc +ember g component hello -gc ``` -While `ember-cli` can take care of the template and the backing class, you will need to manually create the stylesheet (for now). +While `ember-cli` can create the template and the backing class, you will need to manually create the stylesheet. ```sh -touch app/components/hello-world.css +touch app/components/hello.css ``` ### Glimmer components -The goal is to render the text `Hello world!` in a `
`-container. In the stylesheet, define a class selector named `.container`. +The goal is to display `Hello world!` in a `
`-container. In the stylesheet, define a class selector named `.container`.
-app/components/hello-world.css +app/components/hello.css ```css .container { @@ -332,27 +312,27 @@ Next, in the backing class, import the stylesheet and name it `styles`. Store `s
-app/components/hello-world.ts +app/components/hello.ts Note, we write the file extension `.css` explicitly. ```ts import Component from '@glimmer/component'; -import styles from './hello-world.css'; +import styles from './hello.css'; -export default class HelloWorldComponent extends Component { +export default class HelloComponent extends Component { styles = styles; } ```
-Display the message and style the `
`-container. +Display the message and style the container.
-app/components/hello-world.hbs +app/components/hello.hbs ```hbs
@@ -362,33 +342,34 @@ Display the message and style the `
`-container.
-Finally, render the component somewhere. Et voilà! ✨ +Finally, render the component. Et voilà! ✨
app/templates/index.hbs ```hbs - + ```
-You can also [apply multiple styles with the `{{local}}` helper](../../packages/embroider-css-modules/README.md#helper-local). +> [!NOTE] +> Use the [`{{local}}` helper](../../packages/embroider-css-modules/README.md#helper-local) to apply multiple styles. -### <template>-tag components +### <template> tag -You may have noticed a downside of `embroider-css-modules`. Since we pass `styles` to the template as a class property, it's not possible to style template-only components. +Since we pass `styles` to the template as a class property, it's not possible to style template-only components. -We can address this issue by writing [`