From d868494ce69006ad28fb43d3290fcda3fa3a1089 Mon Sep 17 00:00:00 2001 From: Shaun Lloyd Date: Tue, 28 Mar 2023 09:42:31 -0400 Subject: [PATCH 1/3] Update styling & CSS doc to mention styling addon --- docs/configure/styling-and-css.md | 20 +++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/docs/configure/styling-and-css.md b/docs/configure/styling-and-css.md index 9d0607c7eaaa..725b6464648e 100644 --- a/docs/configure/styling-and-css.md +++ b/docs/configure/styling-and-css.md @@ -2,19 +2,29 @@ title: 'Styling and CSS' --- -There are many ways to include CSS in a web application, and correspondingly there are many ways to include CSS in Storybook. Usually, it is best to try and replicate what your application does with styling in Storybook’s configuration. +There are many ways to include CSS in a web application, and correspondingly there are many ways to include CSS in Storybook. Usually, it is best to try and replicate what your application does with styling in Storybook’s configuration. To make this easier, we recommend using [`@storybook/addon-styling`](https://github.com/storybookjs/addon-styling). ### CSS-in-JS -CSS-in-JS libraries are designed to use basic JavaScript, and they often work in Storybook without any extra configuration. Some libraries expect components to render in a specific rendering “context” (for example, to provide themes), and you may need to add a [global decorator](../writing-stories/decorators.md#global-decorators) to supply it. +CSS-in-JS libraries are designed to use basic JavaScript, and they often work in Storybook without any extra configuration. Some libraries expect components to render in a specific rendering “context” (for example, to provide themes), which can be accomplished with `@storybook/addon-styling`'s [`withThemeFromJSXProvider` decorator](https://github.com/storybookjs/addon-styling/blob/next/docs/api.md#withthemefromjsxprovider). ### Importing CSS files -If your component files import their CSS, Storybook's webpack configuration will work out of the box. The noticeable exception to this is if you're using a CSS precompiler. In this case, you can either install and configure a Storybook addon (e.g., [`@storybook/addon-styling`](https://github.com/storybookjs/addon-styling#storybookaddon-styling)), or customize [Storybook's webpack configuration](../builders/webpack.md#extending-storybooks-webpack-config) and include the appropriate loader. +To add global CSS for all of your stories, import it in [`.storybook/preview.js`](./overview.md#configure-story-rendering). - +```js +// .storybook/preview.js + +import '../src/styles/global.css'; +``` + +If your component files import their CSS, Storybook's webpack configuration will work out of the box. The noticeable exception to this is if you're using a CSS compiler tools like Sass or Postcss. -To use your CSS in all stories, you import it in [`.storybook/preview.js`](./overview.md#configure-story-rendering) +### CSS compilers + +If you're using tools like Sass or Postcss, you can either install and configure [`@storybook/addon-styling`](https://github.com/storybookjs/addon-styling#storybookaddon-styling), or customize [Storybook's webpack configuration](../builders/webpack.md#extending-storybooks-webpack-config) and include the appropriate loader. If you're using Vite, this all comes pre-configured for you. + + ### Adding webfonts From 50f7a371b62ab89e7965686dfc98af114bcbc731 Mon Sep 17 00:00:00 2001 From: Shaun Lloyd Date: Wed, 19 Apr 2023 15:42:32 -0400 Subject: [PATCH 2/3] Raise styling-and-css into configure --- docs/configure/styling-and-css.md | 24 +++++++------ docs/get-started/setup.md | 57 +++++++++---------------------- docs/toc.js | 10 +++--- 3 files changed, 34 insertions(+), 57 deletions(-) diff --git a/docs/configure/styling-and-css.md b/docs/configure/styling-and-css.md index 725b6464648e..e0f1c3ce94ec 100644 --- a/docs/configure/styling-and-css.md +++ b/docs/configure/styling-and-css.md @@ -4,13 +4,9 @@ title: 'Styling and CSS' There are many ways to include CSS in a web application, and correspondingly there are many ways to include CSS in Storybook. Usually, it is best to try and replicate what your application does with styling in Storybook’s configuration. To make this easier, we recommend using [`@storybook/addon-styling`](https://github.com/storybookjs/addon-styling). -### CSS-in-JS +## Importing CSS files -CSS-in-JS libraries are designed to use basic JavaScript, and they often work in Storybook without any extra configuration. Some libraries expect components to render in a specific rendering “context” (for example, to provide themes), which can be accomplished with `@storybook/addon-styling`'s [`withThemeFromJSXProvider` decorator](https://github.com/storybookjs/addon-styling/blob/next/docs/api.md#withthemefromjsxprovider). - -### Importing CSS files - -To add global CSS for all of your stories, import it in [`.storybook/preview.js`](./overview.md#configure-story-rendering). +Storybook is pre-configured to recognize imports for css files. To add global CSS for all of your stories, import it in [`.storybook/preview.js`](./overview.md#configure-story-rendering). ```js // .storybook/preview.js @@ -18,14 +14,20 @@ To add global CSS for all of your stories, import it in [`.storybook/preview.js` import '../src/styles/global.css'; ``` -If your component files import their CSS, Storybook's webpack configuration will work out of the box. The noticeable exception to this is if you're using a CSS compiler tools like Sass or Postcss. +If your component files import their CSS files, this will work too. The noticeable exception to this is if you're using CSS processor tools like Sass or Postcss. -### CSS compilers + -If you're using tools like Sass or Postcss, you can either install and configure [`@storybook/addon-styling`](https://github.com/storybookjs/addon-styling#storybookaddon-styling), or customize [Storybook's webpack configuration](../builders/webpack.md#extending-storybooks-webpack-config) and include the appropriate loader. If you're using Vite, this all comes pre-configured for you. +## CSS processors - +If you're using Vite as your builder, you're covered! Vite supports Sass and PostCSS out-of-the-box 🎉 + +However, if you're using Webpack and want to use Sass and PostCss, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling`](https://github.com/storybookjs/addon-styling#storybookaddon-styling) to help you configure these tools. Or if you'd prefer, you can customize [Storybook's webpack configuration yourself](../builders/webpack.md#extending-storybooks-webpack-config) to include the appropriate loader(s). + +## CSS-in-JS + +CSS-in-JS libraries are designed to use basic JavaScript, and they often work in Storybook without any extra configuration. Some libraries expect components to render in a specific rendering “context” (for example, to provide themes), which can be accomplished with `@storybook/addon-styling`'s [`withThemeFromJSXProvider` decorator](https://github.com/storybookjs/addon-styling/blob/next/docs/api.md#withthemefromjsxprovider). -### Adding webfonts +## Adding webfonts If you need webfonts to be available, you may need to add some code to the [`.storybook/preview-head.html`](./story-rendering.md#adding-to-head) file. We recommend including any assets with your Storybook if possible, in which case you likely want to configure the [static file location](./images-and-assets.md#serving-static-files-via-storybook-configuration). diff --git a/docs/get-started/setup.md b/docs/get-started/setup.md index 550b1f6e59df..5497b0597bd8 100644 --- a/docs/get-started/setup.md +++ b/docs/get-started/setup.md @@ -34,6 +34,22 @@ Go to your Storybook to view the rendered component. It’s OK if it looks a bit Depending on your technology stack, you also might need to configure the Storybook environment further. +## Render component styles + +Storybook isn’t opinionated about how you generate or load CSS. It renders whatever DOM elements you provide. But sometimes, things won’t “look right” out of the box. + +You may have to configure your CSS tooling for Storybook’s rendering environment. Here are some setup guides for popular tools in the community. + +- [Tailwind](https://storybook.js.org/recipes/tailwindcss/) +- [Material UI](https://storybook.js.org/recipes/@mui/material/) +- [Vuetify](https://storybook.js.org/recipes/vuetify/) +- [Styled Components](https://storybook.js.org/recipes/styled-components/) +- [Emotion](https://storybook.js.org/recipes/@emotion/styled/) +- [Sass](https://storybook.js.org/recipes/sass/) +- [Bootstrap](https://storybook.js.org/recipes/bootstrap/) + +Don't see the tool that you're looking for? Check out the [styling and css](../configure/styling-and-css.md) page for more details. + ## Configure Storybook for your stack Storybook comes with a permissive [default configuration](../configure/overview.md). It attempts to customize itself to fit your setup. But it’s not foolproof. @@ -91,47 +107,6 @@ Use [decorators](../writing-stories/decorators.md) to “wrap” every story in -## Render component styles - -Storybook isn’t opinionated about how you generate or load CSS. It renders whatever DOM elements you provide. But sometimes, things won’t “look right” out of the box. - -You may have to configure your CSS tooling for Storybook’s rendering environment. Here are some tips on what could help: - -
- CSS-in-JS like styled-components and Emotion - -If you are using CSS-in-JS, chances are your styles are working because they’re generated in JavaScript and served alongside each component. Theme users may need to add a decorator to `.storybook/preview.js`, [see above](#component-context). - -
- -
- @import CSS into components - -Storybook allows you to import CSS files in your components directly. But in some cases you may need to [tweak its Webpack configuration](../builders/webpack.md#override-the-default-configuration). Angular components require [a special import](../configure/styling-and-css.md#importing-css-files). - -
- -
- Global imported styles - -If you have global imported styles, create a file called [`.storybook/preview.js`](../configure/overview.md#configure-story-rendering) and import the styles there. They will be added by Storybook automatically for all stories. - -
- -
- Add external CSS or webfonts in the <head> - -Alternatively, if you want to inject a CSS link tag to the `` directly (or some other resource like a webfont link), you can use [`.storybook/preview-head.html`](../configure/story-rendering.md#adding-to-<head>) to add arbitrary HTML. - -
- -
- Load fonts or images from a local directory - -If you're referencing fonts or images from a local directory, you'll need to configure the Storybook script to [serve the static files](../configure/images-and-assets.md). - -
- ## Load assets and resources If you want to [link to static files](../configure/images-and-assets.md) in your project or stories (e.g., `/fonts/XYZ.woff`), use the `-s path/to/folder` flag to specify a static folder to serve from when you start up Storybook. To do so, edit the `storybook` and `build-storybook` scripts in `package.json`. diff --git a/docs/toc.js b/docs/toc.js index 9ec7e473709d..83053f067399 100644 --- a/docs/toc.js +++ b/docs/toc.js @@ -321,6 +321,11 @@ module.exports = { title: 'Overview', type: 'link', }, + { + pathSegment: 'styling-and-css', + title: 'Styling and CSS', + type: 'link', + }, { pathSegment: 'upgrading', title: 'Upgrading', @@ -356,11 +361,6 @@ module.exports = { title: 'TypeScript', type: 'link', }, - { - pathSegment: 'styling-and-css', - title: 'Styling and CSS', - type: 'link', - }, { pathSegment: 'images-and-assets', title: 'Images and assets', From 7316204497a2179a8415fb9d93b9529e112b29ff Mon Sep 17 00:00:00 2001 From: Shaun Lloyd Date: Wed, 19 Apr 2023 16:33:59 -0400 Subject: [PATCH 3/3] Implement feedback --- docs/configure/import-css/import-css.js.mdx | 8 ++++++++ docs/configure/import-css/import-css.ts.mdx | 14 ++++++++++++++ docs/configure/styling-and-css.md | 10 +++------- 3 files changed, 25 insertions(+), 7 deletions(-) create mode 100644 docs/configure/import-css/import-css.js.mdx create mode 100644 docs/configure/import-css/import-css.ts.mdx diff --git a/docs/configure/import-css/import-css.js.mdx b/docs/configure/import-css/import-css.js.mdx new file mode 100644 index 000000000000..6937b9f15b25 --- /dev/null +++ b/docs/configure/import-css/import-css.js.mdx @@ -0,0 +1,8 @@ +```js +// .storybook/preview.js +import '../src/styles/global.css'; + +export default { + parameters: {}, +}; +``` \ No newline at end of file diff --git a/docs/configure/import-css/import-css.ts.mdx b/docs/configure/import-css/import-css.ts.mdx new file mode 100644 index 000000000000..2d7d4f642bf9 --- /dev/null +++ b/docs/configure/import-css/import-css.ts.mdx @@ -0,0 +1,14 @@ +```ts +// .storybook/preview.ts + +// Replace your-framework with the framework you are using (e.g., react, vue3) +import { Preview } from '@storybook/your-framework'; + +import '../src/styles/global.css'; + +const preview: Preview = { + parameters: {}, +}; + +export default preview; +``` diff --git a/docs/configure/styling-and-css.md b/docs/configure/styling-and-css.md index e0f1c3ce94ec..c0a8aa0b6dbc 100644 --- a/docs/configure/styling-and-css.md +++ b/docs/configure/styling-and-css.md @@ -6,13 +6,9 @@ There are many ways to include CSS in a web application, and correspondingly the ## Importing CSS files -Storybook is pre-configured to recognize imports for css files. To add global CSS for all of your stories, import it in [`.storybook/preview.js`](./overview.md#configure-story-rendering). +Storybook is pre-configured to recognize imports for CSS files. To add global CSS for all your stories, import it in [`.storybook/preview.js`](./overview.md#configure-story-rendering). -```js -// .storybook/preview.js - -import '../src/styles/global.css'; -``` + If your component files import their CSS files, this will work too. The noticeable exception to this is if you're using CSS processor tools like Sass or Postcss. @@ -22,7 +18,7 @@ If your component files import their CSS files, this will work too. The noticeab If you're using Vite as your builder, you're covered! Vite supports Sass and PostCSS out-of-the-box 🎉 -However, if you're using Webpack and want to use Sass and PostCss, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling`](https://github.com/storybookjs/addon-styling#storybookaddon-styling) to help you configure these tools. Or if you'd prefer, you can customize [Storybook's webpack configuration yourself](../builders/webpack.md#extending-storybooks-webpack-config) to include the appropriate loader(s). +However, if you're using Webpack and want to use Sass and PostCss, you'll need some extra configuration. We recommend installing [`@storybook/addon-styling`](https://github.com/storybookjs/addon-styling#storybookaddon-styling) to help you configure these tools. Or if you'd prefer, you can customize [Storybook's webpack configuration yourself](../builders/webpack.md#override-the-default-configuration) to include the appropriate loader(s). ## CSS-in-JS