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 using the AnalogJS Storybook integration. This package can be applied to any Angular project using Storybook.

This is a community integration not maintained by the Storybook team. If you have issues, file an issue in our GitHub repo.

Compatibility Guide

The AnalogJS Storybook integration for using Angular and Vite supports multiple versions of Storybook. See the table below for which version to install based on the project dependencies.

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 Integration for Angular and Vite. Depending on your preferred package manager, run one of the following commands:

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

yarn add @analogjs/storybook-angular @analogjs/vite-plugin-angular --dev

pnpm install @analogjs/storybook-angular @analogjs/vite-plugin-angular -w --save-dev

bun install @analogjs/storybook-angular @analogjs/vite-plugin-angular --save-dev

Configuring Storybook

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

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

export default config;

Framework Options

framework.options configures the Angular compilation for Storybook. These options are passed to @analogjs/vite-plugin-angular with Storybook-specific defaults:

const config: StorybookConfig = {
  framework: {
    name: '@analogjs/storybook-angular',
    options: {
      jit: false,
      liveReload: true,
      inlineStylesExtension: 'scss',
    },
  },
};

liveReload is separate from Vite's server.hmr option, which configures the HMR websocket transport. You can use server.hmr together with liveReload when Storybook needs custom host, port, or path settings.

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, add them to the @analogjs/storybook-angular builder options in the angular.json or project.json.

    "storybook": {
      "builder": "@analogjs/storybook-angular:start-storybook",
      "options": {
        // ... other options
        "styles": [
          "src/styles.css"
        ],
        "stylePreprocessorOptions": {
          "loadPaths": ["libs/my-lib/styles"]
        }
      }
    },
    "build-storybook": {
      "builder": "@analogjs/storybook-angular:build-storybook",
      "options": {
        // ... other options
        "styles": [
          "src/styles.css"
        ],
        "stylePreprocessorOptions": {
          "loadPaths": ["libs/my-lib/styles"]
        }
      }
    }

The Storybook preset uses these options for different jobs:

• styles entries are imported into Storybook's generated preview module, so use them for global stylesheets that every story should load
• stylePreprocessorOptions.loadPaths are passed to Vite's SCSS preprocessor, so use them for Sass @use and @import resolution inside .scss files

For Nx workspaces with shared SCSS libraries, keep the paths workspace-relative in project.json:

{
  "storybook": {
    "executor": "@analogjs/storybook-angular:start-storybook",
    "options": {
      "configDir": "libs/shared/ui/.storybook",
      "styles": [
        "libs/shared/ui/styles/shared-ui.scss",
        "libs/shared/ui/.storybook/storybook.scss"
      ],
      "stylePreprocessorOptions": {
        "loadPaths": ["libs/shared/ui/styles"]
      }
    }
  }
}

Use the styles array for actual global stylesheet files. Use loadPaths only to help Sass resolve imports from those files; it does not load a stylesheet by itself.

For third-party package styles, prefer bare package imports such as katex/dist/katex.css or @angular/material/prebuilt-themes/deeppurple-amber.css over node_modules/... paths when the package exports them.

Enabling Zoneless Change Detection

To use zoneless change detection for the Storybook, add the experimentalZoneless flag to the @analogjs/storybook-angular builder options in the angular.json or project.json.

    "storybook": {
      "builder": "@analogjs/storybook-angular:start-storybook",
      "options": {
        // ... other options
        "experimentalZoneless": true
      }
    },
    "build-storybook": {
      "builder": "@analogjs/storybook-angular:build-storybook",
      "options": {
        // ... other options
        "experimentalZoneless": true
      }
    }

    "storybook": {
      "executor": "@analogjs/storybook-angular:start-storybook",
      "options": {
        // ... other options
        "configDir": "path/to/.storybook",
        "experimentalZoneless": true,
        "compodoc": false
      }
    },
    "build-storybook": {
      "executor": "@analogjs/storybook-angular:build-storybook",
      "options": {
        // ... other options
        "configDir": "path/to/.storybook",
        "experimentalZoneless": true,
        "compodoc": false
      }
    }

Zoneless change detection is the default for new projects starting Angular v21.

Enabling Fast Compilation

To speed up Storybook startup and rebuilds, enable fast compile in the framework options in .storybook/main.ts.

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

export default config;

Fast compile skips Angular's template type-checking, so run type-checking separately if needed.

Setting up Static Assets

Static assets are configured in the .storybook/main.ts file using the staticDirs array.

The example below shows how to add the public directory from src/public relative to the .storybook/main.ts file.

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

export default config;

See the Storybook docs on images and assets for more information.

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 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

yarn add vite-tsconfig-paths --dev

pnpm install -w vite-tsconfig-paths --save-dev

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

const config: StorybookConfig = {
  // ... other config, addons, etc.
  async viteFinal(config: UserConfig) {
    return mergeConfig(config, {
      plugins: [viteTsConfigPaths()],
    });
  },
};

export default config;

With Nx

In Nx workspaces, normal workspace library imports already resolve in Storybook. You usually do not need to add viteTsConfigPaths() just to resolve workspace packages.

If your workspace still depends on custom compilerOptions.paths aliases beyond those normal workspace package imports, add the viteTsConfigPaths plugin from vite-tsconfig-paths in .storybook/main.ts:

const config: StorybookConfig = {
  // ... other config, addons, etc.
  async viteFinal(config: UserConfig) {
    return mergeConfig(config, {
      plugins: [viteTsConfigPaths()],
    });
  },
};

export default config;

viteTsConfigPaths() is only for custom TypeScript path aliases. It does not replace Storybook's styles option or SCSS loadPaths, so shared Sass setups usually need:

• styles for global Storybook stylesheets
• stylePreprocessorOptions.loadPaths for Sass import roots
• viteTsConfigPaths() only if you still rely on custom TS/Angular aliases instead of normal workspace package imports

If styles still do not load as expected, enable scoped preset logging before running Storybook or the Storybook build:

DEBUG=analog-storybook:styles npm run storybook

This logs the resolved workspace root, SCSS loadPaths, and how each styles entry was classified:

• project when it resolves relative to the Storybook project root
• workspace when it resolves from the workspace root
• bare when it is left as a package import such as katex/dist/katex.css

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:

const config: StorybookConfig = {
  // ... other config, addons, etc.
  async viteFinal(config: UserConfig) {
    return mergeConfig(config, {
      plugins: [
        replaceFiles([
          {
            replace: './src/one.ts',
            with: './src/two.ts',
          },
        ]),
      ],
    });
  },
};

export default config;

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"]
}

Setting up Vitest for Interaction Testing

Storybook also supports using Vitest for testing component interactions.

Installing Packages

Install the Vitest addon and dependencies:

npm install @analogjs/vitest-angular @storybook/addon-vitest vitest @vitest/browser-playwright --save-dev

Add Vitest Add-on

Add the addon to your .storybook/main.ts:

const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@storybook/addon-essentials',
    '@storybook/addon-interactions',
    '@storybook/addon-vitest',
  ],
  framework: {
    name: '@analogjs/storybook-angular',
    options: {},
  },
};

export default config;

Setup Vitest Configuration

Create a .storybook/vitest.setup.ts file:

const project = setProjectAnnotations([projectAnnotations]);

beforeAll(project.beforeAll);

Update .storybook/tsconfig.json to include the setup file:

{
  "extends": "../tsconfig.app.json",
  "compilerOptions": {
    "types": ["node"],
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true
  },
  "exclude": ["../src/test.ts", "../src/**/*.spec.ts"],
  "include": ["../src/**/*.stories.*", "./preview.ts", "./vitest.setup.ts"],
  "files": ["./typings.d.ts"]
}

Create a vitest.config.ts file in your project root, or add a storybook project to your existing vite.config.ts:

/// <reference types="vitest/config" />
const dirname =
  typeof __dirname !== 'undefined'
    ? __dirname
    : path.dirname(fileURLToPath(import.meta.url));

export default defineConfig({
  test: {
    projects: [
      {
        extends: true,
        plugins: [
          storybookTest({
            configDir: path.join(dirname, '.storybook'),
          }),
        ],
        test: {
          name: 'storybook',
          browser: {
            enabled: true,
            headless: true,
            provider: playwright(),
            instances: [{ browser: 'chromium' }],
          },
          setupFiles: ['.storybook/vitest.setup.ts'],
        },
      },
    ],
  },
});

Installing Playwright

Install Playwright browser binaries:

npx playwright install chromium

Running Component Tests

Add the test-storybook target to your angular.json:

"test-storybook": {
  "builder": "@analogjs/vitest-angular:test",
  "options": {
    "configFile": "vitest.config.ts"
  }
}

Add a test script to your package.json:

"scripts": {
  "test-storybook": "ng run your-app:test-storybook"
}

Run your interaction tests with:

npm run test-storybook

You can also run tests directly in the Storybook UI. Start Storybook and use the "Run Tests" button in the sidebar, or navigate to a story to see interaction tests run automatically in the Interactions panel.

With Nx

In an Nx workspace using the @nx/storybook/plugin inferred targets, Nx 23.2 and newer detects @storybook/addon-vitest in the project's .storybook/main.ts and infers the test-storybook target as vitest run --project=storybook, so no target needs to be added to the project.json. Run the interaction tests with:

npx nx test-storybook your-app

Building with Angular in Development Mode

storybook build produces a production build, compiling Angular with optimizations and without its development debug API (for example window.ng.getComponent). If tooling runs against the built Storybook and needs that API, such as Playwright component tests, opt the build into Angular's development compilation by setting the Vite mode in viteFinal:

import { UserConfig } from 'vite';

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

const config: StorybookConfig = {
  // ... other config, addons, etc.
  async viteFinal(config: UserConfig) {
    return { ...config, mode: 'development' };
  },
};

export default config;

An explicit mode takes precedence over the production NODE_ENV that the Storybook CLI sets.

Code Coverage

To collect coverage while running your stories, enable the V8 provider on the storybook test project:

test: {
  name: 'storybook',
  coverage: {
    provider: 'v8',
    include: ['src/**/*.ts'],
  },
  browser: {
    enabled: true,
    headless: true,
    provider: playwright(),
    instances: [{ browser: 'chromium' }],
  },
  setupFiles: ['.storybook/vitest.setup.ts'],
},

Monorepo configuration

In a monorepo, a story often imports a shared library from another project through its package/barrel entry point (for example @my-org/ui). When coverage is configured to include those dependent-project sources, Vite pre-bundles the barrel and serves it from node_modules/.vite/deps. Browser-mode V8 coverage ignores any module served from node_modules, so the dependency is reported with 0 hits at its source path even though it executed. Merging that report with your unit-test report double-counts the file and drags the overall percentage down.

To collect real coverage for those dependencies, keep them out of Vite's dependency pre-bundling so they are served and instrumented from source. Add them to optimizeDeps.exclude in your .storybook/main.ts via viteFinal:

import { UserConfig, mergeConfig } from 'vite';

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

const config: StorybookConfig = {
  // ... other config, addons, etc.
  async viteFinal(config: UserConfig) {
    return mergeConfig(config, {
      // serve workspace libraries from source so browser coverage can instrument them
      optimizeDeps: {
        exclude: ['@my-org/ui'],
      },
    });
  },
};

export default config;

Alternatively, if you only want story-level coverage, scope coverage.include to the current project's files so dependent-project sources are not emitted as zero-hit records.