Ana içeriğe atla

Using Storybook with Angular and Vite

Storybook is a frontend workshop for building UI components and pages in isolation.

By default, Angular and Storybook uses Webpack to build and serve the Storybook application.

This guides you through the process of switching to building and serving your Storybook with Angular using Vite. This process can be applied to any Angular project using Storybook.

Setting up Storybook​

If you don't have Storybook setup already, run the following command to initialize Storybook for your project:

npx storybook@latest init

Follow the provided prompts, and commit your changes.

Installing the Storybook package​

Install the Storybook Plugin for Angular and Vite. Depending on your preferred package manager, run one of the following commands:

npm install @analogjs/storybook-angular --save-dev

Configuring Storybook​

Add the zone.js import to the top of your .storybook/preview.ts file.

import 'zone.js';

import { applicationConfig, type Preview } from '@analogjs/storybook-angular';
import { provideNoopAnimations } from '@angular/platform-browser/animations';

// compodoc configuration
import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';

setCompodocJson(docJson);

const preview: Preview = {
  decorators: [
    applicationConfig({
      providers: [provideNoopAnimations()],
    }),
  ],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

export default preview;

Next, update the .storybook/main.ts file to use the StorybookConfig. Also update the framework to use the @analogjs/storybook-angular package.

import { StorybookConfig } from '@analogjs/storybook-angular';

const config: StorybookConfig = {
  // other config, addons, etc.
  framework: {
    name: '@analogjs/storybook-angular',
    options: {},
  },
};

Remove the existing webpackFinal config function if present.

Next, update the Storybook targets in the angular.json or project.json

    "storybook": {
      "builder": "@analogjs/storybook-angular:start-storybook",
    },
    "build-storybook": {
      "builder": "@analogjs/storybook-angular:build-storybook"
    }

Remove any webpack specific options and remove the browserTarget option.

Add the /storybook-static folder to the .gitignore file.

Setting up CSS​

To register global styles, import them directly in the .storybook/preview.ts file.

import 'zone.js';

import { applicationConfig, type Preview } from '@analogjs/storybook-angular';
import { provideNoopAnimations } from '@angular/platform-browser/animations';

// compodoc configuration
import { setCompodocJson } from '@storybook/addon-docs/angular';
import docJson from '../documentation.json';

// global styles
import '../src/styles.css';

setCompodocJson(docJson);

const preview: Preview = {
  decorators: [
    applicationConfig({
      providers: [provideNoopAnimations()],
    }),
  ],
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
};

export default preview;

Running Storybook​

Run the command for starting the development server.

npm run storybook

Building Storybook​

Run the command for building the storybook.

npm run build-storybook

Using shared CSS paths​

To load shared CSS paths, configure them using loadPaths css option in the viteFinal function.

import path from 'node:path';
import { UserConfig, mergeConfig } from 'vite';

export async function viteFinal(config: UserConfig) {
  return mergeConfig(config, {
    css: {
      preprocessorOptions: {
        scss: {
          loadPaths: `${path.resolve(__dirname, '../src/lib/styles')}`,
        },
      },
    },
  });
}

Using TypeScript Config Path Aliases​

If you are using paths in your tsconfig.json, support for those aliases can be added to the vite.config.ts.

With Angular CLI​

First, install the vite-tsconfig-paths package.

npm install vite-tsconfig-paths --save-dev

Next, add the plugin to the plugins array in the .storybook/main.ts.

import viteTsConfigPaths from 'vite-tsconfig-paths';
import { UserConfig, mergeConfig } from 'vite';

export async function viteFinal(config: UserConfig) {
  return mergeConfig(config, {
    plugins: [viteTsConfigPaths()],
  });
}

With Nx​

For Nx workspaces, import and use the nxViteTsPaths plugin from the @nx/vite package. Add the plugin to the plugins array in the .storybook/main.ts.

import { nxViteTsPaths } from '@nx/vite/plugins/nx-tsconfig-paths.plugin';
import { UserConfig, mergeConfig } from 'vite';

export async function viteFinal(config: UserConfig) {
  return mergeConfig(config, {
    plugins: [nxViteTsPaths()],
  });
}

Using File Replacements​

You can also use the replaceFiles() plugin from Nx to replace files during your build.

Import the plugin and set it up:

import { replaceFiles } from '@nx/vite/plugins/rollup-replace-files.plugin';
import { UserConfig, mergeConfig } from 'vite';

export async function viteFinal(config: UserConfig) {
  return mergeConfig(config, {
    plugins: [
      replaceFiles([
        {
          replace: './src/one.ts',
          with: './src/two.ts',
        },
      ]),
    ],
  });
}

Adding the replacement files to files array in the tsconfig.app.json may also be necessary.

{
  "extends": "./tsconfig.json",
  // other config
  "files": ["src/main.ts", "src/main.server.ts", "src/two.ts"]
}