docs: framework support guide (Vue, Svelte, Astro) + example

[JoviDeCroock]

What / Why

Users keep asking whether GraphQLSP works in non-.ts files — Astro (#242), Svelte(Kit) (#251, closed as duplicate of #168), and Vue. Since GraphQLSP is a tsserver plugin, the answer depends entirely on whether each framework's language tooling routes its single-file components through tsserver (where tsconfig.json plugins load) or through its own language server (where they don't).

This PR adds a Framework support section to the README documenting the current state per framework, plus a minimal working Vue example package (packages/example-vue, modeled on packages/example-tada). Docs + private example packages only — no changeset needed, packages/graphqlsp is untouched.

Research findings (with sources)

Vue — supported. Vue Language Tools serves TypeScript features for .vue files through the regular tsserver running @vue/typescript-plugin ("hybrid mode"); as of v3 this is the only mode — the Vue language server no longer handles TypeScript itself (upgrade guide, vuejs/language-tools#5456). Because Volar maps positions between the SFC and its virtual TS at the tsserver boundary, GraphQLSP (declared in tsconfig.json plugins) participates in .vue script blocks with correctly mapped positions. Note this supersedes the current gql.tada docs statement that the TS plugin "won't be able to run in your editor under normal circumstances" for .vue files.

Svelte — .ts files only. svelte-language-server handles .svelte files itself and does not load external TS plugins; typescript-svelte-plugin only teaches tsserver about .svelte imports from .ts files and deliberately returns no diagnostics for .svelte files. External TS plugin support is a still-open feature request from 2021 labeled "limitation": sveltejs/language-tools#905. See also the history in #168/#251. gql-tada check + @gql.tada/svelte-support covers .svelte documents on the CLI.

Astro — .astro files not supported. The Volar-based Astro language server (now in the Astro monorepo) type-checks .astro frontmatter in its own server and ignores compilerOptions.plugins. Both requests to change this were closed as not planned: withastro/language-tools#991 (repo since archived) and withastro/astro#16917 (May 2026). .ts files in Astro projects work as usual.

What was verified vs not

Verified headlessly in this workspace:

• Vue editor path (raw tsserver protocol): spawned tsserver --globalPlugins @vue/typescript-plugin (exactly how the Vue VS Code extension / vtsls load it) against packages/example-vue, opened src/Pokemon.vue with a deliberate schema typo:
  • GraphQLSP diagnostic 52001 Cannot query field "fleeRatee" on type "Pokemon". Did you mean "fleeRate"? reported at the correct .vue line/column
  • hover on a document field returned Pokemon.name: String!
  • completions inside the selection set returned schema fields (maxCP, maxHP, id)
  • versions: @vue/typescript-plugin@3.3.6, TypeScript 5.3.3, vue 3.5.39
• Vue CLI path: vue-tsc --noEmit passes on the example; with the typo present it still passes (confirming CLI type checks don't run LS plugins), while gql-tada check (with @gql.tada/vue-support) correctly reports the same error at src/Pokemon.vue:10:7
• Root pnpm install succeeds with the new package; pnpm --filter @0no-co/graphqlsp run build and the full pnpm run test:e2e suite pass (52/52)

NOT verified (no editor available headlessly):

• an actual VS Code / Neovim session for Vue — though the raw-protocol test replicates the exact plugin-loading mechanism those editors use
• Svelte and Astro claims were not reproduced locally; they rest on the cited issues, source comments, and gql.tada docs rather than a local repro
• Vue Language Tools 2.x hybrid mode (only 3.3.6 was tested; 2.x hybrid mode uses the same architecture but wasn't exercised)

Side note: gql-tada check crashes with TypeError: t.unref is not a function in @gql.tada/cli-utils@1.9.0 cleanup on Node 22 after printing correct results — unrelated to this PR, may be worth an upstream look.

Follow-up proposals (not implemented here)

• No adapter/shim is needed for Vue — it works with zero GraphQLSP changes.
• Svelte/Astro can't be unlocked from our side: the blocker is that their language servers never invoke tsserver plugins for their SFC formats. A GraphQLSP-side shim can't inject itself into those servers. If desired, the realistic follow-ups are upstream contributions (a Volar getExternalFiles-style plugin bridge in svelte-language-server per Use external typescript-plugin for IntelliSense within svelte files sveltejs/language-tools#905, or compilerOptions.plugins initialization in Astro's language server per Support compilerOptions.plugins inside Astro Language Server (Breaks TS Language plugins) withastro/astro#16917), plus documenting gql-tada check support packages as the CI story.
• Optionally add a small e2e test that runs the Vue scenario (tsserver + --globalPlugins @vue/typescript-plugin) in CI to catch regressions in the Volar interop; left out to keep this PR docs/example-only.

🤖 Generated with Claude Code

[changeset-bot]

⚠️ No Changeset found

Latest commit: b59652c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR