fix(nuxt): skip generation during prepare if no input & config types #2618

RihanArfan · 2025-09-09T23:50:50Z

Some bug fixes and improvements to the Nuxt module and documentation.

bolt-new-by-stackblitz · 2025-09-09T23:50:53Z

Run & review this pull request in StackBlitz Codeflow.

vercel · 2025-09-09T23:50:54Z

@RihanArfan is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

changeset-bot · 2025-09-09T23:50:54Z

⚠️ No Changeset found

Latest commit: 2f01555

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

mrlubos

I assume this will fix the occasional crash I've been running into so THANK YOU for that. I just need some context around the other changes made so I can clean up the docs to match the style elsewhere

mrlubos · 2025-09-10T06:24:44Z

docs/openapi-ts/clients/nuxt.md

 ---
-title: Nuxt v3 Client
-description: Generate a type-safe Nuxt v3 client from OpenAPI with the Nuxt client for openapi-ts. Fully compatible with validators, transformers, and all core features.
+title: Nuxt Client


Why make these changes? Once we finalize this page, we should have a v4 page too, it's ambiguous which version it's compatible with otherwise

Going forwards a major Nuxt release should still be backwards compatible with older modules. When Nuxt v5 releases Q4 25/Q1 26 the same module should work without any new changes. Since Nuxt 2 is EOL I don't think there'll be any confusion about using the module with it.

https://nuxt.com/docs/4.x/guide/going-further/modules#do-not-advertise-with-a-specific-nuxt-version

Nice work! I will still want to polish some of the wording in this copy, but overall I agree with the changes you've made/are making

Thank you 😄 docs isn't my strong suit

mrlubos · 2025-09-10T06:26:52Z

docs/openapi-ts/clients/nuxt.md

+      plugins: [
+        {
+          name: '@hey-api/client-nuxt',
+          runtimeConfigPath: './shared/lib/hey-api.ts', // [!code ++]


Why do you sometimes use the ./shared/lib path in your examples?

The runtime config path should be within ./app or ./shared because of how Nuxt generates the tsconfigs for it's imports etc. so #hey-api/ will resolve to the generated client. If the file was directly in the project root, TS would throw errors since it can't resolve the import.

Originally I thought the generated Nuxt client could be used in both the frontend and server routes, so I figured the shared directory would be the best Nuxt folder for it. I just tested now and the generated client can't be used within server routes.

So based on this the Hey API docs should be recommending people put that file within ./app (anywhere). I guess the runtime config could reside in utils, but given that's an auto imported directory I think users using lib is better.

Suggested change

runtimeConfigPath: './shared/lib/hey-api.ts', // [!code ++]

runtimeConfigPath: './app/lib/hey-api.ts', // [!code ++]

We only need to mention it within the docs in the runtime config section, and it doesn't need to be added to other examples imo.

What would need to change to make it work within server routes? Seems like an important issue, even if not directly related to this pull request

I agree, it would make it so convenient for both building fully fullstack Nuxt, or BFFs (which are really popular with Nuxt).

I believe the issue is because the client has imports for Nuxt and Vue things which can't be used on Nitro server routes.

openapi-ts/packages/openapi-ts/src/plugins/@hey-api/client-nuxt/bundle/client.ts

Lines 1 to 7 in 91bc2d0

import {

useAsyncData,

useFetch,

useLazyAsyncData,

useLazyFetch,

} from 'nuxt/app';

import { reactive, ref, watch } from 'vue';

What I'd suggest is creating ~~@hey-api/client-nitro~~ @hey-api/client-ofetch (which basically a super simplified Nuxt client copy) and the Nuxt module can register these server imports with addServerImports(). As a standalone ofetch client, people using that outside of Nuxt/Nitro also benefit similar to how there's an Axios one.

On top of this you could create a separate Nitro module for standalone Nitro users (since it's a fantastic backend framework) which acts similarly to the Nuxt module

packages/nuxt/package.json

mrlubos

Actually I think the CI error you're seeing is what I refer to in my message above haha

RihanArfan · 2025-09-10T21:14:40Z

Thanks for reviewing it so fast ❤️ I've responded to your questions. Lmk if there's anything else you'd like to know.

~~With the Nuxt module specifically, there is a postinstall script which does need the openapi-ts to be built. Cannot find module '/home/runner/.../node_modules/@hey-api/openapi-ts/dist/index.cjs' (dist)

I'm going to edit the CI workflow to sort it out now~~

Update: just edited the package.json to move the postinstall/nuxt prepare script to be ran before build instead. If there's a contributing guide or any docs for developing: to work on the nuxt module after cloning this repo, first run pnpm run dev:prepare

nuxt/starter@9c3f24f

skipping as @hey-api/openapi-ts throws an exception if missing input which makes prepare fail

mrlubos

There are still some CI fails, but the good news is, the error is different now 🎉

mrlubos · 2025-09-11T06:18:27Z

packages/nuxt/package.json

  "scripts": {
-    "build": "nuxt-module-build build",
-    "dev": "tsup --watch",
+    "dev:prepare": "nuxt-module-build prepare",


So how does development work now? Do you just run this script instead of dev? If so, why not keep it named dev?

Right now there's no way for previewing local development outside of TS type checking, since there's no playground. I can add back a playground so local development, manual testing and an example of usage is available.

Normally this is how local development looks:

git clone

pnpm i

pnpm dev:prepare # generates types and stubs for local dev

pnpm dev # launch the nuxt app inside playground/ which uses the module with hot reloading.

https://github.com/nuxt/starter/blob/module/package.json#L27-L29

The dev:prepare script currently just generates the .nuxt directory (which contains things like the generated tsconfig etc).

I don't want to burden you with the playground, if the CI checks pass that should be enough for now!

I think the CI failures are related to type checking the pinia colada examples

I've pushed a fix for the other issue which has triggered CI and hopefully the other one works 🤞

packages/nuxt/src/module.ts

mrlubos

@RihanArfan are you able to fix the typecheck issue?

dosubot bot added size:L This PR changes 100-499 lines, ignoring generated files. bug 🔥 Something isn't working client Client package related docs 📃 Improvements or additions to documentation labels Sep 9, 2025

RihanArfan force-pushed the fix/nuxt-module branch from 1497aaf to 5791605 Compare September 10, 2025 00:14

RihanArfan changed the title ~~fix: skip generation during prepare if no input~~ fix(nuxt): skip generation during prepare if no input Sep 10, 2025

mrlubos reviewed Sep 10, 2025

View reviewed changes

mrlubos requested changes Sep 10, 2025

View reviewed changes

RihanArfan added 9 commits September 10, 2025 22:58

fix: optional chaining

f4ef6f8

chore: update exports

5868419

nuxt/starter@9c3f24f

chore: add nuxt module builder deps & upgrade deps

8beb2e7

chore: use nuxt generated tsconfig

ce81209

chore: remove unused vitest config

8baac38

fix: config types in nuxt config

db714c7

fix: skip gen during prepare if no input

49d1352

skipping as @hey-api/openapi-ts throws an exception if missing input which makes prepare fail

docs: improve nuxt docs

93e357b

chore: move prepare to build script

19fa633

RihanArfan force-pushed the fix/nuxt-module branch from 5791605 to 19fa633 Compare September 10, 2025 22:01

fix: import from @nuxt/kit

ac84c29

mrlubos requested changes Sep 11, 2025

View reviewed changes

docs: fix link

eb48124

RihanArfan changed the title ~~fix(nuxt): skip generation during prepare if no input~~ fix(nuxt): skip generation during prepare if no input & config types Sep 11, 2025

This was referenced Sep 11, 2025

refactor(pinia-colada): migrate queries to defineQueryOptions #2610

Merged

feat: init client-ofetch #2642

Merged

Merge branch 'main' into fix/nuxt-module

2f01555

mrlubos requested changes Sep 21, 2025

View reviewed changes

or2e mentioned this pull request Sep 30, 2025

[@hey-api/nuxt] Missing typing in nuxt.config #2282

Open

	runtimeConfigPath: './shared/lib/hey-api.ts', // [!code ++]
	runtimeConfigPath: './app/lib/hey-api.ts', // [!code ++]

	import {
	useAsyncData,
	useFetch,
	useLazyAsyncData,
	useLazyFetch,
	} from 'nuxt/app';
	import { reactive, ref, watch } from 'vue';

Uh oh!

fix(nuxt): skip generation during prepare if no input & config types #2618

Are you sure you want to change the base?

fix(nuxt): skip generation during prepare if no input & config types #2618

Conversation

RihanArfan commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bolt-new-by-stackblitz bot commented Sep 9, 2025

Uh oh!

vercel bot commented Sep 9, 2025

Uh oh!

changeset-bot bot commented Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

mrlubos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RihanArfan Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RihanArfan Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mrlubos left a comment

Choose a reason for hiding this comment

Uh oh!

RihanArfan commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrlubos left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RihanArfan Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RihanArfan Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mrlubos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

RihanArfan commented Sep 9, 2025 •

edited

Loading

changeset-bot bot commented Sep 9, 2025 •

edited

Loading

RihanArfan Sep 10, 2025 •

edited

Loading

RihanArfan Sep 10, 2025 •

edited

Loading

RihanArfan commented Sep 10, 2025 •

edited

Loading

RihanArfan Sep 11, 2025 •

edited

Loading

RihanArfan Sep 11, 2025 •

edited

Loading