From 8c5fe63074196d9a1e5e4beacaf15e46765572a2 Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 24 Jan 2023 00:14:46 +0800 Subject: [PATCH 1/8] Addon-docs: Add legacy transitional support for MDX1 --- code/addons/docs/package.json | 6 ++++++ code/addons/docs/src/preset.ts | 13 +++++++++++-- code/lib/core-server/src/typings.d.ts | 1 + code/lib/preview-api/src/typings.d.ts | 1 + code/lib/types/src/modules/core-common.ts | 5 +++++ code/yarn.lock | 4 ++++ 6 files changed, 28 insertions(+), 2 deletions(-) diff --git a/code/addons/docs/package.json b/code/addons/docs/package.json index 023f569c8480..e6a8ce28b9ac 100644 --- a/code/addons/docs/package.json +++ b/code/addons/docs/package.json @@ -126,9 +126,15 @@ "typescript": "~4.9.3" }, "peerDependencies": { + "@storybook/mdx1-csf": "0.0.5--canary.19.89e7fd1.0", "react": "^16.8.0 || ^17.0.0 || ^18.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0" }, + "peerDependenciesMeta": { + "@storybook/mdx1-csf": { + "optional": true + } + }, "publishConfig": { "access": "public" }, diff --git a/code/addons/docs/src/preset.ts b/code/addons/docs/src/preset.ts index 3b7ac4a87a7a..397f0172569e 100644 --- a/code/addons/docs/src/preset.ts +++ b/code/addons/docs/src/preset.ts @@ -6,7 +6,9 @@ import { dedent } from 'ts-dedent'; import type { IndexerOptions, StoryIndexer, DocsOptions, Options } from '@storybook/types'; import type { CsfPluginOptions } from '@storybook/csf-plugin'; import type { JSXOptions } from '@storybook/mdx2-csf'; +import { global } from '@storybook/global'; import { loadCsf } from '@storybook/csf-tools'; +import { logger } from '@storybook/node-logger'; import { ensureReactPeerDeps } from './ensure-react-peer-deps'; async function webpack( @@ -73,7 +75,12 @@ async function webpack( `); } - const mdxLoader = require.resolve('@storybook/mdx2-csf/loader'); + const mdxVersion = global.FEATURES?.legacyMdx1 ? 'MDX1' : 'MDX2'; + logger.info(`Addon-docs: using ${mdxVersion}`); + + const mdxLoader = global.FEATURES?.legacyMdx1 + ? require.resolve('@storybook/mdx1-csf/loader') + : require.resolve('@storybook/mdx2-csf/loader'); let rules = module.rules || []; if (transcludeMarkdown) { @@ -135,7 +142,9 @@ async function webpack( const storyIndexers = (indexers: StoryIndexer[] | null) => { const mdxIndexer = async (fileName: string, opts: IndexerOptions) => { let code = (await fs.readFile(fileName, 'utf-8')).toString(); - const { compile } = await import('@storybook/mdx2-csf'); + const { compile } = global.FEATURES?.legacyMdx1 + ? await import('@storybook/mdx1-csf') + : await import('@storybook/mdx2-csf'); code = await compile(code, {}); return loadCsf(code, { ...opts, fileName }).parse(); }; diff --git a/code/lib/core-server/src/typings.d.ts b/code/lib/core-server/src/typings.d.ts index b51124a22ab7..2596c5e8940c 100644 --- a/code/lib/core-server/src/typings.d.ts +++ b/code/lib/core-server/src/typings.d.ts @@ -15,5 +15,6 @@ declare var FEATURES: interactionsDebugger?: boolean; breakingChangesV7?: boolean; argTypeTargetsV7?: boolean; + legacyMdx1?: boolean; } | undefined; diff --git a/code/lib/preview-api/src/typings.d.ts b/code/lib/preview-api/src/typings.d.ts index 195827936c63..c55173e5bb96 100644 --- a/code/lib/preview-api/src/typings.d.ts +++ b/code/lib/preview-api/src/typings.d.ts @@ -13,6 +13,7 @@ declare var FEATURES: interactionsDebugger?: boolean; breakingChangesV7?: boolean; argTypeTargetsV7?: boolean; + legacyMdx1?: boolean; } | undefined; diff --git a/code/lib/types/src/modules/core-common.ts b/code/lib/types/src/modules/core-common.ts index d08b0282ce82..7089f5c51951 100644 --- a/code/lib/types/src/modules/core-common.ts +++ b/code/lib/types/src/modules/core-common.ts @@ -317,6 +317,11 @@ export interface StorybookConfig { * Will be removed in 7.0. */ warnOnLegacyHierarchySeparator?: boolean; + + /** + * Use legacy MDX1, to help smooth migration to 7.0 + */ + legacyMdx1?: boolean; }; /** diff --git a/code/yarn.lock b/code/yarn.lock index 217393666427..43d3414345f6 100644 --- a/code/yarn.lock +++ b/code/yarn.lock @@ -5253,8 +5253,12 @@ __metadata: ts-dedent: ^2.0.0 typescript: ~4.9.3 peerDependencies: + "@storybook/mdx1-csf": 0.0.5--canary.19.e834b59.0 react: ^16.8.0 || ^17.0.0 || ^18.0.0 react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 + peerDependenciesMeta: + "@storybook/mdx1-csf": + optional: true languageName: unknown linkType: soft From df8c83cf0ee7cda74f14ab7264964d3ea807bb9e Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 24 Jan 2023 00:18:51 +0800 Subject: [PATCH 2/8] Update yarn.lock --- code/yarn.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/yarn.lock b/code/yarn.lock index 43d3414345f6..58aa351f2533 100644 --- a/code/yarn.lock +++ b/code/yarn.lock @@ -5253,7 +5253,7 @@ __metadata: ts-dedent: ^2.0.0 typescript: ~4.9.3 peerDependencies: - "@storybook/mdx1-csf": 0.0.5--canary.19.e834b59.0 + "@storybook/mdx1-csf": 0.0.5--canary.19.89e7fd1.0 react: ^16.8.0 || ^17.0.0 || ^18.0.0 react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 peerDependenciesMeta: From 1582d24128827721169726ca25328cf9699c14f4 Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 24 Jan 2023 10:47:04 +0800 Subject: [PATCH 3/8] MIGRATION: Added legacyMdx1 instructions --- MIGRATION.md | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index e71d9753d15c..a23f66082098 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -47,6 +47,7 @@ - [Configuring the Docs Container](#configuring-the-docs-container) - [External Docs](#external-docs) - [MDX2 upgrade](#mdx2-upgrade) + - [Legacy MDX1 support](#legacy-mdx1-support) - [Default docs styles will leak into non-story user components](#default-docs-styles-will-leak-into-non-story-user-components) - [Explicit `` elements are no longer syntax highlighted](#explicit-code-elements-are-no-longer-syntax-highlighted) - [Dropped source loader / storiesOf static snippets](#dropped-source-loader--storiesof-static-snippets) @@ -902,11 +903,33 @@ export default function App({ Component, pageProps }) { Storybook 7 Docs uses MDXv2 instead of MDXv1. This means an improved syntax, support for inline JS expression, and improved performance among [other benefits](https://mdxjs.com/blog/v2/). -If you use `.stories.mdx` files in your project, you may need to edit them since MDX2 contains [breaking changes](https://mdxjs.com/migrating/v2/#update-mdx-files). +If you use `.stories.mdx` files in your project, you'll probably need to edit them since MDX2 contains [breaking changes](https://mdxjs.com/migrating/v2/#update-mdx-files). In general, MDX2 is stricter and more structured than MDX1. -We will update this section with specific pointers based on user feedback during the prerelease period and probably add an codemod to help streamline the upgrade before final 7.0 release. +We've provided an automigration, `mdx1to2` that makes a few of these changes automatically. For example, `mdx1to2` automatically converts MDX1-style HTML comments into MDX2-style JSX comments to save you time. -As part of the upgrade we deleted the codemod `mdx-to-csf` and will be replacing it with a more sophisticated version prior to release. +Unfortunately, the set of changes from MDX1 to MDX2 is vast, and many changes are subtle, so the bulk of the migration will be manual. You can use the [MDX Playground](https://mdxjs.com/playground/) to try out snippets interactively. + +#### Legacy MDX1 support + +If you get stuck with the [MDX2 upgrade](#mdx2-upgrade), we also provide opt-in legacy MDX1 support. This is intended as a temporary solution while you upgrade your Storybook and will be discontinued in Storybook 8.0. The MDX1 library is no longer maintained and installing it results in npm audit security warnings. + +To process your `.stories.mdx` files with MDX1, first install the `@storybook/mdx1-csf` package in your project: + +``` +yarn add -D @storybook/mdx1-csf@next +``` + +Then enable the `legacyMdx1` feature flag in your `.storybook/main.js` file: + +```js +export default { + features: { + legacyMdx1: true, + } +} +``` + +This only affects `.(stories|story).mdx` files. Notably, if you want to use Storybook 7's "pure" `.mdx` format, you'll need to use MDX2 for that. #### Default docs styles will leak into non-story user components From e0b93d1402eae4d12a2804bbb286ebd62a28cf4a Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 24 Jan 2023 10:49:21 +0800 Subject: [PATCH 4/8] Update MIGRATION.md --- MIGRATION.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index a23f66082098..91069d4ed2b9 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -911,7 +911,7 @@ Unfortunately, the set of changes from MDX1 to MDX2 is vast, and many changes ar #### Legacy MDX1 support -If you get stuck with the [MDX2 upgrade](#mdx2-upgrade), we also provide opt-in legacy MDX1 support. This is intended as a temporary solution while you upgrade your Storybook and will be discontinued in Storybook 8.0. The MDX1 library is no longer maintained and installing it results in npm audit security warnings. +If you get stuck with the [MDX2 upgrade](#mdx2-upgrade), we also provide opt-in legacy MDX1 support. This is intended as a temporary solution while you upgrade your Storybook; MDX1 will be discontinued in Storybook 8.0. The MDX1 library is no longer maintained and installing it results in `npm audit` security warnings. To process your `.stories.mdx` files with MDX1, first install the `@storybook/mdx1-csf` package in your project: From 1e13541cdf94338f542f41252004f6319743bbaa Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 24 Jan 2023 10:51:09 +0800 Subject: [PATCH 5/8] Update MIGRATION.md --- MIGRATION.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/MIGRATION.md b/MIGRATION.md index 91069d4ed2b9..86ef85ce8a91 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -929,7 +929,9 @@ export default { } ``` -This only affects `.(stories|story).mdx` files. Notably, if you want to use Storybook 7's "pure" `.mdx` format, you'll need to use MDX2 for that. +NOTE: This only affects `.(stories|story).mdx` files. Notably, if you want to use Storybook 7's "pure" `.mdx` format, you'll need to use MDX2 for that. + +NOTE: Legacy MDX1 support is only for Webpack projects. There is currently no legacy support for Vite. #### Default docs styles will leak into non-story user components From 2de380835b38da1b9a1960e748e9485e031dd95a Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 24 Jan 2023 15:31:06 +0800 Subject: [PATCH 6/8] Fix typings --- code/addons/docs/src/typings.d.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/code/addons/docs/src/typings.d.ts b/code/addons/docs/src/typings.d.ts index 18881b5e33b7..73d1afc62a39 100644 --- a/code/addons/docs/src/typings.d.ts +++ b/code/addons/docs/src/typings.d.ts @@ -4,6 +4,7 @@ declare module 'remark-external-links'; declare module 'babel-plugin-react-docgen'; declare module 'acorn-jsx'; declare module 'vue/dist/vue'; +declare module '@storybook/mdx1-csf'; declare module 'sveltedoc-parser' { export function parse(options: any): Promise; From c2512812745ed30673cbf3420c95d2974707001e Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Tue, 24 Jan 2023 15:39:06 +0800 Subject: [PATCH 7/8] Fix FEATURES types in addon-docs --- code/addons/docs/src/typings.d.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/code/addons/docs/src/typings.d.ts b/code/addons/docs/src/typings.d.ts index 73d1afc62a39..957b4b62a945 100644 --- a/code/addons/docs/src/typings.d.ts +++ b/code/addons/docs/src/typings.d.ts @@ -10,4 +10,14 @@ declare module 'sveltedoc-parser' { export function parse(options: any): Promise; } +declare var FEATURES: + | { + storyStoreV7?: boolean; + interactionsDebugger?: boolean; + breakingChangesV7?: boolean; + argTypeTargetsV7?: boolean; + legacyMdx1?: boolean; + } + | undefined; + declare var LOGLEVEL: 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent' | undefined; From dd01de3e9ff2014f2bf80d9d69676e1f67a2bca8 Mon Sep 17 00:00:00 2001 From: Michael Shilman Date: Thu, 26 Jan 2023 00:37:13 +0800 Subject: [PATCH 8/8] Addon-docs: Upgrade mdx1-csf peer dep --- code/addons/docs/package.json | 2 +- code/yarn.lock | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/code/addons/docs/package.json b/code/addons/docs/package.json index 7ec40825a09c..3a62666023c3 100644 --- a/code/addons/docs/package.json +++ b/code/addons/docs/package.json @@ -126,7 +126,7 @@ "typescript": "~4.9.3" }, "peerDependencies": { - "@storybook/mdx1-csf": "0.0.5--canary.19.89e7fd1.0", + "@storybook/mdx1-csf": ">=1.0.0-0", "react": "^16.8.0 || ^17.0.0 || ^18.0.0", "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0" }, diff --git a/code/yarn.lock b/code/yarn.lock index 9d22f898ae3e..298aa6562bbd 100644 --- a/code/yarn.lock +++ b/code/yarn.lock @@ -5206,7 +5206,7 @@ __metadata: ts-dedent: ^2.0.0 typescript: ~4.9.3 peerDependencies: - "@storybook/mdx1-csf": 0.0.5--canary.19.89e7fd1.0 + "@storybook/mdx1-csf": ">=1.0.0-0" react: ^16.8.0 || ^17.0.0 || ^18.0.0 react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 peerDependenciesMeta: