Vue: Enhance Support for vue-component-meta with tsconfig References

[larsrickert]

What I did

We need to pass a valid tsconfig file to vue-component-meta to work correctly.
When using tsconfig references in the default tsconfig.json, the user must explicitly set which tsconfig to use, otherwise docgen might be broken or not work correctly.

I added a framework option to change the tsconfig that vue-component-meta uses.

Note: The setup shown in the example below is actually pretty common since its the default that you get from the official Vue starter CLI.

Example:

Show example

tsconfig.json

{
  "files": [],
  "references": [
    { "path": "./tsconfig.node.json" },
    { "path": "./tsconfig.app.json" },
  ]
}

tsconfig.app.json

{
  "extends": "@vue/tsconfig/tsconfig.dom.json",
  "include": ["env.d.ts", "src/**/*"],
  "exclude": ["src/**/*.ct.*", "src/**/*.spec.*", "src/**/*.stories.ts"],
  "compilerOptions": {
    "composite": true,
    "rootDir": "./src",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

tsconfig.node.json not relevant for this example

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/vue3-vite';

const config: StorybookConfig = {
  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: {
        plugin: 'vue-component-meta',
        tsconfig: 'tsconfig.app.json',
      },
    },
  },
};

export default config;

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!

1. Run a sandbox for template, e.g. yarn task --task sandbox --start-from auto --template vue3-vite/default-ts
2. In sandbox/vue3-vite-default.ts, replace tsconfig.json with:

{
 "files": [],
 "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
}

3. In sandbox/vue3-vite-default.ts, create `tsconfig.app.json with:

{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "skipLibCheck": true,

    "moduleResolution": "bundler",
    "allowImportingTsExtensions": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "noEmit": true,
    "jsx": "preserve",

    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true,
    "paths": {
      "@/*": ["./src/*"]
    },
    "composite": true
  },
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
}

4. In src/stories/Header.vue, move the prop type to src/stories/types.ts and import it from @/stories/types
5. Start Storybook
6. Open http://localhost:6006/?path=/docs/example-header--docs
7. Docgen will now be broken, prop types/description etc. is missing because vue-component-meta does not resolve the references so it does not consider the @/ import alias
8. In .storybook/main.ts, add framework option:

  framework: {
    name: '@storybook/vue3-vite',
    options: {
      docgen: {
        plugin: "vue-component-meta",
        tsconfig: "tsconfig.app.json"
      }
    },
  },

9. Restart Storybook
10. Check the Story again. It will not work correctly

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/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>

[nx-cloud]

☁️ Nx Cloud Report

CI is running/has finished running commands for commit 5aab872. As they complete they will appear below. Click to see the status, the terminal output, and the build insights.

📂 See all runs for this CI Pipeline Execution

---

✅ Successfully ran 1 target

• nx run-many --target=prep --all --parallel=8 --max-parallel=3 -- --reset --optimized

---

Sent with 💌 from NxCloud.

[chakAs3]

Thank you, @larsrickert, for providing the workaround. Additionally, your open issue regarding vue language-tools is noted. I'm currently seeking feedback from @johnsoncodehk on this matter. Meanwhile, I'll conduct some tests before granting approval. However, I'm inclined to change the function name ..WithWorkaround, so I'll be working on finding a suitable implementation for that adjustment.

[chakAs3]

I believe the correct approach is to provide a valid tsconfig to the checker directly. Therefore, what we've implemented, suggested by @larsrickert, isn't a workaround but rather our first solution. This involves explicitly passing the valid tsconfig in main.ts. Another, more ideal option would be to create a lookup manager that automatically locates a valid tsconfig for a .vue file from references in case we have it

[chakAs3]

so @larsrickert it is not vue-componet-meta limitation it is meant to be like that we got a response from Johson
vuejs/language-tools#3896 (comment)

[larsrickert]

@chakAs3 I updated the docs, hopefully its clearer now that it is the recommended solution

[jonniebigodes]

@larsrickert, appreciate you taking the time to create this pull request and helping us by including the necessary documentation 🙏 ! I left a small suggestion for you to look into regarding the documentation when you can.

Let me know once you've addressed it, and I'll gladly take another look.

Looking forward to hearing from you.

Hope you have a fantastic day.

Stay safe

[kasperpeulen]

LGTM

[baixiaoyu2997]

Or perhaps this is a bit off-topic, could we add a prompt to inform users that setting vue-component-meta will affect the build's performance, and could even cause the build to fail on Vercel, for example, At least one "Out of Memory" ("OOM") event was detected during the build.
reference: #26647

[larsrickert]

Or perhaps this is a bit off-topic, could we add a prompt to inform users that setting vue-component-meta will affect the build's performance, and could even cause the build to fail on Vercel, for example, At least one "Out of Memory" ("OOM") event was detected during the build. reference: #26647

I would like to take a look at this separately. Once this PR is merged, we can check if setting the tsconfig improves performance, otherwise we need to take a look at the performance issues in more detail

[larsrickert]

@kasperpeulen Hey :) I assumed this PR would be included in version 8.1 yesterday but it seems like it isn't.
Is this intended or do you have an estimate when this will be released?

[shilman]

@larsrickert The problem is that this PR (and a couple others) mistakenly targeted and was merged to main. In our workflow we target everything to next. I thought the team took care of this during the release. If that's not the case, we'll try to get it into a patch release ASAP.

[larsrickert]

@larsrickert The problem is that this PR (and a couple others) mistakenly targeted and was merged to main. In our workflow we target everything to next. I thought the team took care of this during the release. If that's not the case, we'll try to get it into a patch release ASAP.

I double checked it, it is in fact released. It is only missing in the changelog, thats what caused my confusing :D