storybook-addon-dependency-previews 0.3.0 → 0.4.0-beta.0

package/README.md

@@ -8,7 +8,7 @@
 
 A plugin for [Storybook](https://storybook.js.org/) that shows the full dependency tree in both directions (built with and used by) the components in your application.
 
-Currently works with **React**, **Svelte**, and **Angular**.
+Currently works with **React**, **Svelte**, **Angular**, and **Next.js**. The automated `sb-deps setup` wizard handles Vite-based projects (React, Svelte) end-to-end. Webpack-based projects (Angular, Next.js) need a one-time manual setup — see the [manual-setup-webpack guide](https://github.com/Dan503/storybook-addon-dependency-previews/blob/main/storybook-addon-package/docs/manual-setup-webpack.md) below.
 
 This is what you will see in Storybook after Dependency Previews have been installed and configured:
 
@@ -42,375 +42,33 @@ The below image demonstrates what you will see when you open up some of the depe
 
 ## Installation guide
 
-### Package download
+### Quick start (React and Svelte)
 
-First you will need to install the plugin via npm as well as [dependency-cruiser](https://www.npmjs.com/package/dependency-cruiser)
+After running `npx storybook@latest init` in your project, run the setup wizard:
 
+```sh
+npx --package storybook-addon-dependency-previews sb-deps setup
 ```
-npm install -D storybook-addon-dependency-previews dependency-cruiser
-```
-
-<details>
-	<summary>Other package managers</summary>
-	<p><pre><code>pnpm add -D storybook-addon-dependency-previews dependency-cruiser</code></pre></p>
-	<p><pre><code>yarn add -D storybook-addon-dependency-previews dependency-cruiser</code></pre></p>
-	<p><pre><code>bun add -D storybook-addon-dependency-previews dependency-cruiser</code></pre></p>
-	<p><pre><code>deno add --dev npm:storybook-addon-dependency-previews npm:dependency-cruiser</code></pre></p>
-</details>
-
-### Register the add-on
-
-From your root folder, open your `.storybook/main.ts` file.
-
-Edit the `main.ts` to contain the following values or copy/paste the below to replace the full contents of the main.ts file.
-
-#### Register with React
-
-```ts
-import type { StorybookConfig } from '@storybook/react-vite'
-
-const config: StorybookConfig = {
-	stories: ['../src/**/*.stories.@(ts|tsx|mdx)'],
-	addons: [
-		// autodocs is required for this addon to work
-		'@storybook/addon-docs',
-		// the storybook dependency previews addon registration
-		'storybook-addon-dependency-previews/addon',
-	],
-	framework: {
-		name: '@storybook/react-vite',
-		options: {},
-	},
-}
-
-export default config
-```
-
-#### Register with Svelte
-
-```ts
-import type { StorybookConfig } from '@storybook/sveltekit'
-
-const config: StorybookConfig = {
-	stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|ts|svelte)'],
-	addons: [
-		// autodocs is required for this addon to work
-		'@storybook/addon-docs',
-		// required for .stories.svelte CSF format
-		'@storybook/addon-svelte-csf',
-		// the storybook dependency previews addon registration
-		'storybook-addon-dependency-previews/addon',
-	],
-	framework: '@storybook/sveltekit',
-}
-
-export default config
-```
-
-#### Register with Angular
-
-`@storybook/angular` uses webpack5 exclusively. The addon requires two webpack additions in `webpackFinal`: a `DefinePlugin` to inject `__PROJECT_ROOT__` (needed for the VS Code "open file" feature), and a `NormalModuleFactory` plugin to handle the addon's CSS modules correctly.
-
-You will also need a `css-modules-loader.cjs` file alongside your `.storybook/main.ts`. Copy it from the [Angular example source](https://github.com/Dan503/storybook-addon-dependency-previews/blob/main/example-site/angular/.storybook/css-modules-loader.cjs).
-
-```ts
-import type { StorybookConfig } from '@storybook/angular'
-import { createRequire } from 'module'
-import { fileURLToPath } from 'url'
-import path from 'path'
-
-const require = createRequire(import.meta.url)
-
-const config: StorybookConfig = {
-	stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
-	addons: [
-		// autodocs is required for this addon to work
-		'@storybook/addon-docs',
-		// the storybook dependency previews addon registration
-		'storybook-addon-dependency-previews/addon',
-	],
-	framework: {
-		name: '@storybook/angular',
-		options: {},
-	},
-	webpackFinal: async (config) => {
-		const sbAngularRequire = createRequire(
-			import.meta.resolve('@storybook/angular'),
-		)
-		const webpack = sbAngularRequire('webpack') as any
-
-		// Path to the css-modules-loader.cjs file (copy from the Angular example source)
-		const cssModulesLoader = fileURLToPath(
-			new URL('./css-modules-loader.cjs', import.meta.url),
-		)
-
-		config.plugins = config.plugins ?? []
-
-		// Inject __PROJECT_ROOT__ so preview.ts can pass it to projectRootPath
-		config.plugins.push(
-			new webpack.DefinePlugin({
-				__PROJECT_ROOT__: JSON.stringify(
-					path.resolve(fileURLToPath(new URL('..', import.meta.url))),
-				),
-			}),
-		)
-
-		// Handle CSS modules for the addon's dist files
-		config.plugins.push({
-			apply(compiler: any) {
-				compiler.hooks.normalModuleFactory.tap(
-					'AddonCssModules',
-					(factory: any) => {
-						factory.hooks.afterResolve.tap(
-							'AddonCssModules',
-							(resolveData: any) => {
-								const resource: string =
-									resolveData.createData?.resource ?? ''
-								if (
-									resource.endsWith('.module.css') &&
-									resource.includes(
-										'storybook-addon-dependency-previews',
-									)
-								) {
-									resolveData.createData.loaders = [
-										{
-											loader: cssModulesLoader,
-											options: {},
-										},
-									]
-								}
-							},
-						)
-					},
-				)
-			},
-		})
-
-		return config
-	},
-}
-export default config
-```
-
-### Bare minimum storybook story example
-
-Get a story ready so you have something to test with.
-
-Below is the bare minimum needed to generate a viable story that is compatible with the add-on.
-
-#### React `.stories.tsx` file example
-
-```ts
-import type { Meta, StoryObj } from '@storybook/react-vite'
-import { ComponentName } from './ComponentName'
-
-const meta: Meta<typeof ComponentName> = {
-	// You can use spaces here to make the title of the story page more human readable
-	title: 'Component Name',
-	component: ComponentName,
-	// autodocs tag is required
-	tags: ['autodocs'],
-	// The `__filePath` property must be applied to every story file
-	// for the addon to track dependencies effectively
-	// `import.meta.url` is a Vite specific value that automatically generates the path for you
-	parameters: {
-		__filePath: import.meta.url,
-	},
-}
-
-export default meta
-
-type Story = StoryObj<typeof meta>
 
-export const Primary: Story = {
-	args: {},
-}
-```
-
-#### Svelte `.stories.svelte` file using [Svelte CSF](https://github.com/storybookjs/addon-svelte-csf)
-
-```svelte
-<script module>
-	import { defineMeta } from '@storybook/addon-svelte-csf'
-	import ComponentName from './ComponentName.svelte'
-
-	const { Story } = defineMeta({
-		title: 'Component Name',
-		component: ComponentName,
-		// autodocs tag is required
-		tags: ['autodocs'],
-		// The `__filePath` property must be applied to every story file
-		parameters: {
-			__filePath: import.meta.url,
-		},
-	})
-</script>
-
-<Story name="Primary" />
-```
-
-#### Angular `.stories.ts` file example
-
-```ts
-import type { Meta, StoryObj } from '@storybook/angular'
-import type { StoryParameters } from 'storybook-addon-dependency-previews'
-import { ComponentName } from './ComponentName.component'
-
-const meta: Meta<ComponentName> = {
-	// You can use spaces here to make the title of the story page more human readable
-	title: 'Component Name',
-	component: ComponentName,
-	// autodocs tag is required
-	tags: ['autodocs'],
-	// The `__filePath` property must be applied to every story file
-	// for the addon to track dependencies effectively
-	// `import.meta.url` is a webpack feature available in Angular Storybook
-	parameters: {
-		__filePath: import.meta.url,
-	} satisfies StoryParameters,
-}
-
-export default meta
-
-type Story = StoryObj<ComponentName>
-
-export const Primary: Story = {}
-```
-
-### package.json scripts
-
-You will need the following scripts in your `package.json` file:
-
-```json
-// package.json
-{
-	...
-	"scripts": {
-		...
-		"sb": "sb-deps --watch --run-storybook",
-		"sb:build": "sb-deps && storybook build",
-		"sb:deps": "sb-deps",
-		"sb:alt-port": "sb-deps --watch --run-storybook --sb-port 7020"
-	}
-	...
-}
-```
-
-Don't run any of these yet, you are not finished with the installation.
-
-`npm run sb` will run storybook in watch mode. It will update the dependency-previews.json file whenever a story file changes, is added, or removed. Use this instead of the `storybook` command to take advantage of automatic dependency tracking while you work and auto scaffolding of stories when new story files are created.
-
-`npm run sb:build` will do a one off compile of your storybook website
-
-`npm run sb:deps` will generate a fresh dependency-previews.json on demand
-
-`npm run sb:alt-port` (optional) will run storybook in watch mode and run it using a specific port number.
-
-#### Angular projects
-
-`@storybook/angular@10+` requires Storybook to be launched through the Angular CLI builder rather than the default `storybook dev` command. Pass the Angular CLI target as an argument to `--run-storybook`:
-
-```json
-"sb": "sb-deps --watch --run-storybook \"ng run <project-name>:storybook\""
-```
-
-Replace `<project-name>` with the name of your Angular project as defined in `angular.json`.
-
-### Create the preview file
-
-First run `npm run sb:deps` to generate a fresh `dependency-previews.json` file in the `.storybook` folder.
-
-Make sure that the `"resolveJsonModule"` tsConfig.json setting is set to `true` to import this file.
-
-Now create a `.storybook/preview.ts` file (or `preview.tsx` if your framework requires JSX) with the following content:
-
-```ts
-/// <reference types="vite/client" />
-
-import {
-	defaultPreviewParameters,
-	dependencyPreviewDecorators,
-	type StorybookPreviewConfig,
-} from 'storybook-addon-dependency-previews'
-
-// Import the generated dependency-previews.json file
-import dependenciesJson from './dependency-previews.json'
-
-// Global styles are imported here (optional)
-import '../src/styles.css'
-
-const previewConfig: StorybookPreviewConfig = {
-	decorators: [...dependencyPreviewDecorators],
-	parameters: {
-		...defaultPreviewParameters,
-		dependencyPreviews: {
-			dependenciesJson,
-			storyModules: import.meta.glob(
-				'/src/**/*.stories.@(tsx|ts|jsx|js|svelte)',
-				{ eager: false },
-			),
-			// Replace this with the URL to your src folder in your git repository.
-			// This enables the addon to link to the source code of the component.
-			sourceRootUrl:
-				'https://github.com/your-org/your-repo/blob/main/src',
-			// This allows Source File Path to open the
-			// component file directly in VS Code when
-			// running in a local host environment.
-			// `import.meta.url` is a Vite specific feature
-			projectRootPath: new URL('..', import.meta.url).pathname,
-		},
-	},
-}
-
-export default previewConfig
-```
-
-#### Angular `preview.ts`
-
-Angular uses webpack, so `import.meta.glob` and Vite-specific APIs are not available. Use the `__PROJECT_ROOT__` value injected via `DefinePlugin` in `main.ts` instead:
-
-```ts
-import type { Preview } from '@storybook/angular'
-import {
-	defaultPreviewParameters,
-	dependencyPreviewDecorators,
-} from 'storybook-addon-dependency-previews'
-import dependenciesJson from './dependency-previews.json'
-
-declare const __PROJECT_ROOT__: string
-
-const preview: Preview = {
-	parameters: {
-		...defaultPreviewParameters,
-		dependencyPreviews: {
-			dependenciesJson,
-			// Replace this with the URL to your src folder in your git repository.
-			// This enables the addon to link to the source code of the component.
-			sourceRootUrl:
-				'https://github.com/your-org/your-repo/blob/main/src',
-			// __PROJECT_ROOT__ is injected by DefinePlugin in main.ts.
-			// This allows Source File Path to open the component file
-			// directly in VS Code when running in a local host environment.
-			projectRootPath: __PROJECT_ROOT__,
-		},
-	},
-	decorators: [...dependencyPreviewDecorators],
-}
-
-export default preview
-```
+(The package's bin is `sb-deps`, but the published package name is `storybook-addon-dependency-previews`. The explicit `--package` form makes `npx` install the right package on the first run; once the wizard has installed the addon, you can use the shorter `npx sb-deps …` form for subsequent calls.)
 
-> **Note:** Angular does not use `storyModules` (no `import.meta.glob`). The addon still generates the full dependency tree via the CLI — only the VS Code "open file" shortcut needs `projectRootPath`.
+The wizard:
 
-### Run it!
+- detects your framework, package manager, and existing Storybook config,
+- installs `storybook-addon-dependency-previews` and `dependency-cruiser`,
+- registers the addon in `.storybook/main.ts`,
+- patches (or creates) `.storybook/preview.ts` with the addon's parameters and decorators,
+- adds the `sb`, `sb:deps`, and `sb:build` scripts to your `package.json`,
+- generates the initial `.storybook/dependency-previews.json`.
 
-You should be all set now.
+When it finishes, run `npm run sb` (or your package manager's equivalent) to start Storybook with dependency watching.
 
-Try running `npm run sb` to boot up storybook, leave it running as you work.
+### Manual setup
 
-As you create new component files, the component will be auto-scaffolded for you and a matching story file will be created for it automatically. The dependency previews json file will also be auto-updated.
+The wizard supports React (`@storybook/react-vite`) and Svelte (`@storybook/sveltekit`, `@storybook/svelte-vite`) — all Vite-based. **Angular (`@storybook/angular`) and Next.js (`@storybook/nextjs`) projects are both webpack-based and require manual setup** — the wizard's preview-patcher relies on Vite's `import.meta.glob`, which webpack doesn't expose. Follow the matching guide below:
 
-This workflow allows you to focus on what matters instead of having to waste time writing lots of boilerplate code every time you want to create a new component.
+- [Manual setup — Vite (React, Svelte)](https://github.com/Dan503/storybook-addon-dependency-previews/blob/main/storybook-addon-package/docs/manual-setup-vite.md)
+- [Manual setup — webpack (`@storybook/angular`, `@storybook/nextjs`)](https://github.com/Dan503/storybook-addon-dependency-previews/blob/main/storybook-addon-package/docs/manual-setup-webpack.md)
 
 ## Configuration file (optional)
 

package/dist/blocks/DependencyPreviews.d.cts

@@ -1,7 +1,7 @@
-import * as react_jsx_runtime1 from "react/jsx-runtime";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/blocks/DependencyPreviews.d.ts
-declare function DependencyPreviews(): react_jsx_runtime1.JSX.Element;
+declare function DependencyPreviews(): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { DependencyPreviews };
 //# sourceMappingURL=DependencyPreviews.d.cts.map

package/dist/blocks/DependencyPreviews.d.mts

@@ -1,7 +1,7 @@
-import * as react_jsx_runtime1 from "react/jsx-runtime";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/blocks/DependencyPreviews.d.ts
-declare function DependencyPreviews(): react_jsx_runtime1.JSX.Element;
+declare function DependencyPreviews(): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { DependencyPreviews };
 //# sourceMappingURL=DependencyPreviews.d.mts.map

package/dist/cli/sb-deps.cjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_cli_setup_index = require('./setup/index.cjs');
 let node_fs = require("node:fs");
 node_fs = require_rolldown_runtime.__toESM(node_fs);
 let node_path = require("node:path");
@@ -17,18 +18,19 @@ node_url = require_rolldown_runtime.__toESM(node_url);
 
 //#region cli/sb-deps.ts
 const argv = process.argv.slice(2);
+const SUBCOMMAND = argv[0] && !argv[0].startsWith("--") ? argv[0] : null;
 const WATCH = argv.includes("--watch");
 const RUN_SB_IDX = argv.indexOf("--run-storybook");
 const RUN_SB = RUN_SB_IDX !== -1;
 const _RUN_SB_NEXT = RUN_SB ? argv[RUN_SB_IDX + 1] : undefined;
 const SB_CUSTOM_CMD = _RUN_SB_NEXT && !_RUN_SB_NEXT.startsWith("--") ? _RUN_SB_NEXT : undefined;
-const PORT_ARGI = Math.max(argv.indexOf("--sb-port"), 0);
-const SB_PORT = PORT_ARGI && argv[PORT_ARGI + 1] ? Number(argv[PORT_ARGI + 1]) || 6006 : 6006;
+const PORT_ARGI = argv.indexOf("--sb-port");
+const SB_PORT = PORT_ARGI !== -1 && argv[PORT_ARGI + 1] ? Number(argv[PORT_ARGI + 1]) || 6006 : 6006;
 const projectRoot = process.cwd();
 const outDir = (0, node_path.resolve)(projectRoot, ".storybook");
 const rawPath = (0, node_path.join)(outDir, "dependency-previews.raw.json");
 const cookedPath = (0, node_path.join)(outDir, "dependency-previews.json");
-if (!(0, node_fs.existsSync)(outDir)) (0, node_fs.mkdirSync)(outDir, { recursive: true });
+if (SUBCOMMAND !== "setup" && !(0, node_fs.existsSync)(outDir)) (0, node_fs.mkdirSync)(outDir, { recursive: true });
 const __filename$1 = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
 const __dirname$1 = (0, node_path.dirname)(__filename$1);
 const pkgDefault = (0, node_path.resolve)(__dirname$1, "scripts", "depcruise.config.cjs");
@@ -681,10 +683,11 @@ async function startStorybook() {
 	const isWin = process.platform === "win32";
 	let cmd;
 	let args;
+	let shellMode;
 	if (SB_CUSTOM_CMD) {
-		const parts = SB_CUSTOM_CMD.split(" ");
-		cmd = parts[0];
-		args = parts.slice(1);
+		cmd = SB_CUSTOM_CMD;
+		args = [];
+		shellMode = true;
 	} else {
 		cmd = "npx";
 		args = [
@@ -694,12 +697,13 @@ async function startStorybook() {
 			"-p",
 			String(SB_PORT)
 		];
+		shellMode = isWin;
 	}
 	info(`[sb-deps] launching: ${cmd} ${args.join(" ")}`);
 	sbChild = (0, node_child_process.spawn)(cmd, args, {
 		cwd: projectRoot,
 		stdio: "inherit",
-		shell: isWin,
+		shell: shellMode,
 		env: process.env
 	});
 	sbChild.on("error", (err) => {
@@ -713,6 +717,10 @@ async function startStorybook() {
 }
 ;
 (async () => {
+	if (SUBCOMMAND === "setup") {
+		await require_cli_setup_index.runSetup(argv.slice(1));
+		return;
+	}
 	const cfg = await loadSbDepsConfig();
 	ANGULAR_SELECTOR_PREFIX = cfg.angularSelectorPrefix ?? "app-";
 	SCAFFOLD_CONFIG = cfg.scaffold ?? {};