State of the project

[tobiasdiez]

We want to provide a transparent update regarding the state of the Storybook/Nuxt module.

There are currently several known issues affecting this module. While some of these have known workarounds, others remain unresolved. Unfortunately, none of these issues are actionable by the maintainers of this module at this time, as they require changes in the upstream Storybook project.

The primary challenge is that the Storybook team is currently unable to offer assistance in merging the upstream PRs that we have opened to address these issues. At the moment, these are:

• Vite: Import preview runtime as ordinary module storybookjs/storybook#29172
• Vite: Improve handling of preview annotations storybookjs/storybook#28798
• CLI: Re-Add Nuxt support storybookjs/storybook#28607
• Vite: Don't prefix story import with @fs storybookjs/storybook#28941

Furthermore, we are impacted by the following unfixed upstream issues:

• BUG: vue-component-meta not running correctly storybookjs/storybook#29494
• [Bug]: Storybook doesn't work with Yarn 4 (nodeLinker: pnpm), Vue 3, Vite 5, Storybook 8 storybookjs/storybook#28620
• [Feature Request]: add hook to provide initial vite config storybookjs/storybook#20817

As a result, we all are at an impasse: either these limitations will need to be worked around or tolerated for now.

Or you might consider exploring alternative solutions. One such alternative is Histoire, a project that has shown a strong commitment to supporting the Vue ecosystem and may offer a more engaging path forward for Nuxt developers.

We remain committed to providing the best possible experience for users of this module and will revisit this situation if new opportunities arise. Thank you for your understanding and for being part of this journey.

[hacknug]

Thanks for the explanation and for putting together a list of issues and PRs currently affecting us. Let's see if we can do anything to help the upstream folks getting those to the finish line 👍

[lafllamme]

Thanks for the update and the detailed breakdown of issues. We’ll do our best to assist in pushing these forward and supporting the upstream efforts. 🚀

[shilman]

I'm sorry that things have stalled in the Nuxt framework due to unresolved Storybook issues.

Unfortunately, none of the linked PRs are in a mergeable state. Each requires attention and rework from the core team. Based on this issue, we plan to see whether we can get these issues resolved next week.

How did we get here? We try to merge smaller PRs as they come in, but the more disruptive ones often get backed up and sometimes kicked down the road as we focus on big changes to other parts of Storybook. This is an issue with our process, and something we can improve in a more systematic way as part of our PR triage, which typically focuses on incoming PRs but should also spend more time figuring out how to work down the backlog.

As for the future of Nuxt support, this issue helps clarify the urgency in the short term. Longer term, we hope that we can work through issues together more smoothly and keep the great work you're doing here unblocked.

[MelvinIdema]

I'm sorry that things have stalled in the Nuxt framework due to unresolved Storybook issues.

Unfortunately, none of the linked PRs are in a mergeable state. Each requires attention and rework from the core team. Based on this issue, we plan to see whether we can get these issues resolved next week.

How did we get here? We try to merge smaller PRs as they come in, but the more disruptive ones often get backed up and sometimes kicked down the road as we focus on big changes to other parts of Storybook. This is an issue with our process, and something we can improve in a more systematic way as part of our PR triage, which typically focuses on incoming PRs but should also spend more time figuring out how to work down the backlog.

As for the future of Nuxt support, this issue helps clarify the urgency in the short term. Longer term, we hope that we can work through issues together more smoothly and keep the great work you're doing here unblocked.

Great to see the Nuxt community is now in the view of the Storybook team. Let's hope we can resolve this together!

[mehcode]

If it helps, here is my Storybook configuration on a fresh Nuxt project, with the latest versions of everything. Absolutely everything works great. I have the full Storybook setup with 100s of components using Chromatic.

@tobiasdiez has done amazing work over the last few months.

When I first started working with Storybook + Nuxt I had many many more hacks than I have now. This is barely anything. Just a few snippets here and there. The DX could be improved further of course, but we've come a long way.

I hope the hacks present in these files help narrow the focus on what might be wrong for a fresh project just adding storybook.

package.json

    "@nuxtjs/storybook": "npm:@nuxtjs/storybook@nightly",
    "@storybook/addon-actions": "^8.4.7",
    "@storybook/addon-backgrounds": "^8.4.7",
    "@storybook/addon-controls": "^8.4.7",
    "@storybook/addon-docs": "^8.4.7",
    "@storybook/addon-essentials": "^8.4.7",
    "@storybook/addon-highlight": "^8.4.7",
    "@storybook/addon-measure": "^8.4.7",
    "@storybook/addon-outline": "^8.4.7",
    "@storybook/addon-toolbars": "^8.4.7",
    "@storybook/addon-viewport": "^8.4.7",
    "storybook": "^8.4.7",

.storybook/preview.ts

import { setup, type Preview } from "@storybook-vue/nuxt";
import { createI18n } from "vue-i18n";
import i18n from "../i18n.config.js";
import { addons } from "storybook/internal/preview-api";

setup(async (app) => {
  // HACK: without this, a data race occurs and i18n is added to the wrong vue app
  // error: "i18n[TranslateVNodeSymbol] is not a function"
  await new Promise((resolve) => setTimeout(resolve, 0));
  app.use(createI18n(i18n));
});

// HACK: ever since the update to Nuxt 3.12 and Storybook 8.12, the static
//  build of our storybook fails to select the story on first load
//  this hacks into the internal API of storybook to force a select
//  immediately
setTimeout(() => {
  const query = new URLSearchParams(window.parent.location.search.slice(1));
  const storyId = query.get("path")?.split("/")?.at(-1);

  if (storyId != null) {
    addons.getChannel().emit("setCurrentStory", {
      storyId,
    });
  }
}, 0);

export default {
  tags: ["autodocs"],
  parameters: {
    actions: { argTypesRegex: "^on.*" },
  },
  // add a margin around components,
  // so they aren't squished up against the viewport
  decorators: [
    (story) => ({
      components: { story },
      template: '<div style="margin: 20px"><story /></div>',
    }),
  ],
} satisfies Preview;

.storybook/main.ts

import type { StorybookConfig } from "@nuxtjs/storybook";
import type { PluginOption } from "vite";

function removePluginByName(plugins: PluginOption[], pluginName: string) {
  // @ts-expect-error we promise this is ok
  const index = plugins.findIndex((plugin) => plugin?.name === pluginName);

  if (index !== -1) {
    plugins.splice(index, 1);
  }
}

export default {
  stories: ["../**/*.stories.ts"],
  staticDirs: [{ from: "./static/", to: "/static" }, "../public"],
  framework: {
    name: "@storybook-vue/nuxt",
    options: {
      docgen: "vue-component-meta",
    },
  },
  addons: [
    "@storybook/addon-docs",
    "@storybook/addon-controls",
    "@storybook/addon-backgrounds",
    "@storybook/addon-actions",
    "@storybook/addon-highlight",
    "@storybook/addon-measure",
    "@storybook/addon-outline",
    "@storybook/addon-toolbars",
    "@storybook/addon-viewport",
  ],
  docs: {
    autodocs: "tag",
  },
  core: {
    disableTelemetry: true,
  },
  viteFinal: (config) => {
    // HACK: use the runtime template compiler version of vue.js
    config.resolve ??= {};
    config.resolve.alias = {
      vue: "vue/dist/vue.esm-bundler.js",
      ...config.resolve.alias,
    };

    config.plugins ??= [];

    // HACK: remove the `inspect` plugin (if present)
    // causes invalid string length issues
    removePluginByName(config.plugins, "vite-plugin-inspect");

    return config;
  },
} satisfies StorybookConfig;

i18n.config.ts

import type { I18nOptions } from "vue-i18n";

export default {
  legacy: false,
  locale: "en",
  fallbackLocale: "en",
} satisfies I18nOptions;

[chakAs3]

Hi @mehcode, great to hear everything is working well for you! With hundreds of components on Chromatic, I’m curious how the i18n module (or any other module that applies plugins to the Vue app) has been functioning for you.

I recently opened a PR that addresses a bug where, on the second click of a story, the plugin isn’t available. Let me know if you’ve encountered anything similar!

[mehcode]

@chakAs3 Awesome. Yes, that is one of the issues I've had and have a hack for to paper over. From the issue above.

import { setup, type Preview } from "@storybook-vue/nuxt";
import { createI18n } from "vue-i18n";
import i18n from "../i18n.config.js";
import { addons } from "storybook/internal/preview-api";

setup(async (app) => {
  // HACK: without this, a data race occurs and i18n is added to the wrong vue app
  // error: "i18n[TranslateVNodeSymbol] is not a function"
  await new Promise((resolve) => setTimeout(resolve, 0));
  app.use(createI18n(i18n));
});

// [...]

Without that hack, I get the behavior you mention. Will be nice to remove that one.

[chakAs3]

Hi @mehcode,Oh, I see! calling app.use() in the setup function is a quick workaround—it’s a clever hack, though it might not resolve the issue entirely since you still wouldn’t get the value without that nice delay trick right?. That approach hadn’t come to my mind!
The PR I submitted does fix this, but I really appreciate how well you described the issue—it could’ve been really helpful yesterday to debug and resolve it faster.

If you had any similar issues with super hacks, please feel free to share with me so we can resolve it properly !

[chakAs3]

Hi @mehcode new release 8.3.3 available now with the proper fix, please check it out and let me know
https://github.com/nuxt-modules/storybook/releases/tag/v8.3.3

[mehcode]

Great work. I can confirm that the new version removes the need for the setup(..) hack I have.

[shilman]

@tobiasdiez I'm following up to see how everything is going.

It looks like we merged three of the four PRs you mentioned in the original issue, and storybookjs/storybook#28798 is failing in CI. We merged storybookjs/storybook#28607 and released it as part of Storybook 8.5 so the Nuxt framework should be getting hundreds more fresh installs every week.

[tobiasdiez]

@shilman Thanks so much to you and the entire Storybook team! The most pressing issues have been resolved, and the Nuxt integration is now running much more reliably. Great work—let’s keep it going! I think we can close this issue.

I attempted to fix PR #28798 a few times, but each time I ran into unrelated issues with the test suites (see, for example, this comment). The test failures don’t seem critical—likely just outdated snapshots.