mirror of
https://github.com/storybookjs/storybook.git
synced 2025-04-04 13:31:19 +08:00
Merge pull request #17387 from storybookjs/chore_docs_updates_for_angular
Chore: (Docs) Updates to the Angular documentation
This commit is contained in:
Michael Shilman
GitHub
commit
312e79d081
42
docs/configure/css-troubleshooting/angular.mdx
Normal file
42
docs/configure/css-troubleshooting/angular.mdx
Normal file
@ -0,0 +1,42 @@
|
||||
With Angular, you'll need to take special care of handling CSS.
|
||||
|
||||
### Working with previous versions
|
||||
|
||||
If you're working with an older version of Angular, in addition to providing a custom Webpack configuration, you can also use an inline loader to load your CSS safely. For example:
|
||||
|
||||
```js
|
||||
import '!style-loader!css-loader!./styles.css';
|
||||
```
|
||||
|
||||
### With Angular 13
|
||||
|
||||
With Angular version 13 and above, you should use a builder configuration to import your CSS, for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"my-project": {
|
||||
"architect": {
|
||||
"build": {
|
||||
"builder": "@angular-devkit/build-angular:browser",
|
||||
"options": {
|
||||
"styles": ["src/styles.css", "src/styles.scss"]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Additionally, if you need Storybook specific styles that are separate from your application, you can configure the styles with [Storybook's custom builder](../get-started/install.md), which will override the application's styles:
|
||||
|
||||
```json
|
||||
{
|
||||
"storybook": {
|
||||
"builder": "@storybook/angular:start-storybook",
|
||||
"options": {
|
||||
"browserTarget": "my-default-project:build",
|
||||
"styles": [".storybook/custom-styles.scss"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -10,23 +10,9 @@ CSS-in-JS libraries are designed to use basic JavaScript, and they often work in
|
||||
|
||||
### Importing CSS files
|
||||
|
||||
If your component files import their CSS, Storybook’s webpack config will work unmodified with some exceptions:
|
||||
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 preset (e.g., [SCSS preset](https://github.com/storybookjs/presets/tree/master/packages/preset-scss)), or customize [Storybook's webpack configuration](./webpack#extending-storybooks-webpack-config) and include the appropriate loader.
|
||||
|
||||
- If you are using a CSS precompiler, you may need to add a preset (such as the [SCSS preset](https://github.com/storybookjs/presets/tree/master/packages/preset-scss), or add a loader to Storybook’s webpack config).
|
||||
- In Angular, you'll need to take special care of how you handle CSS:
|
||||
|
||||
- Either [customize your webpack config](./webpack#extending-storybooks-webpack-config)
|
||||
- Or use syntax to use a inline loader:
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'angular/storybook-angular-inline-css-loader.js.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
<FeatureSnippets paths={['configure/css-troubleshooting/angular.mdx']} />
|
||||
|
||||
To use your CSS in all stories, you import it in [`.storybook/preview.js`](./overview.md#configure-story-rendering)
|
||||
|
||||
|
||||
@ -52,6 +52,7 @@ Depending on your framework, first, build your app and then check that everythin
|
||||
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'angular/storybook-run-dev.with-builder.js.mdx',
|
||||
'common/storybook-run-dev.npm.js.mdx',
|
||||
'common/storybook-run-dev.yarn.js.mdx',
|
||||
]}
|
||||
|
||||
@ -1,8 +1,28 @@
|
||||
Use the Storybook CLI to install it in a single command. Run this inside your _existing project’s_ root directory:
|
||||
- Use the Storybook CLI to install it in a single command. Run this inside your _existing project’s_ root directory:
|
||||
|
||||
```shell
|
||||
# Add Storybook:
|
||||
npx sb init
|
||||
```
|
||||
|
||||
If you run into issues with the installation, check the [Troubleshooting section](#troubleshooting) below for guidance on how to solve it.
|
||||
- Update your `angular.json` file to include Storybook's custom builder:
|
||||
|
||||
```json
|
||||
{
|
||||
"storybook": {
|
||||
"builder": "@storybook/angular:start-storybook",
|
||||
"options": {
|
||||
"browserTarget": "angular-cli:build",
|
||||
"port": 6006
|
||||
}
|
||||
},
|
||||
"build-storybook": {
|
||||
"builder": "@storybook/angular:build-storybook",
|
||||
"options": {
|
||||
"browserTarget": "angular-cli:build"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you run into issues with the installation, check the [Troubleshooting section](#troubleshooting) below for guidance on how to solve it.
|
||||
@ -12,6 +12,28 @@
|
||||
|
||||
Check the [Migration Guide](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#automigrate) for more information on how to set up Webpack 5.
|
||||
|
||||
- If you're using the custom Storybook builder, Storybook will not automatically open a browser window or tab. It's is a known issue that we plan to fix in future releases.
|
||||
|
||||
- When adding Storybook to your Angular project, check if you're running the install command from the root directory. Or in a monorepo environment inside the directory where the `angular.json` file is located.
|
||||
|
||||
- If you need further customization to the Storybook builder configuration, you can use the following table as a reference:
|
||||
|
||||
| Configuration element | Description |
|
||||
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `"browserTarget"` | Build target to be served using the following format. <br/> `"example-project:builder:config"` |
|
||||
| `"tsConfig"` | Location of the TypeScript configuration file, relative to the current workspace. <br/> `"tsConfig": "./tsconfig.json"`. |
|
||||
| `"port"` | Port used by Storybook. <br/> `"port": 6006` |
|
||||
| `"host"` | Set up a custom host for Storybook. <br/> `"host": "http://my-custom-host"` |
|
||||
| `"configDir"` | Storybook configuration directory location. <br/> `"configDir": ".storybook"` |
|
||||
| `"https"` | Starts Storybook with HTTPS enabled. <br/> `"https": true` <br/> Requires custom certificate information. |
|
||||
| `"sslCa"` | Provides an SSL certificate authority. <br/> `"sslCa": "your-custom-certificate-authority"` <br/> Optional usage with `"https"` |
|
||||
| `"sslCert"` | Provides an SSL certificate. <br/> `"sslCert": "your-custom-certificate"` <br/> Required for `https` |
|
||||
| `"sslKey"` | Provides an SSL key to serve Storybook. <br/> `"sslKey": "your-ssl-key"` |
|
||||
| `"smokeTest"` | Exit Storybook after successful start. <br/> `"smokeTest": true` |
|
||||
| `"ci"` | Starts Storybook in CI mode (skips interactive prompts and will not open browser window). <br/> `"ci": true` |
|
||||
| `"quiet"` | Filters Storybook verbose build output. <br/> `"quiet": true` |
|
||||
| `"docsMode"` | Starts Storybook in [documentation mode](../writing-docs/build-documentation.md#preview-storybooks-documentation). <br/> `"docsMode": true` |
|
||||
| `"styles"` | Provide the location of the [application's styles](../configure/styling-and-css.md#importing-css-files) to be used with Storybook. <br/> `"styles": ["src/styles.css", "src/styles.scss"]` <br/> |
|
||||
| `"stylePreprocessorOptions"` | Provides further customization for style preprocessors resolved to the workspace root. <br/> `"stylePreprocessorOptions": { "includePaths": ["src/styles"] }` |
|
||||
|
||||
- For other installation issues, check the [Angular README](../../app/angular/README.md) for additional instructions.
|
||||
@ -13,15 +13,19 @@ Teams publish Storybook online to review and collaborate on works in progress. T
|
||||
|
||||
## Build Storybook as a static web application
|
||||
|
||||
First, we'll need to build Storybook as a static web application. The functionality is already built-in and pre-configured. Run the following command inside your project's root directory:
|
||||
First, we'll need to build Storybook as a static web application. The functionality is already built-in and pre-configured for most supported frameworks. Others require a bit of customization (e.g., Angular). Run the following command inside your project's root directory:
|
||||
|
||||
```shell
|
||||
# With yarn
|
||||
yarn build-storybook
|
||||
<!-- prettier-ignore-start -->
|
||||
|
||||
# With npm
|
||||
npm run build-storybook
|
||||
```
|
||||
<CodeSnippets
|
||||
paths={[
|
||||
'angular/custom-build-script-production.script-for-builder.js.mdx',
|
||||
'angular/build-storybook-production-mode.with-builder.js.mdx',
|
||||
'common/build-storybook-production-mode.js.mdx',
|
||||
]}
|
||||
/>
|
||||
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
<div class="aside">
|
||||
|
||||
@ -133,4 +137,4 @@ This level of service can serve published Storybooks but has no further integrat
|
||||
|
||||
Examples: [Netlify](https://www.netlify.com/), [S3](https://aws.amazon.com/en/s3/)
|
||||
|
||||
</details>
|
||||
</details>
|
||||
@ -0,0 +1,6 @@
|
||||
```shell
|
||||
# Builds Storybook with Angular's custom builder
|
||||
# See https://storybook.js.org/docs/angular/get-started/install
|
||||
# to learn how to create the custom builder
|
||||
ng run my-project:build-storybook
|
||||
```
|
||||
@ -0,0 +1,7 @@
|
||||
```json
|
||||
{
|
||||
"scripts": {
|
||||
"build-storybook": "ng run my-project:build-storybook"
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,3 +0,0 @@
|
||||
```js
|
||||
import '!style-loader!css-loader!./styles.css';
|
||||
```
|
||||
@ -0,0 +1,3 @@
|
||||
```shell
|
||||
ng run my-project:storybook
|
||||
```
|
||||
@ -0,0 +1,7 @@
|
||||
```shell
|
||||
# With yarn
|
||||
yarn build-storybook
|
||||
|
||||
# With npm
|
||||
npm run build-storybook
|
||||
```
|
||||
Loading…
x
Reference in New Issue
Block a user