Eslint-plugin: Handle JSON5 format #31336

yatishgoel · 2025-05-01T20:54:53Z

What I did

The eslintPlugin automigration was previously using JSON.parse to read .eslintrc.json files. This caused crashes when users had comments in their configuration (which is valid JSON5 syntax often used in ESLint v8 and earlier).

Following maintainer feedback aiming for comment preservation, this PR fixes the issue by:

Replacing JSON.parse with comment-json.parse() within the configureEslintPlugin function. This correctly handles .eslintrc.json files containing comments or other JSON5 features without errors.
Using comment-json.stringify() to write the modified configuration back to the file.
Adding the comment-json package as a dependency to @storybook/cli.
Updating the relevant unit test (should correctly parse, configure, and preserve comments in JSON5 .eslintrc.json) to verify the behavior.

Note on Comment Preservation: Testing revealed that while comment-json successfully preserves comments located outside of arrays or attached to unmodified object properties, it does not consistently preserve comments located inside an array (like extends) when that array is modified (e.g., by adding plugin:storybook/recommended). The test assertions have been updated to reflect this observed behavior.

This resolves the SyntaxError reported in #31316, allows the migration to proceed smoothly for users with JSON5-formatted ESLint configurations, and preserves the majority of user comments in the configuration file.

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

stories
unit tests
integration tests
end-to-end tests

Manual testing

This section is mandatory for all contributions. If you believe no manual test is necessary, please state so explicitly. Thanks!

Manual testing can be done by running the upgrade command on a project that uses an .eslintrc.json file containing comments:

Set up a sample project using Storybook 8 (or earlier) with an .eslintrc.json file that includes comments (similar to the one in issue [Bug]: Storybook 9 - eslintPlugin automigration crashes on config files with JSON5 format #31316, including comments inside the extends array if possible).
Run npx storybook@latest upgrade using this branch.
Verify that the upgrade process completes without the SyntaxError related to parsing the ESLint config.
Verify that the eslint-plugin-storybook is correctly configured in the extends array in .eslintrc.json.
Verify that comments outside the extends array were preserved, while comments inside it might have been removed.

Documentation

Add or update documentation reflecting your changes
If you are deprecating/removing a feature, make sure to update
MIGRATION.MD

Checklist for Maintainers

When this PR is ready for testing, make sure to add ci:normal, ci:merged or ci:daily GH label to it to run a specific set of sandboxes. The particular set of sandboxes can be found in code/lib/cli-storybook/src/sandbox-templates.ts
Make sure this PR contains one of the labels below:
Available labels
- bug: Internal changes that fixes incorrect behavior.
- maintenance: User-facing maintenance tasks.
- dependencies: Upgrading (sometimes downgrading) dependencies.
- build: Internal-facing build tooling & test updates. Will not show up in release changelog.
- cleanup: Minor cleanup style change. Will not show up in release changelog.
- documentation: Documentation only changes. Will not show up in release changelog.
- feature request: Introducing a new feature.
- BREAKING CHANGE: Changes that break compatibility in some way with current major version.
- other: Changes that don't fit in the above categories.

🦋 Canary release

This PR does not have a canary release associated. You can request a canary release of this pull request by mentioning the @storybookjs/core team here.

core team members can create a canary release here or locally with gh workflow run --repo storybookjs/storybook canary-release-pr.yml --field pr=<PR_NUMBER>

greptile-apps

_{3 file(s) reviewed, 1 comment(s)}
_{Edit PR Review Bot Settings | Greptile}

greptile-apps · 2025-05-01T21:00:32Z

code/core/src/cli/eslintPlugin.ts

@@ -218,7 +220,6 @@ export async function configureEslintPlugin({

      eslintConfig.extends = [...existingExtends, 'plugin:storybook/recommended'] as string[];

-      const eslintFileContents = await readFile(eslintConfigFile, { encoding: 'utf8' });
      const spaces = detectIndent(eslintFileContents).amount || 2;
      await writeFile(eslintConfigFile, JSON.stringify(eslintConfig, undefined, spaces));


logic: Using JSON.stringify will strip out any comments and formatting from the original file. Consider using json5.stringify to preserve JSON5 features.

Suggested change

await writeFile(eslintConfigFile, JSON.stringify(eslintConfig, undefined, spaces));

await writeFile(eslintConfigFile, json5.stringify(eslintConfig, undefined, spaces));

…intrc.json

valentinpalkovic · 2025-05-05T13:20:44Z

Hi @yatishgoel,

Thank you for your contribution.

I am wondering, whether we can preserve comments inside of a json5 configuration by transforming comments into namespaced key-value pairs and when stringifying it back to transform it back to a comment. WDYT?

yatishgoel · 2025-05-05T14:33:23Z

Hi @yatishgoel,

Thank you for your contribution.

I am wondering, whether we can preserve comments inside of a json5 configuration by transforming comments into namespaced key-value pairs and when stringifying it back to transform it back to a comment. WDYT?

Hi @valentinpalkovic, thanks for the suggestion! If I’m understanding correctly, you’re proposing that we turn each comment into a temporary, namespaced property on the config object and then convert those properties back into comments when stringifying. That would certainly work to keep comments in place, but it does add a fair bit of custom parsing and post-processing logic.

Would you be open to using a lightweight library like comment-json instead? It handles full round-trip comment support—preserving whitespace, comment placement, and formatting—without the need for us to write and maintain our own encode/decode layer. Let me know what you think!

valentinpalkovic · 2025-05-05T14:35:36Z

Hi @yatishgoel,
Thank you for your contribution.
I am wondering, whether we can preserve comments inside of a json5 configuration by transforming comments into namespaced key-value pairs and when stringifying it back to transform it back to a comment. WDYT?

Hi @valentinpalkovic, thanks for the suggestion! If I’m understanding correctly, you’re proposing that we turn each comment into a temporary, namespaced property on the config object and then convert those properties back into comments when stringifying. That would certainly work to keep comments in place, but it does add a fair bit of custom parsing and post-processing logic.

Would you be open to using a lightweight library like comment-json instead? It handles full round-trip comment support—preserving whitespace, comment placement, and formatting—without the need for us to write and maintain our own encode/decode layer. Let me know what you think!

Exactly! Using comment-json may indeed be what we are searching for. Are you willing to integrate it into your PR and write some additional tests?

yatishgoel · 2025-05-05T14:58:20Z

Hi @yatishgoel,
Thank you for your contribution.
I am wondering, whether we can preserve comments inside of a json5 configuration by transforming comments into namespaced key-value pairs and when stringifying it back to transform it back to a comment. WDYT?

Hi @valentinpalkovic, thanks for the suggestion! If I’m understanding correctly, you’re proposing that we turn each comment into a temporary, namespaced property on the config object and then convert those properties back into comments when stringifying. That would certainly work to keep comments in place, but it does add a fair bit of custom parsing and post-processing logic.
Would you be open to using a lightweight library like comment-json instead? It handles full round-trip comment support—preserving whitespace, comment placement, and formatting—without the need for us to write and maintain our own encode/decode layer. Let me know what you think!

Exactly! Using comment-json may indeed be what we are searching for. Are you willing to integrate it into your PR and write some additional tests?

Sure

…ments

yatishgoel · 2025-05-05T22:30:11Z

Hi @valentinpalkovic,

I've updated the PR to implement that approach:

Added comment-json as a dependency.
Updated configureEslintPlugin to use commentJson.parse() (correctly configured now to preserve comments) and commentJson.stringify().
Updated the unit tests and snapshots to reflect the new behavior.

During testing, I found that while comment-json successfully preserves comments outside of modified arrays (like top-level comments or those attached to other properties like rules), it unfortunately did not preserve comments located inside the extends array when that array was modified by adding the new recommendation. I tried different array modification methods (.push() vs. spread operator), but the result was the same regarding inner-array comments.

The current solution now correctly fixes the original parsing crash and preserves most comments, which is an improvement over stripping them all.

I've updated the PR description to detail these findings accurately.

Could you please take another look when you have a chance?

Thanks!

valentinpalkovic · 2025-05-06T07:00:25Z

Thank you! Could you push an updated version of the yarn.lock file please?

nx-cloud · 2025-05-06T07:46:49Z

View your CI Pipeline Execution ↗ for commit d50852a.

Command	Status	Duration	Result
`nx run-many -t build --parallel=3`	✅ Succeeded	1m 44s	View ↗

☁️ Nx Cloud last updated this comment at 2025-05-06 07:46:49 UTC

ndelangen · 2025-05-06T08:25:03Z

@yannbf want to review this? please

fix(cli): handle JSON5 format in eslintrc.json (storybookjs#31316)

5ca0b19

greptile-apps bot reviewed May 1, 2025

View reviewed changes

fix(cli): update eslint configuration to use JSON5.stringify for .esl…

d863364

…intrc.json

valentinpalkovic assigned yannbf May 5, 2025

valentinpalkovic added bug ci:normal labels May 5, 2025

fix(cli): Handle JSON5 configs in ESLint migration, preserve most com…

f88ef57

…ments

Merge branch 'next' into fix/eslint-json5-parse-31316

24a79fd

ndelangen added 2 commits May 6, 2025 09:41

Merge branch 'next' into pr/yatishgoel/31336

7d61eb6

chore(deps): Update yarn.lock to include new dependencies and versions

d50852a

ndelangen assigned ndelangen and unassigned yannbf May 6, 2025

ndelangen added the eslint-plugin label May 6, 2025

ndelangen changed the title ~~fix(cli): Handle JSON5 format in eslintrc.json during migration~~ Eslint-plugin: Handle JSON5 format May 6, 2025

ndelangen assigned yannbf and unassigned ndelangen May 6, 2025

yannbf approved these changes May 6, 2025

View reviewed changes

yannbf merged commit 69bbc76 into storybookjs:next May 6, 2025
55 of 57 checks passed

github-actions bot mentioned this pull request May 6, 2025

Release: Prerelease 9.0.0-beta.11 #31377

Merged

22 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Eslint-plugin: Handle JSON5 format #31336

Eslint-plugin: Handle JSON5 format #31336

Uh oh!

yatishgoel commented May 1, 2025 •

edited

Loading

Uh oh!

greptile-apps bot left a comment

Uh oh!

greptile-apps bot May 1, 2025

Uh oh!

valentinpalkovic commented May 5, 2025

Uh oh!

yatishgoel commented May 5, 2025

Uh oh!

valentinpalkovic commented May 5, 2025 •

edited

Loading

Uh oh!

yatishgoel commented May 5, 2025

Uh oh!

yatishgoel commented May 5, 2025

Uh oh!

valentinpalkovic commented May 6, 2025

Uh oh!

nx-cloud bot commented May 6, 2025

Uh oh!

ndelangen commented May 6, 2025

Uh oh!

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

	await writeFile(eslintConfigFile, JSON.stringify(eslintConfig, undefined, spaces));
	await writeFile(eslintConfigFile, json5.stringify(eslintConfig, undefined, spaces));

Uh oh!

Eslint-plugin: Handle JSON5 format #31336

Eslint-plugin: Handle JSON5 format #31336

Uh oh!

Conversation

yatishgoel commented May 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What I did

Checklist for Contributors

Testing

The changes in this PR are covered in the following automated tests:

Manual testing

Documentation

Checklist for Maintainers

🦋 Canary release

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

greptile-apps bot May 1, 2025

Choose a reason for hiding this comment

Uh oh!

valentinpalkovic commented May 5, 2025

Uh oh!

yatishgoel commented May 5, 2025

Uh oh!

valentinpalkovic commented May 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yatishgoel commented May 5, 2025

Uh oh!

yatishgoel commented May 5, 2025

Uh oh!

valentinpalkovic commented May 6, 2025

Uh oh!

nx-cloud bot commented May 6, 2025

Uh oh!

ndelangen commented May 6, 2025

Uh oh!

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

yatishgoel commented May 1, 2025 •

edited

Loading

valentinpalkovic commented May 5, 2025 •

edited

Loading