[Nuxt 3/4 + TypeScript] "Cannot find name 'definePageMeta'"

[analog wave]

Hi @hasty willow. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

---

Your issue—VSCode showing "Cannot find name 'definePageMeta'" and "Cannot find name 'useHead'" in a Nuxt 3 + TypeScript project—is a common one, and is almost always related to IDE type resolution rather than a problem with your Nuxt setup itself.

Here are the key points and solutions based on the knowledge sources:

1. Auto-generated Types
   Nuxt generates .nuxt/nuxt.d.ts and .nuxt/tsconfig.json for type support. Your tsconfig.json should extend from ./.nuxt/tsconfig.json, which you already have. This is correct and should provide type information for macros like definePageMeta and composables like useHead automatically. Make sure you have run nuxt dev or nuxt build at least once so these files are generated and up to date. If you overwrite certain options (like compilerOptions.paths) in your own tsconfig.json, it can break type resolution for Nuxt macros and aliases Nuxt TypeScript Concepts.

2. Volar and IDE Issues
   There are known issues where Volar (the recommended VSCode extension for Vue 3) sometimes fails to pick up Nuxt's auto-generated types, especially if there are extra folders in your project or if Volar is misconfigured. In some cases, deleting unrelated folders (like an android folder) or tweaking Volar's settings (such as enabling hybrid mode) has resolved the issue for others GitHub Issue: Typecheck errors on all that is auto imported.

3. No Need for Manual Type References
   You do not need to add /// <reference types="nuxt" /> in your own files if your tsconfig.json is set up correctly. Nuxt's auto-generated types should be picked up automatically.

4. Check for Overridden Paths
   If you have custom compilerOptions.paths in your tsconfig.json, it may prevent Nuxt's aliases and macro types from being recognized. Try removing or adjusting them to avoid conflicts Nuxt TypeScript Concepts.

5. Try a Clean Project
   If a fresh Nuxt project does not have this issue, but your current one does, it may be due to project-specific configuration or extra folders/files confusing the IDE. Try to isolate the difference.

Summary of steps to try:

• Ensure you have run nuxt dev or nuxt build to generate .nuxt/nuxt.d.ts and .nuxt/tsconfig.json.
• Make sure your tsconfig.json extends from ./.nuxt/tsconfig.json and does not override compilerOptions.paths unless necessary.
• Restart VSCode and the TypeScript server.
• Check Volar settings (try enabling hybrid mode).
• Remove any unrelated folders that might confuse the IDE (as seen with the android folder in one case).
• If the problem persists only in VSCode but not in other IDEs (like WebStorm), it is likely an IDE/plugin issue, not a Nuxt one.

If none of these steps resolve the issue, consider opening an issue with a reproduction on the Nuxt GitHub or the Volar language tools repo GitHub Issue: Typecheck errors on all that is auto imported.

You are not missing anything fundamental in your Nuxt setup—this is almost certainly an IDE type resolution quirk.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: