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;