storybook-addon-dependency-previews 0.2.0 → 0.3.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** and **Svelte**. Angular support is coming soon.
+Currently works with **React**, **Svelte**, and **Angular**.
 
 This is what you will see in Storybook after Dependency Previews have been installed and configured:
 
@@ -32,6 +32,12 @@ The below image demonstrates what you will see when you open up some of the depe
 - [Svelte rendered example website](https://dependency-previews-demo-site-svelte.netlify.app/)
 - [Svelte demo source code](https://github.com/Dan503/storybook-addon-dependency-previews/tree/main/example-site/svelte)
 
+#### Angular demos
+
+- [Angular Storybook demo site](https://dependency-previews-storybook-angular.netlify.app/?path=/docs/04-templates-home-template--docs)
+- [Angular rendered example website](https://dependency-previews-demo-site-angular.netlify.app/)
+- [Angular demo source code](https://github.com/Dan503/storybook-addon-dependency-previews/tree/main/example-site/angular)
+
 <!-- TODO: Provide a video/gif of the addon in action -->
 
 ## Installation guide
@@ -101,6 +107,91 @@ const config: StorybookConfig = {
 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.
@@ -158,6 +249,34 @@ export const Primary: Story = {
 <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:
@@ -187,6 +306,16 @@ Don't run any of these yet, you are not finished with the installation.
 
 `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.
@@ -236,6 +365,43 @@ const previewConfig: StorybookPreviewConfig = {
 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
+```
+
+> **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`.
+
 ### Run it!
 
 You should be all set now.
@@ -245,3 +411,87 @@ Try running `npm run sb` to boot up storybook, leave it running as you work.
 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.
 
 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.
+
+## Configuration file (optional)
+
+The `sb-deps` CLI can be customized via a `sb-deps.config.mjs` file in your project root (alongside `package.json`). Supported formats: `.mjs`, `.js`, or `.cjs`.
+
+Use the `defineSbDepsConfig` helper from `storybook-addon-dependency-previews/config` for type safety and editor autocomplete:
+
+```js
+// sb-deps.config.mjs
+import { defineSbDepsConfig } from 'storybook-addon-dependency-previews/config'
+
+export default defineSbDepsConfig({
+	// options go here
+})
+```
+
+### `angularSelectorPrefix`
+
+_(Angular only)_ The prefix prepended to Angular component selectors when auto-scaffolding new components.
+
+**Default:** `'app-'`
+
+| Value              | Resulting selector |
+| ------------------ | ------------------ |
+| `'app-'` (default) | `app-button-atom`  |
+| `'my-'`            | `my-button-atom`   |
+| `''`               | `button-atom`      |
+
+```js
+// sb-deps.config.mjs
+import { defineSbDepsConfig } from 'storybook-addon-dependency-previews/config'
+
+export default defineSbDepsConfig({
+	angularSelectorPrefix: '', // no prefix
+})
+```
+
+### `scaffold`
+
+Override the templates used when `sb-deps` auto-scaffolds new component and story files. Each template function receives a context object with relevant variables and must return the full file content as a string.
+
+```js
+// sb-deps.config.mjs
+import { defineSbDepsConfig } from 'storybook-addon-dependency-previews/config'
+
+export default defineSbDepsConfig({
+	scaffold: {
+		react: {
+			/** Customize the generated .tsx component file */
+			component: ({ componentName, propsName }) =>
+				`export interface ${propsName} {}
+
+export function ${componentName}({}: ${propsName}) {
+	return <div>${componentName}</div>
+}
+`,
+			/** Customize the generated .stories.tsx file */
+			story: ({ componentName, propsName, title, tags, base }) => '...',
+		},
+		svelte: {
+			/** Customize the generated .svelte component file */
+			component: ({ componentName }) => '...',
+			/** Customize the generated .stories.svelte file */
+			story: ({ componentName, title, tags }) => '...',
+		},
+		angular: {
+			/** Customize the generated .component.ts file */
+			component: ({
+				componentName,
+				className,
+				selector,
+				base,
+				templateLocation,
+			}) => '...',
+			/** Customize the generated .component.html file (external templates only) */
+			componentHtml: ({ componentName }) => '...',
+			/** Customize the generated .stories.ts file */
+			story: ({ componentName, className, base, title, tags }) => '...',
+		},
+	},
+})
+```
+
+All scaffold options are optional — omit any key to keep the default template for that file type.

package/dist/addon/index.cjs

@@ -1,11 +1,17 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
 const require_addon_vitePlugin = require('./vitePlugin.cjs');
+let module$1 = require("module");
+module$1 = require_rolldown_runtime.__toESM(module$1);
 
 //#region src/addon/index.ts
+const require$1 = (0, module$1.createRequire)(require("url").pathToFileURL(__filename).href);
+const managerEntries = [require$1.resolve("../manager.mjs")];
 async function viteFinal(config) {
 	config.plugins = [...config.plugins ?? [], require_addon_vitePlugin.sbDepsVitePlugin()];
 	return config;
 }
 
 //#endregion
+exports.managerEntries = managerEntries;
 exports.viteFinal = viteFinal;
 //# sourceMappingURL=index.cjs.map

package/dist/addon/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["sbDepsVitePlugin"],"sources":["../../src/addon/index.ts"],"sourcesContent":["import { sbDepsVitePlugin } from './vitePlugin'\n\nexport async function viteFinal(config: any) {\n\tconfig.plugins = [...(config.plugins ?? []), sbDepsVitePlugin()]\n\treturn config\n}\n"],"mappings":";;;AAEA,eAAsB,UAAU,QAAa;AAC5C,QAAO,UAAU,CAAC,GAAI,OAAO,WAAW,EAAE,EAAGA,2CAAkB,CAAC;AAChE,QAAO"}
+{"version":3,"file":"index.cjs","names":["require","sbDepsVitePlugin"],"sources":["../../src/addon/index.ts"],"sourcesContent":["import { createRequire } from 'module'\nimport { sbDepsVitePlugin } from './vitePlugin'\n\nconst require = createRequire(import.meta.url)\n\nexport const managerEntries = [require.resolve('../manager.mjs')]\n\nexport async function viteFinal(config: any) {\n\tconfig.plugins = [...(config.plugins ?? []), sbDepsVitePlugin()]\n\treturn config\n}\n"],"mappings":";;;;;;AAGA,MAAMA,sFAAwC;AAE9C,MAAa,iBAAiB,CAACA,UAAQ,QAAQ,iBAAiB,CAAC;AAEjE,eAAsB,UAAU,QAAa;AAC5C,QAAO,UAAU,CAAC,GAAI,OAAO,WAAW,EAAE,EAAGC,2CAAkB,CAAC;AAChE,QAAO"}

package/dist/addon/index.d.cts

@@ -1,5 +1,6 @@
 //#region src/addon/index.d.ts
+declare const managerEntries: string[];
 declare function viteFinal(config: any): Promise<any>;
 //#endregion
-export { viteFinal };
+export { managerEntries, viteFinal };
 //# sourceMappingURL=index.d.cts.map

package/dist/addon/index.d.mts

@@ -1,5 +1,6 @@
 //#region src/addon/index.d.ts
+declare const managerEntries: string[];
 declare function viteFinal(config: any): Promise<any>;
 //#endregion
-export { viteFinal };
+export { managerEntries, viteFinal };
 //# sourceMappingURL=index.d.mts.map

package/dist/addon/index.mjs

@@ -1,11 +1,14 @@
 import { sbDepsVitePlugin } from "./vitePlugin.mjs";
+import { createRequire } from "module";
 
 //#region src/addon/index.ts
+const require = createRequire(import.meta.url);
+const managerEntries = [require.resolve("../manager.mjs")];
 async function viteFinal(config) {
 	config.plugins = [...config.plugins ?? [], sbDepsVitePlugin()];
 	return config;
 }
 
 //#endregion
-export { viteFinal };
+export { managerEntries, viteFinal };
 //# sourceMappingURL=index.mjs.map

package/dist/addon/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/addon/index.ts"],"sourcesContent":["import { sbDepsVitePlugin } from './vitePlugin'\n\nexport async function viteFinal(config: any) {\n\tconfig.plugins = [...(config.plugins ?? []), sbDepsVitePlugin()]\n\treturn config\n}\n"],"mappings":";;;AAEA,eAAsB,UAAU,QAAa;AAC5C,QAAO,UAAU,CAAC,GAAI,OAAO,WAAW,EAAE,EAAG,kBAAkB,CAAC;AAChE,QAAO"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/addon/index.ts"],"sourcesContent":["import { createRequire } from 'module'\nimport { sbDepsVitePlugin } from './vitePlugin'\n\nconst require = createRequire(import.meta.url)\n\nexport const managerEntries = [require.resolve('../manager.mjs')]\n\nexport async function viteFinal(config: any) {\n\tconfig.plugins = [...(config.plugins ?? []), sbDepsVitePlugin()]\n\treturn config\n}\n"],"mappings":";;;;AAGA,MAAM,UAAU,cAAc,OAAO,KAAK,IAAI;AAE9C,MAAa,iBAAiB,CAAC,QAAQ,QAAQ,iBAAiB,CAAC;AAEjE,eAAsB,UAAU,QAAa;AAC5C,QAAO,UAAU,CAAC,GAAI,OAAO,WAAW,EAAE,EAAG,kBAAkB,CAAC;AAChE,QAAO"}

package/dist/blocks/DependencyPreviews.d.cts

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

package/dist/blocks/DependencyPreviews.d.mts

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