Merge pull request #30103 from storybookjs/8-5-docs-fixes

Docs: Fixes found during 8.5 QA

docs/_snippets/vitest-plugin-vitest-config.md

@@ -11,6 +11,8 @@ export default mergeConfig(
   defineConfig({
     plugins: [
       storybookTest({
+        // The location of your Storybook config, main.js|ts
+        configDir: './.storybook',
         // This should match your package.json script to run Storybook
         // The --ci flag will skip prompts and not open a browser
         storybookScript: 'yarn storybook --ci',
@@ -44,6 +46,8 @@ export default mergeConfig(
   defineConfig({
     plugins: [
       storybookTest({
+        // The location of your Storybook config, main.js|ts
+        configDir: './.storybook',
         // This should match your package.json script to run Storybook
         // The --ci flag will skip prompts and not open a browser
         storybookScript: 'yarn storybook --ci',
@@ -78,6 +82,8 @@ export default mergeConfig(
   defineConfig({
     plugins: [
       storybookTest({
+        // The location of your Storybook config, main.js|ts
+        configDir: './.storybook',
         // This should match your package.json script to run Storybook
         // The --ci flag will skip prompts and not open a browser
         storybookScript: 'yarn storybook --ci',

docs/_snippets/vitest-plugin-vitest-workspace.md

@@ -12,6 +12,8 @@ export default defineWorkspace([
     extends: './vite.config.ts',
     plugins: [
       storybookTest({
+        // The location of your Storybook config, main.js|ts
+        configDir: './.storybook',
         // This should match your package.json script to run Storybook
         // The --ci flag will skip prompts and not open a browser
         storybookScript: 'yarn storybook --ci',
@@ -49,6 +51,8 @@ export default defineWorkspace([
     extends: './vite.config.ts',
     plugins: [
       storybookTest({
+        // The location of your Storybook config, main.js|ts
+        configDir: './.storybook',
         // This should match your package.json script to run Storybook
         // The --ci flag will skip prompts and not open a browser
         storybookScript: 'yarn storybook --ci',
@@ -87,6 +91,8 @@ export default defineWorkspace([
     extends: './vite.config.ts',
     plugins: [
       storybookTest({
+        // The location of your Storybook config, main.js|ts
+        configDir: './.storybook',
         // This should match your package.json script to run Storybook
         // The --ci flag will skip prompts and not open a browser
         storybookScript: 'yarn storybook --ci',

docs/_snippets/webpack-final-to-vite-final.md

@@ -0,0 +1,83 @@
+```js filename=".storybook/main.js" renderer="common" language="js" tabTitle="With Webpack"
+export default {
+  // Replace your-framework with the framework you are using (e.g., react-webpack5, nextjs, angular)
+  framework: '@storybook/your-framework',
+  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  async webpackFinal(config) {
+    storybookBaseConfig.module?.rules?.push({
+      test: /\.(graphql|gql)$/,
+      include: [path.resolve('./lib/emails')],
+      exclude: /node_modules/,
+      loader: 'graphql-tag/loader',
+    });
+    storybookBaseConfig.module?.rules?.push({
+      test: /\.(graphql|gql)$/,
+      include: [path.resolve('./lib/schema')],
+      exclude: /node_modules/,
+      loader: 'raw-loader',
+    });
+
+    return config;
+  },
+};
+```
+
+```js filename=".storybook/main.js" renderer="common" language="js" tabTitle="With Vite"
+export default {
+  // Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite)
+  framework: '@storybook/your-framework',
+  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  async viteFinal(config) {
+    return {
+      ...config,
+      plugins: [...(config.plugins ?? []), graphql()],
+    };
+  },
+};
+```
+
+```ts filename=".storybook/main.ts" renderer="common" language="ts" tabTitle="With Webpack"
+// Replace your-framework with the framework you are using (e.g., react-webpack5, nextjs, angular)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
+  framework: '@storybook/your-framework',
+  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  async webpackFinal(config) {
+    storybookBaseConfig.module?.rules?.push({
+      test: /\.(graphql|gql)$/,
+      include: [path.resolve('./lib/emails')],
+      exclude: /node_modules/,
+      loader: 'graphql-tag/loader',
+    });
+    storybookBaseConfig.module?.rules?.push({
+      test: /\.(graphql|gql)$/,
+      include: [path.resolve('./lib/schema')],
+      exclude: /node_modules/,
+      loader: 'raw-loader',
+    });
+
+    return config;
+  },
+};
+
+export default config;
+```
+
+```ts filename=".storybook/main.ts" renderer="common" language="ts" tabTitle="With Vite"
+// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite)
+import type { StorybookConfig } from '@storybook/your-framework';
+
+const config: StorybookConfig = {
+  framework: '@storybook/your-framework',
+  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+  async viteFinal(config) {
+    return {
+      ...config,
+      plugins: [...(config.plugins ?? []), graphql()],
+    };
+  },
+};
+
+export default config;
+```

docs/builders/vite.mdx

@@ -82,6 +82,20 @@ If you need, you can also configure Storybook's Vite builder using TypeScript. R
 
 ## Troubleshooting
 
+### Migrating from Webpack
+
+Vite generally handles more use cases out of the box than Webpack. For example, loading styles just works for most projects. So, when migrating a Webpack-based project to Vite, you may find that you don't need all of your previous configuration.
+
+We recommend starting with no Storybook-specific Vite configuration and only adding what you determine your project actually requires.
+
+For reference, here is a Webpack configuration to handle loading graphql queries and its equivalent, using a plugin, in Vite:
+
+{/* prettier-ignore-start */}
+
+<CodeSnippets path="webpack-final-to-vite-final.md" />
+
+{/* prettier-ignore-end */}
+
 ### Working directory not being detected
 
 By default, the Vite builder enables Vite's [`server.fs.strict`](https://vitejs.dev/config/#server-fs-strict) option for increased security, defining the project's `root` to Storybook's configuration directory.

docs/get-started/frameworks/nextjs.mdx

@@ -108,6 +108,8 @@ Storybook for Next.js is a [framework](../../contribute/framework.mdx) that make
 
   <Callout variant="info">
     If your Storybook configuration contains custom Webpack operations in [`webpackFinal`](../../api/main-config/main-config-webpack-final.mdx), you will likely need to create equivalents in [`viteFinal`](../../api/main-config/main-config-vite-final.mdx).
+
+    For more information, see the [Vite builder documentation](../../builders/vite.mdx#migrating-from-webpack).
   </Callout>
 
   Finally, if you were using Storybook plugins to integrate with Next.js, those are no longer necessary when using this framework and can be removed:

docs/writing-tests/test-addon.mdx

@@ -41,6 +41,8 @@ Before installing, make sure your project meets the following requirements:
 - A Storybook framework that uses Vite (e.g. [`vue3-vite`](../get-started/frameworks/vue3-vite.mdx), [`react-vite`](../get-started/frameworks/react-vite.mdx), ['sveltekit`](../get-started/frameworks/sveltekit.mdx), etc.), or the [Storybook Next.js framework with Vite](../get-started/frameworks/nextjs.mdx#with-vite)
 - Vitest ≥ 2.1
     - If you're not yet using Vitest, it will be installed and configured for you when you install the addon
+- (optional) MSW ≥ 2.0
+    - If MSW is installed, it must be v2.0.0 or later to not conflict with Vitest's dependency
 
 <If renderer="react">
   <Callout variant="info" icon="ℹ️">
@@ -96,7 +98,9 @@ Some Storybook frameworks require additional setup to enable the framework's fea
     viteConfig,
     defineConfig({
       plugins: [
-        storybookTest(),
+        storybookTest({
+          // ...
+        }),
         storybookNextJsPlugin(), // 👈 Apply the framework plugin here
       ],
       // ...
@@ -119,7 +123,9 @@ Some Storybook frameworks require additional setup to enable the framework's fea
     viteConfig,
     defineConfig({
       plugins: [
-        storybookTest(),
+        storybookTest({
+          // ...
+        }),
         storybookVuePlugin(), // 👈 Apply the framework plugin here
       ],
       // ...
@@ -142,7 +148,9 @@ Some Storybook frameworks require additional setup to enable the framework's fea
     viteConfig,
     defineConfig({
       plugins: [
-        storybookTest(),
+        storybookTest({
+          // ...
+        }),
         storybookSveltekitPlugin(), // 👈 Apply the framework plugin here
       ],
       // ...
@@ -313,6 +321,7 @@ export default defineWorkspace([
     {
       plugins: [
         storybookTest({
+          // ...
           storybookScript: 'yarn storybook --ci',
           storybookUrl: process.env.SB_URL
         }),
@@ -427,17 +436,9 @@ If your stories use assets in the public directory and you're not using the defa
 
 ### How do I apply custom Vite configuration?
 
-If you have custom operations defined in [`viteFinal`](../api/main-config/main-config-vite-final.mdx) in your `.storybook/main.js|ts` file, you will need to translate those into the Vitest configuration. This is because the plugin does not use the Storybook Vite configuration.
-
-For example, to recreate an alias in Storybook's Vite configuration, you would need to apply that alias in the Vitest configuration:
-
-{/* prettier-ignore-start */}
-
-<CodeSnippets path="vitest-plugin-vitest-config-alias.md" />
-
-{/* prettier-ignore-end */}
+Your Storybook project's Vite configuration (in [`viteFinal`](../api/main-config/main-config-vite-final.mdx) in your `.storybook/main.js|ts` file) is automatically applied to your Vitest configuration, with one exception: the plugins.
 
-The above example places the Vite configuration in a Vitest configuration file. You can also place it in a Vitest workspace file, if that is how your project is configured.
+If you are running any plugins in `viteFinal`, you will likely also need to run those in the Vitest configuration.
 
 ### How do I isolate Storybook tests from others?
 

docs/writing-tests/test-coverage.mdx

@@ -34,6 +34,29 @@ Before coverage can be calculated, you may need to install a support package cor
 
 {/* prettier-ignore-end */}
 
+Additionally (until Vitest 3.0.0 is released), the generated coverage report will include the stories files themselves and output from your built Storybook application. This is misleading and they should be excluded. To do this, you can add the following to your Vitest config:
+
+```ts title="vitest.config.ts"
+import { coverageConfigDefaults, defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  // ...
+  test: {
+    coverage: {
+      // 👇 Add this
+      exclude: [
+         ...coverageConfigDefaults.exclude,
+         '**/.storybook/**',
+         // 👇 This pattern must align with the `stories` property of your `.storybook/main.ts` config
+         '**/*.stories.*',
+         // 👇 This pattern must align with the output directory of `storybook build`
+         '**/storybook-static/**',
+       ], 
+    }
+  }
+})
+```
+
 ### Usage
 
 Because coverage is built into the Test addon, you can use it everywhere you run your tests.
@@ -188,32 +211,6 @@ When calculating coverage in the Storybook UI, the following options are always
 - `reporter`
 - `reportsDirectory`
 
-### Troubleshooting
-
-#### Excluding stories from the coverage report
-
-Until Vitest 3.0.0 is released, the generated coverage report will include the stories files themselves and output from your built Storybook application. This is misleading and they should be excluded. To do this, you can add the following to your Vitest config:
-
-```ts title="vitest.config.ts"
-import { coverageConfigDefaults, defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  // ...
-  test: {
-    coverage: {
-      // 👇 Add this
-      exclude: [
-         ...coverageConfigDefaults.exclude,
-         // This pattern must align with the `stories` property of your `.storybook/main.ts` config
-         '**/*.stories.*',
-         // This pattern must align with the output directory of `storybook build`
-         'storybook-static/**',
-       ], 
-    }
-  }
-})
-```
-
 </If>
 
 ## With the coverage addon