utility.assert is not a function

[brvnonascimento]

Describe the bug
Storybook fails to build throwing the following errors:

TypeError: utility.assert is not a function

Error loading story index:

Error: Cannot parse JSDoc tags.

System

System:
OS: macOS 12.0.1
CPU: (8) x64 Apple M1
Binaries:
Node: 14.17.5 - ~/.nvm/versions/node/v14.17.5/bin/node
Yarn: 1.22.17 - /usr/local/bin/yarn
npm: 6.14.14 - ~/.nvm/versions/node/v14.17.5/bin/npm
Browsers:
Firefox: 96.0.3
Safari: 15.1
npmPackages:
@storybook/addon-actions: 6.4.18 => 6.4.18
@storybook/addon-docs: 6.4.18 => 6.4.18
@storybook/addon-essentials: 6.4.18 => 6.4.18
@storybook/addon-links: 6.4.18 => 6.4.18
@storybook/addons: ^6.4.18 => 6.4.18
@storybook/builder-webpack5: 6.4.18 => 6.4.18
@storybook/manager-webpack5: 6.4.18 => 6.4.18
@storybook/react: 6.4.18 => 6.4.18
@storybook/testing-react: ^1.2.3 => 1.2.3

[brvnonascimento]

I had to eject from @storybook/addon-essentials and setup its addons manually. The problem is indeed with @storybook/addon-docs, which when added throws the error "Cannot parse JSDoc tags".

[kafkas]

Having the exact same issue...

[kafkas]

I ended up disabling the @storybook/addon-docs to get rid of the error. This can be done by replacing the '@storybook/addon-essentials' in the main config with the following:

   ...
    {
      name: '@storybook/addon-essentials',
      options: {
        docs: false,
      },
    },

This isn't a fix or workaround. It's just a way to get rid of the error by disabling the add-on as described in docs.

[evolvingriley]

Same issue, thanks for the fix!

[aaronadamsCA]

The workaround isn't great, of course; this means TypeScript projects lose all automatic argType inference.

The root cause seem to be a bug in Doctrine, which reached end of life and stopped releasing in 2018.

[dontsave]

we found this issue happened when upgrading NextJs in our monorepo to the latest 12.1.x version. @shilman the workaround of disabling docs is not a real workaround, as docs is a core feature of storybook. we are now either faced with the choice of not being able to upgrade Next or not have documentation of our components

[dontsave]

update: the Next upgrade removed assert as a deep dependency. our fix for this issue is to add it back as a dev dependency on the root workspace. i would guess this is an implicit dependency of addon-docs, which could be made explicit as a fix

[aaronadamsCA]

This is a great catch by @dontsave, and I can confirm it resolves our issue as well. Transitive dependency doctrine seems to assume it's running in a browser environment; my best guess is this worked fine with Webpack 4 since it auto-polyfilled assert.

[aaronadamsCA]

I think #17978 is possibly related, too.

[jonesmac]

alternatively, you can add a fallback to the webpackFinal config function and provide a polyfill.

In this case, you can add the commonjs-assert package.

yarn add --dev commonjs-assert

Then add a property to the webpack final config in main.js

const path = require('path');
const toPath = (filePath) => path.join(process.cwd(), filePath);
...
module.exports = {
 webpackFinal: async (config) => ({
    ...config,
    resolve: {
      ...config.resolve,
     // can likely be removed in storybook > 6.4 see - https://github.com/storybookjs/storybook/issues/17458
     fallback: {
       ...config.resolve.fallback,
      'assert': toPath('commonjs-assert')
     }
    },
 })
}

[guhyeon]

@jonesmac, there are no commonjs-assert now,

error An unexpected error occurred: "https://registry.yarnpkg.com/commonjs-assert: Not found".

[jonesmac]

@jonesmac, there are no commonjs-assert now,

error An unexpected error occurred: "https://registry.yarnpkg.com/commonjs-assert: Not found".

If you look at the read me for that project's repo, you have to install it with yarn install assert

[ChrisSargent]

alternatively, you can add a fallback to the webpackFinal config function and provide a polyfill.

In this case, you can add the commonjs-assert package.

yarn add --dev commonjs-assert

Then add a property to the webpack final config in main.js

const path = require('path');
const toPath = (filePath) => path.join(process.cwd(), filePath);
...
module.exports = {
 webpackFinal: async (config) => ({
    ...config,
    resolve: {
      ...config.resolve,
     // can likely be removed in storybook > 6.4 see - https://github.com/storybookjs/storybook/issues/17458
     fallback: {
       ...config.resolve.fallback,
      'assert': toPath('commonjs-assert')
     }
    },
 })
}

For anyone else seeing this issue, you can also use

assert: require.resolve('assert'),

[milhlhat]

For anyone else seeing this issue, you can also use

 assert: require.resolve('assert'),

Thanks, module commonjs-assert is not exits. use yarn add -D assert instead

[tmeasday]

Has anyone tried this in 6.5? I suspect it was fixed by this: #17375? (specifically this commit: 0bae768)

[csantos1113]

For what is worth, I had the same issue using @storybook/* version 6.5.x, but I also had this in my package.json

  "resolutions": {
    "webpack": "5.74.0"
  },

Why I have that resolution?
No major reason, really I just got tired of webpack4 and all its dependencies existing in my node_modules even though I opted-in to using webpack5 long ago

core: {
  builder: {
    name: 'webpack5'
  }
}

Why that resolution "breaks" my storybook?
Because assert got installed as a transient dependency of webpack4

$ yarn why assert
└─ node-libs-browser@npm:2.2.1
   └─ assert@npm:1.5.0

$ yarn why node-libs-browser
└─ webpack@npm:4.46.0
   └─ node-libs-browser@npm:2.2.1

$ yarn why webpack
├─ @storybook/builder-webpack4@npm:6.5.10 [3b1e7]
│  └─ webpack@npm:4.46.0 [9715f] (via npm:4 [9715f])
├─ @storybook/core-server@npm:6.5.10 [c6ef4]
│  └─ webpack@npm:4.46.0 [9715f] (via npm:4 [9715f])
│
├─ @storybook/manager-webpack4@npm:6.5.10
│  └─ webpack@npm:4.46.0 (via npm:4)
... and many more storybook packages

so, when I forced webpack5, these webpack4 dependencies were deleted

How did I fix it?

yarn add -D assert

[tmeasday]

@csantos1113 thats a bit puzzling though. Did you have some kind of override of the webpack config ala @ChrisSargent's comment?

Because reading the source code, (in 6.5) we alias assert to browser-assert (obv. a different package to assert), which is a dependency of @storybook/builder-webpack5.

Perhaps if you run storybook with --debug-webpack you can take a look at what the resolve.fallback.assert is set to in the preview.

No major reason, really I just got tired of webpack4 and all its dependencies existing in my node_modules even though I opted-in to using webpack5 long ago

Fair enough, this issue is well and truly resolved in SB7.

[csantos1113]

Hey @tmeasday thanks for the quick response.

Fair enough, this issue is well and truly resolved in SB7.

Looking forward to using SB7 💪

---

Did you have some kind of override of the webpack config

Yes I do, I have this in my .storybook/main.js

webpackFinal: (config) => {
  // Allow named imports from CJS into ESM modules
  config.module.rules.push({
    type: 'javascript/auto',
    test: /\.mjs$/,
    use: []
  });
  config.resolve = {
    ...config.resolve,
    plugins: [
      ...(config.resolve.plugins || []),
      new TsconfigPathsPlugin({ extensions: config.resolve.extensions })
    ]
  };
  return config;
}

but worth to mention: removing any of that has no effect on the assert issue.

---

Perhaps if you run storybook with --debug-webpack you can take a look at what the resolve.fallback.assert is set to in the preview.

I ran it but I see the same fallback object (with and without "resolutions": { "webpack": "5.74.0" } in my package.json)

    fallback: {
      path: '/Users/cesar.santos/my-repo/node_modules/path-browserify/index.js',
      assert: false,
      crypto: false
    },

---

Because reading the source code, (in 6.5) we alias assert to browser-assert (obv. a different package to assert), which is a dependency of @storybook/builder-webpack5.

I'm not experienced with SB source code, but I notice that:
storybook/lib/builder-webpack5/src/preview/iframe-webpack.config.ts:249 has

fallback: {
  path: require.resolve('path-browserify'),
  assert: require.resolve('browser-assert'),
},

and storybook/lib/builder-webpack5/src/preview/base-webpack.config.ts:88 has

fallback: {
  ...storybookBaseConfig.resolve?.fallback,
  crypto: false,
  assert: false,
},

Shouldn't perhaps base-webpack.config.ts has the same assert fallback?

[csantos1113]

this also fixed my issue (without having to install assert manually).. @tmeasday - So perhaps base-webpack.config.ts do need the same assert fallback?

===================================================================
diff --git a/.storybook/main.js b/.storybook/main.js
--- a/.storybook/main.js	(revision 7050f86b92bd1e869fd6ced97210edfb680b2aa5)
+++ b/.storybook/main.js	(date 1664977245522)
@@ -65,7 +65,11 @@
       plugins: [
         ...(config.resolve.plugins || []),
         new TsconfigPathsPlugin({ extensions: config.resolve.extensions })
-      ]
+      ],
+      fallback: {
+        ...config.resolve.fallback,
+        assert: require.resolve('browser-assert')
+      }
     };
     return config;
   }
===================================================================
diff --git a/package.json b/package.json
--- a/package.json	(revision 7050f86b92bd1e869fd6ced97210edfb680b2aa5)
+++ b/package.json	(date 1664977254003)
@@ -40,7 +40,6 @@
     "@types/node": "18.8.0",
     "@types/rimraf": "3.0.2",
     "@types/testing-library__jest-dom": "5.14.5",
-    "assert": "2.0.0",
     "babel-loader": "8.2.5",
     "commitizen": "4.2.5",
     "cz-conventional-changelog": "3.3.0",

[tmeasday]

Funny you mention that @csantos1113 #19341 (comment)

So this issue will be fixed in 7.0.

@shilman / @ndelangen should we patch this back to 6.5? (#19358)

[quantizor]

FWIW I just yarn add --dev assert and removed the overrides in webpackFinal and the error went away :/

[jamsinclair]

Updating all storybook modules to v6.5.16 seemed to resolve this issue for our application. I assume the fix was backported @tmeasday? 🤓

[tmeasday]

Hmm, I don't think so @jamsinclair:

storybook/lib/builder-webpack5/src/preview/base-webpack.config.ts

Lines 89 to 91 in a56e6bd

	...storybookBaseConfig.resolve?.fallback,
	crypto: false,
	assert: false,

But I am glad to hear the problem is fixed. Which builder (wp4 vs wp5?)

[tmeasday]

In any case going to close this as it is fixed in 7.0. Please try upgrading if you are still seeing problems!

[jamsinclair]

Ah interesting! @tmeasday It was with WP5 that also might have been the reason. I guess we'll look into 7.0 if it happens again.

Thanks for the update! 🙇

[jonesmac]

I actually just pulled the latest for Storybook (6.5.16) and it still happens for me. I had to modify the webpack(v5) config and install browser-assert for it to work as it looks like the Doctrine lib is still being used.

[yodakaEngineer]

I used yarn v3 and got the same error(Error: Cannot parse JSDoc tags.).
I changed it to yarn v1 and the error disappeared.

[ndelangen]

@shilman do we have confirmation this is an issue in 7.0?

[tmeasday]

A user with a custom webpack config (that overrode resolve.fallback.assert) ran into this with 7.0. But I guess ultimately that wasn't an issue with SB. We could consider catching + rethrowing a more helpful error if this is reported a lot.

[TrySound]

@ndelangen I get similar issue with react-vite framework after upgrade to v7. All worked well in 6.5.

[ndelangen]

@TrySound Can you supply a reproduction please?
Do you have a custom vite config?

[TrySound]

No custom config except viteFinal with export conditions extension.

Storybook should not apply hacks while bundling own modules on user side. That doctrine package should be prebundled otherwise it continue to break from time to time.

I was able to reproduce only in webstudio big monorepo. Thought will require time to reproduce. The release brings a lot of changes.

[ndelangen]

Storybook should not apply hacks while bundling own modules on user side..

What do we do that you'd consider 'hacks'?

[TrySound]

Replacing assert with browser-assert when user run storybook. Like here unexpected node_modules layout breaks it.

[ndelangen]

ok, so here:

storybook/code/lib/builder-webpack5/src/preview/iframe-webpack.config.ts

Line 311 in d760a5a

assert: require.resolve('browser-assert'),

and here:

storybook/code/lib/builder-manager/src/index.ts

Line 84 in 4a37372

assert: require.resolve('browser-assert'),

and here:

storybook/code/lib/builder-vite/src/vite-config.ts

Line 62 in 11bec10

assert: require.resolve('browser-assert'),

You think it'd be better if storybook didn't do this at all?

What is an "unexpected node_modules layout"?
Why does this alias break when this occurs?

[TrySound]

Honestly not sure. The layout is built by pnpm in hoisted mode. assert goes to top level node_modules and for some reason becomes preferred over browser-assert. I can investigate this later. Thanks for links.

[milotoor]

Just ran into this problem using SB7 and @storybook/[email protected]. The suggestion above to modify the webpack config helped. My .storybook/main.js file before:

module.exports = {
  stories: [],
  addons: ['@storybook/addon-essentials'],
  framework: {
    name: '@storybook/react-webpack5',
    options: {},
  },
  docs: {
    autodocs: true,
  },
}

And after:

module.exports = {
  stories: [],
  addons: ['@storybook/addon-essentials'],
  webpackFinal: (config) => ({
    ...config,
    resolve: {
      ...config.resolve,
      fallback: {
        ...config.resolve.fallback,
        assert: require.resolve('browser-assert'),
      },
    },
  }),
  framework: {
    name: '@storybook/react-webpack5',
    options: {},
  },
  docs: {
    autodocs: true,
  },
}

I'm quite new to storybook, and am in the process of upgrading from 6.5 to 7. I don't really understand why this change fixes the issue, and don't have a minimal reproduction of the issue to share. Sorry I can't be more helpful, just wanted to voice that upgrading to SB7 does not seem to have completely resolved the problem.

[ChrisSargent]

FWIW, in my case, now on SBv7, the issue is no longer a problem.