diff --git a/docs/shared/recipes/storybook/angular-storybook-compodoc.md b/docs/shared/recipes/storybook/angular-storybook-compodoc.md index eceb3cec7b..ad6dd184d2 100644 --- a/docs/shared/recipes/storybook/angular-storybook-compodoc.md +++ b/docs/shared/recipes/storybook/angular-storybook-compodoc.md @@ -33,7 +33,7 @@ This comment would result in the following documentation in Compodoc: ![Button size `@Input` generated documentation](/shared/recipes/storybook/button-size-input.png) -If we add a description and a default value to each of our component `@Input`s, we will end up with a full documentation page. See a full example of the button component [here](https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular/apps/web/src/app/butn/butn.component.ts). The generated documentation of this example will look like this: +If we add a description and a default value to each of our component `@Input`s, we will end up with a full documentation page. See a full example of the button component [here](https://github.com/nrwl/nx-recipes/tree/main/storybook-compodoc-angular/apps/my-app/src/app/butn/butn.component.ts). The generated documentation of this example will look like this: ![Generated Docs page for the Button](/shared/recipes/storybook/button-docs.png) @@ -59,29 +59,44 @@ This guide assumes that you have an Angular project with Storybook configured in First we need to install the necessary packages: +{% tabs %} +{% tab label="yarn" %} + ```shell yarn add -D @compodoc/compodoc ``` -or +{% /tab %} +{% tab label="npm" %} ```shell npm install --save-dev @compodoc/compodoc ``` +{% /tab %} +{% tab label="pnpm" %} + +```shell +pnpm install --save-dev @compodoc/compodoc +``` + +{% /tab %} +{% /tabs %} + ### 2. Include the component files in the TypeScript compilation for Compodoc When you are using Compodoc, you need to create a `tsconfig` file, and in the `include` array you need to place all the files that you want Compodoc to include in its compilation. Compodoc [suggests](https://compodoc.app/guides/installation.html) to add a `tsconfig.doc.json` to do that. Then, when running `compodoc` you can use the `-p` (or `--tsconfig`) flag to specify the path to that file. See all the options that Compodoc supports [here](https://compodoc.app/guides/options.html). In the Storybook case, Storybook has the `--tsconfig` option [prefilled](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L23) to point to the `.storybook/tsconfig.json` file. As is noted in the [Storybook schema for the Angular builders](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/start-storybook/schema.json#L76), "_Options `-p` with tsconfig path and `-d` with workspace root is always given._". What this means is that you can add the paths to the component files (where Compodoc will look for JSDoc comment blocks) in the `include` array of the `.storybook/tsconfig.json` file. This is the file that Storybook will use to compile the TypeScript files, and it will also be the file that Compodoc will use to compile the TypeScript files. -In your project's `.storybook/tsconfig.json` file, in the `include` array, add the path to the component files (eg. `"../src/**/*.component.ts"`). For example, if you have an application called `web`, the file `apps/web/.storybook/tsconfig.json` will look like this: +In your project's `.storybook/tsconfig.json` file, in the `include` array, add the path to the component files (eg. `"../src/**/*.component.ts"`). For example, if you have an application called `my-app`, the file `apps/my-app/.storybook/tsconfig.json` will look like this: -```json {% fileName="apps/web/.storybook/tsconfig.json" %} +```json {% fileName="apps/my-app/.storybook/tsconfig.json" %} { "extends": "../tsconfig.json", "compilerOptions": { - "emitDecoratorMetadata": true + "emitDecoratorMetadata": true, + "resolveJsonModule": true }, "files": ["../src/polyfills.ts"], "exclude": ["../**/*.spec.ts"], @@ -113,7 +128,7 @@ This applies in cases where, for example, you have [one single Storybook for you #### a. Set `compodoc: true` -In your project's `project.json` file (e.g. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets. +In your project's `project.json` file (e.g. `apps/my-app/project.json`), find the `storybook` and the `build-storybook` targets. In the `options` you will see `"compodoc": false`. Change that to `true`. @@ -121,38 +136,53 @@ In the `options` you will see `"compodoc": false`. Change that to `true`. Storybook has [preconfigured `compodoc`](https://github.com/storybookjs/storybook/blob/next/code/frameworks/angular/src/builders/utils/run-compodoc.ts#L25) to generate a `documentation.json` file at the root of your workspace by default. We want to change that, and keep the documentation file project-specific. Of course, you can change that later, or as you see fit for your use case. But let's keep it project-specific for now. -In your project's `project.json` file (eg. `apps/web/project.json`), find the `storybook` and the `build-storybook` targets. Below the `"compodoc"` option, create a new option called `"compodocArgs` which contains the following: `["-e", "json", "-d", "apps/web"]`. This means that the `exportFormat` (`-e`) will be `json` and the `output` directory (`-d`) will be `apps/web` (change that, of course, to the directory of your project). +In your project's `project.json` file (eg. `apps/my-app/project.json`), find the `storybook` and the `build-storybook` targets. Below the `"compodoc"` option, create a new option called `"compodocArgs` which contains the following: `["-e", "json", "-d", "apps/my-app"]`. This means that the `exportFormat` (`-e`) will be `json` and the `output` directory (`-d`) will be `apps/my-app` (change that, of course, to the directory of your project). -Let's see the result for our `web` app `storybook` target, for example (in `apps/web/project.json`): +Let's see the result for our `my-app` app `storybook` target, for example (in `apps/my-app/project.json`): -```jsonc {% fileName="project.json" %} +```jsonc {% fileName="apps/my-app/project.json" %} "storybook": { "executor": "@storybook/angular:start-storybook", "options": { "port": 4400, - "configDir": "apps/web/.storybook", - "browserTarget": "web:build", + "configDir": "apps/my-app/.storybook", + "browserTarget": "my-app:build", "compodoc": true, - "compodocArgs": ["-e", "json", "-d", "apps/web"] + "compodocArgs": ["-e", "json", "-d", "apps/my-app"] }, }, ``` ### 4. Let Storybook know of the `documentation.json` file -In your project's `.storybook/preview.js` file (for example for your `web` app the path would be `apps/web/.storybook/preview.js`), add the following: +In your project's `.storybook/preview.ts` file (for example for your `my-app` app the path would be `apps/my-app/.storybook/preview.ts`), add the following: -```js {% fileName="apps/web/.storybook/preview.js" %} +```js {% fileName="apps/my-app/.storybook/preview.ts" %} import { setCompodocJson } from '@storybook/addon-docs/angular'; import docJson from '../documentation.json'; setCompodocJson(docJson); ``` +Notice how we are adding `"resolveJsonModule": true` in our app's `.storybook/tsconfig.json` in order to be able to import the `documentation.json` file: + +```json {% fileName="apps/my-app/.storybook/tsconfig.json" %} +{ + "extends": "../tsconfig.json", + "compilerOptions": { + "emitDecoratorMetadata": true, + "resolveJsonModule": true + }, + "files": ["../src/polyfills.ts"], + "exclude": ["../**/*.spec.ts"], + "include": ["../src/**/*.stories.ts", "../src/**/*.component.ts", "*.js"] +} +``` + ### 5. Set up Autodocs -In your project's `.storybook/main.js` file you have to enable autodocs: +In your project's `.storybook/main.ts` file you have to enable autodocs: -```js {% fileName="apps/web/.storybook/main.js" %} +```js {% fileName="apps/my-app/.storybook/main.ts" %} const config = { stories: ['../src/app/**/*.stories.@(js|jsx|ts|tsx|mdx)'], addons: ['@storybook/addon-essentials'], @@ -169,16 +199,16 @@ const config = { export default config; ``` -### Now run Storybook and see the results! +### Now run Storybook and see the results Now you can run Storybook or build Storybook, and documentation will be included. Just check the Docs tab! ```shell -nx storybook web +nx storybook my-app ``` and ```shell -nx build-storybook web +nx build-storybook my-app ``` diff --git a/docs/shared/recipes/storybook/one-storybook-for-all.md b/docs/shared/recipes/storybook/one-storybook-for-all.md index 0aaddf3bc9..60dcbd26d3 100644 --- a/docs/shared/recipes/storybook/one-storybook-for-all.md +++ b/docs/shared/recipes/storybook/one-storybook-for-all.md @@ -80,35 +80,23 @@ stories: [ ]; ``` -### Import the stories in tsconfig.storybook.json +### If you're using Angular add the stories in your tsconfig.json -Here is a sample `libs/storybook-host/tsconfig.storybook.json` file: +Here is a sample `libs/storybook-host/.storybook/tsconfig.json` file: -```json {% fileName="libs/storybook-host/tsconfig.storybook.json" %} +```json {% fileName="libs/storybook-host/.storybook/tsconfig.json" %} { "extends": "../tsconfig.json", "compilerOptions": { "emitDecoratorMetadata": true }, - ... - "include": [ - "../../**/ui/**/src/**/*.stories.ts", - "../../**/ui/**/src/**/*.stories.js", - "../../**/ui/**/src/**/*.stories.jsx", - "../../**/ui/**/src/**/*.stories.tsx", - "../../**/ui/**/src/**/*.stories.mdx", - ".storybook/*.js", - ".storybook/*.ts" - ] + "exclude": ["../**/*.spec.ts"], + "include": ["../../**/ui/**/src/lib/**/*.stories.ts", "*.ts"] } ``` Notice how in the `include` array we are specifying the paths to our stories, using the same pattern we used in our `.storybook/main.ts`. -{% callout type="note" title="Angular Storybook tsconfig.json" %} -For Angular, that file is in your project's `.storybook` directory, so in this case it would be under `libs/storybook-host/.storybook/tsconfig.json`. -{% /callout %} - ### Serve or build your Storybook Now you can serve, test or build your Storybook as you would, normally. And then you can publish the bundled app!