Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 26 additions & 23 deletions MIGRATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,11 @@
- [From version 9.x to 10.0.0](#from-version-9x-to-1000)
- [Core Changes](#core-changes)
- [Local addons must be fully resolved](#local-addons-must-be-fully-resolved)
- [The `.storybook/main.*`-file must be valid ESM](#the-storybookmain-file-must-be-valid-esm)
- [The `.storybook/main.*` file and other presets must be valid ESM](#the-storybookmain-file-and-other-presets-must-be-valid-esm)
- [Node.js 20.19+ or 22.12+ required](#nodejs-2019-or-2212-required)
- [Require `tsconfig.json` `moduleResolution` set to value that supports `types` condition](#require-tsconfigjson-moduleresolution-set-to-value-that-supports-types-condition)
- [`core.builder` configuration must be a fully resolved path](#corebuilder-configuration-must-be-a-fully-resolved-path)
- [Removed x-only builtin tags](#removed-x-only-builtin-tags)
- [Extensionless imports in JS-based preset files are no longer supported](#extensionless-imports-in-js-based-preset-files-are-no-longer-supported)
- [From version 8.x to 9.0.0](#from-version-8x-to-900)
- [Core Changes and Removals](#core-changes-and-removals)
- [Dropped support for legacy packages](#dropped-support-for-legacy-packages)
Expand Down Expand Up @@ -512,9 +511,9 @@ export default {
};
```

#### The `.storybook/main.*`-file must be valid ESM
#### The `.storybook/main.*` file and other presets must be valid ESM

Storybook will load the `.storybook/main.*` file as an ESM file.
Storybook will load the `.storybook/main.*` file and any custom preset files as ESM files.
Thus CJS constants (`require`, `__dirname`, `__filename`) will not be defined.

You can define these constants yourself, like so:
Expand All @@ -529,7 +528,29 @@ const __dirname = dirname(__filename);
const require = createRequire(import.meta.url);
```

A `main.ts` file that's CJS is no longer supported.
A `main.ts` file that's CJS is no longer supported. The same applies to any custom preset files.

Additionally, **extensionless relative imports are no longer supported** in JavaScript-based configuration files (`.storybook/main.js`) and custom presets. All relative imports must now include explicit file extensions.

**Before (no longer works):**
```js
// .storybook/main.js
import myPreset from './my-file';
```

**After:**
```js
// .storybook/main.js
import myPreset from './my-file.js';
```

This change aligns with Node.js ESM requirements, where relative imports must specify the full file extension. This applies to `.storybook/main.js` and any custom preset files. While TypeScript-based files (`.storybook/main.ts`) will continue to work with extensionless imports for now through automatic resolution, we recommend migrating to explicit extensions for consistency and better compatibility.

**Recommended approach for all files:**
- Use `.js` for JavaScript files
- Use `.mjs` for ES modules
- Use `.ts` for TypeScript files
- Always include the extension in relative imports

#### Node.js 20.19+ or 22.12+ required

Expand Down Expand Up @@ -586,24 +607,6 @@ export const core = {
During development of Storybook [Tags](https://storybook.js.org/docs/writing-stories/tags), we created `dev-only`, `docs-only`, and `test-only` built-in tags. These tags were never documented and superseded by the currently-documented `dev`, `autodocs`, and `test` tags which provide more precise control. The outdated `x-only` tags are removed in 10.0.
During development of Storybook [Tags](https://storybook.js.org/docs/writing-stories/tags), we created `dev-only`, `docs-only`, and `test-only` built-in tags. These tags were never documented and superceded by the currently-documented `dev`, `autodocs`, and `test` tags which provide more precise control. The outdated `x-only` tags are removed in 10.0.

#### Extensionless imports in JS-based preset files are no longer supported

Storybook 10 no longer supports extensionless relative imports in JavaScript-based preset and configuration files (e.g., `.storybook/main.js`). All relative imports must now include explicit file extensions.

**Before (no longer works):**
```js
// .storybook/main.js
import myPreset from './my-file';
```

**After:**
```js
// .storybook/main.js
import myPreset from './my-file.js';
```

This change aligns with Node.js ESM requirements, where relative imports must specify the full file extension. While TypeScript-based files (`.storybook/main.ts`) will continue to work with extensionless imports for now through automatic resolution, we recommend migrating to explicit extensions for consistency and better compatibility.

## From version 8.x to 9.0.0

### Core Changes and Removals
Expand Down
2 changes: 1 addition & 1 deletion docs/releases/migration-guide.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ This guide is meant to help you **upgrade from Storybook 9.x to 10** successfull

The rest of this guide will help you upgrade successfully, either automatically or manually. But first, there are some [breaking changes][full-migration-notes] in Storybook 10. Here are the most impactful changes you should know about before you go further:

* [Main configuration (`.storybook/main.js|ts`) must be valid ESM](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#the-storybookmain-file-must-be-valid-esm)
* [Main configuration (`.storybook/main.js|ts`) and other presets must be valid ESM](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#the-storybookmain-file-and-other-presets-must-be-valid-esm)
* Ecosystem updates
* [Node 20.19+ or 22.12+ is now required](https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#nodejs-2019-or-2212-required)

Expand Down
Loading