Docs tab disappears when updating addon-docs from v6.4 to v6.5

[bartaz]

Describe the bug

When Storybook v6.5 was introduced we noticed that upgrading to it resulted in "Docs" tab in our React documentation to disappear.
I narrowed it down to @storybook/addon-docs package specifically. Everything else can use latest version "6.5.10", but I have to keep @storybook/addon-docs at 6.4.22 to keep it running.
There are no errors either in storybook logs in CLI, nor in the browser that would suggest anything wrong with addon-docs in 6.5.

Repo where it happens:
https://github.com/canonical/react-components

System

Environment Info:

  System:
    OS: Linux 5.10 Ubuntu 20.04.4 LTS (Focal Fossa)
    CPU: (5) arm64 unknown
  Binaries:
    Node: 16.16.0 - /usr/bin/node
    Yarn: 1.22.19 - /usr/bin/yarn
    npm: 8.15.1 - /usr/bin/npm
  npmPackages:
    @storybook/addon-a11y: 6.5.10 => 6.5.10 
    @storybook/addon-controls: 6.5.10 => 6.5.10 
    @storybook/addon-docs: 6.5.10 => 6.5.10 
    @storybook/addons: 6.5.10 => 6.5.10 
    @storybook/builder-webpack5: 6.5.10 => 6.5.10 
    @storybook/manager-webpack5: 6.5.10 => 6.5.10 
    @storybook/react: 6.5.10 => 6.5.10 
    @storybook/theming: 6.5.10 => 6.5.10 

[kherock]

I'm seeing this after upgrading from 6.4 as well. I think this is the same issue as #17527 - my browser console doesn't show any errors unless I navigate to a MDX story.

[kherock]

@bartaz could you let me know if setting your .storybook/preview.js to the following fixes your docs on 6.5?

import { themes } from "@storybook/theming";
import "vanilla-framework/scss/build.scss";

// or global addParameters
export const parameters = {
  docs: {
    ...require('@storybook/addon-docs/preview').parameters.docs,
    theme: themes.vanillaish,
  },
};

[bartaz]

Hey @kherock thanks for the tips, unfortunately adding '@storybook/addon-docs/preview' params to the preview config didn't help. There is still no Docs tab.

Not sure how similar it is to #17527, because in our case the Docs tab doesn't show up at all, even in the toolbar, you can't navigate to it, and we don't see the docs.container error.

[bartaz]

Interestingly, if I manually change the URL to docs path it would show the docs contents just fine, just without a tab in the top bar:

[kherock]

My experience was the same where I have no docs tab either. My setup is slightly different in that I have MDX stories that show the error in the linked issue when I navigate to them.

[bartaz]

I investigated further and looking at some suggestions in comments on #17527 it seems in our case it was a main.js issue. Changing

  addons: [
    "@storybook/addon-docs/preset",
    …
  ],

to

  addons: [
    "@storybook/addon-docs",
   …
  ],

seems to have fixed that. Without any other changes needed to preview.js.

[jackw]

We've been trying to upgrade to 6.5.x and this has also tripped us up. Unfortunately none of the above suggestions have helped us. We aren't writing *.stories.mdx but rather making use of arbitrary mdx and parameters.docs.page with an imported .mdx file in story.tsx. Downgrading addon-docs to 6.4.22 is the only way I've so far managed to keep the docs tab visible.

As reported by @bartaz I can also navigate directly to the /docs/<story-id> and the panel renders fine.

[kherock]

I'm seeing this again after noticing that what seemed to fix it locally didn't end up doing anything after it went through my CI. I'm not even using MDX at all in this storybook - the only things that are somewhat out of the ordinary are that I'm using Yarn 3 and have a custom preview.tsx file. It's the same as @jackw, I can navigate to stories, but the tab will not show.

[kherock]

I came up with another potential fix:

// main.js
module.exports = {
  addons: [
    {
      name: path.dirname(require.resolve('@storybook/addon-docs/package.json')),
      options: { transcludeMarkdown: true },
    },
    { name: '@storybook/addon-essentials', options: { docs: false } },
}

I noticed that the docs page comes back if I enabled the docs addon via addon-essentials. I compared the way that it resolves presets and noticed that it uses require.resolve('<addon>/package.json').

It seems like the problem might be in the way the addon loader resolves files under the package root. It seems to only arise when PnP is enabled as enabling the node-modules linker seems to also fix the missing tab.

[jackw]

@kherock you're a legend! Gave the require.resolve('@storybook/addon-docs/package.json') workaround a try and can confirm it fixes the issue in our yarn PnP project too. Great work! 🙌

[vanessayuenn]

In attempt to clean up old issue, I will be closing this one. We've made lots of improvements in Storybook since 7.0 so it's quite likely that this issue has been resolved already. If this is still a problem, please open a new issue with reproduction steps for 7.x version. Thank you!

[MannyDiera]

For anyone running into this issue in 2024

1. Run npm i @storybook/addon-docs -D to add the addon docs as a dev dependency
2. Add '@storybook/addon-docs' to the addons array in the main.js config.
3. Add tags: ['autodocs'] within the preview object in preview.js.
4. Re-run npm run storybook

// main.js
const config = {
  stories: [
    '../src/**/*.mdx',
    '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'
  ],
  addons: [
    '@storybook/addon-docs',
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@chromatic-com/storybook',
    '@storybook/addon-interactions'
  ],
  framework: {
    name: '@storybook/html-vite',
    options: {},
  },
};

// preview.js
const preview = {
  parameters: {
    controls: {
      matchers: {
        color: /(background|color)$/i,
        date: /Date$/i,
      },
    },
  },
  tags: ['autodocs'],
};