From 50a61c5d252706ada425a5aa5cfbd0acf5b8e275 Mon Sep 17 00:00:00 2001
From: Kyle Gach <kyle.gach@gmail.com>
Date: Fri, 27 Dec 2024 15:13:05 -0600
Subject: [PATCH] Add webpack-to-vite migration guidance

---
 docs/_snippets/webpack-final-to-vite-final.md | 83 +++++++++++++++++++
 docs/builders/vite.mdx                        | 14 ++++
 docs/get-started/frameworks/nextjs.mdx        |  2 +
 3 files changed, 99 insertions(+)
 create mode 100644 docs/_snippets/webpack-final-to-vite-final.md

diff --git a/docs/_snippets/webpack-final-to-vite-final.md b/docs/_snippets/webpack-final-to-vite-final.md
new file mode 100644
index 000000000000..df83bc4fa7c5
--- /dev/null
+++ b/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;
+```
diff --git a/docs/builders/vite.mdx b/docs/builders/vite.mdx
index 8f226e4f5844..99c411dac1e1 100644
--- a/docs/builders/vite.mdx
+++ b/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.
diff --git a/docs/get-started/frameworks/nextjs.mdx b/docs/get-started/frameworks/nextjs.mdx
index 14e2c3e55294..62b2c5b7ff88 100644
--- a/docs/get-started/frameworks/nextjs.mdx
+++ b/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: