Nuxt•7d ago

import defineNitroPlugin or not? Import aliases not working in /server/plugins/*.ts

Hi, I created a new Project today on the newest version 4.2.1 and for some reason I dont get type hints for defineNitroPlugin anymore. Also, I cannot import from e.g. "~~/server/utils/auth". This works in server utils and API routes, but for some reason, in plugins, it does not. If I run the dev server everything works. I am using this plugin to create a better-auth superuser (I just need 1 user), is there another way I can / should do this? In the docs it tells me: "It is necessary to explicitly import defineNitroPlugin from nitropack/runtime within your plugin file.", but I have another app in which the type completion works, also on the newest nuxt version. I tried: - deleting node_modules and .nuxt folders and recreating them multiple times. - restarting dev server If I need to explicitly import it, that is fine by me, but why does my other app work? 😄

12 Replies

kapa.ai•7d ago

Hi @Dustin. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- You’ve run into two separate but related things: 1. defineNitroPlugin import / typings In custom Nuxt modules, Nitro plugins do not work “magically” unless you explicitly import Nitro/runtime helpers like defineNitroPlugin and useRuntimeConfig in the plugin file itself. This was important enough that it was added as a docs warning: you must import them directly rather than relying on auto‑imports. [custom module warning] That’s why you’ll see examples that do:

   // server/plugins/my-plugin.ts
   import { defineNitroPlugin } from 'nitropack/runtime'
   import { useRuntimeConfig } from '#imports'

   export default defineNitroPlugin((nitroApp) => {
     const config = useRuntimeConfig()
     // ...
   })

   // server/plugins/my-plugin.ts
   import { defineNitroPlugin } from 'nitropack/runtime'
   import { useRuntimeConfig } from '#imports'

   export default defineNitroPlugin((nitroApp) => {
     const config = useRuntimeConfig()
     // ...
   })

If this file is part of a module, trying to use #build/types/nitro-imports or other app aliases inside the server runtime can trigger “Vue app aliases are not allowed in server runtime” and missing‑file errors, so you should not rely on that pattern. [StackOverflow nitro plugin] The change in Nuxt 4.1–4.2 around separate TS projects and tsconfig generation can affect how/where those types are included, so one project may still have working editor inference from older behavior while a fresh project follows the newer, stricter setup. There isn’t enough detail in the sources to say exactly why your other app still resolves defineNitroPlugin without explicit import, but current guidance is to import it explicitly. 2. Aliases / auto‑imports in server context - Nuxt 4 introduced a dedicated shared/ directory (with #shared alias) whose types are wired into both tsconfig.json and tsconfig.server.json, and whose utils/types are auto‑importable from both app and server. [shared folder; shared types server] - There have been fixes to make sure server‑side tsconfig includes server files in layers and shared types, mainly to fix editor errors like “Cannot find name defineNitroPlugin” even though the app runs. [layer server tsconfig; shared types server] - Another fix restored Nuxt aliases into Nitro’s compilerOptions.paths so things like #imports/#components and other aliases work correctly in server TS context. [restore nitro aliases] The issue you describe — aliases like ~~/server/utils/auth working in server routes but not in server/plugins/*.ts, plus missing type hints — matches these TS‑config / include issues. In 4.2.1, the patches above should be in place, but IDEs (especially JetBrains) have had bugs with Nuxt typings and may not fully respect the generated multi‑tsconfig setup. [JetBrains TS bug note] What you should do now - In server plugins, explicitly import Nitro helpers:

  import { defineNitroPlugin } from 'nitropack/runtime'
  import { useRuntimeConfig } from '#imports'

  import { defineNitroPlugin } from 'nitropack/runtime'
  import { useRuntimeConfig } from '#imports'

- Use standard Nuxt aliases (#imports, #shared, etc.) where possible; if ~~/server/... is not being resolved in the plugin but works elsewhere, that’s likely your IDE reading the wrong tsconfig or not picking up the generated .nuxt/tsconfig.server.json. The runtime behavior being correct but types failing is exactly what the tsconfig fixes were addressing. [layer server tsconfig] - For creating a superuser in Nitro, your current approach (Nitro plugin that runs on server startup / on first request and uses useRuntimeConfig) is consistent with the documented pattern; the sources don’t describe an alternative “recommended” superuser mechanism beyond standard Nitro plugins, so there’s no clearly better documented pattern to point to. Because the knowledge sources don’t include your exact repo setup, I can’t say precisely why the other app still has auto‑completion without explicit imports, but the current documented and supported pattern is to always import defineNitroPlugin (and similar) explicitly in server plugins, especially when they’re registered from a custom Nuxt module. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•7d ago

<@239748199818985472> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

DustinOP•7d ago

@kapa.ai what should my root tsconfig.json look like?

kapa.ai•7d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- For Nuxt 4 with the new multi‑project setup, the docs and issues consistently show the root tsconfig.json as a project reference file that mainly points to the generated configs and (optionally) adds shared compilerOptions. The minimal recommended shape is:

{
  // <https://nuxt.com/docs/guide/concepts/typescript>
  "files": [],
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" },
    { "path": "./.nuxt/tsconfig.shared.json" },
    { "path": "./.nuxt/tsconfig.node.json" }
  ]
}

{
  // <https://nuxt.com/docs/guide/concepts/typescript>
  "files": [],
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" },
    { "path": "./.nuxt/tsconfig.shared.json" },
    { "path": "./.nuxt/tsconfig.node.json" }
  ]
}

[typecheck issue; shared tsconfig issue] If you need global compiler options (e.g. decorators), you can add them at the root level; these are then picked up by the referenced projects:

{
  "files": [],
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" },
    { "path": "./.nuxt/tsconfig.shared.json" },
    { "path": "./.nuxt/tsconfig.node.json" }
  ],
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strictPropertyInitialization": false,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

{
  "files": [],
  "references": [
    { "path": "./.nuxt/tsconfig.app.json" },
    { "path": "./.nuxt/tsconfig.server.json" },
    { "path": "./.nuxt/tsconfig.shared.json" },
    { "path": "./.nuxt/tsconfig.node.json" }
  ],
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "strictPropertyInitialization": false,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

[shared tsconfig issue] The sources don’t provide a more opinionated full template (e.g. for paths/aliases) beyond this pattern. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•7d ago

<@239748199818985472> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

DustinOP•7d ago

@kapa.ai found the "error", mine was like this: { // https://nuxt.com/docs/guide/concepts/typescript "extends": "./.nuxt/tsconfig.json" }

kapa.ai•7d ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- That extends setup is exactly what causes problems with Nuxt 4’s new TypeScript project references. Nuxt’s docs and migration notes explicitly say you must remove:

"extends": "./.nuxt/tsconfig.json"

"extends": "./.nuxt/tsconfig.json"

when you switch to the new references‑based config, because extends and references are mutually exclusive and lead to lots of unexpected TS errors if combined. [extends removal] So your fix is correct: replace the old config with the project‑references style one, e.g.:

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

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

[typecheck issue] ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•7d ago

<@239748199818985472> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

kapa.ai•7d ago

Let me check the knowledge base for you again. One moment! :books:

MEE6•7d ago

staubinger has been warned

Reason: Mass mention

kapa.ai•7d ago

---------------------- Nuxt’s own docs and issues only give partial guidance here, not a full “official minimal package.json”, so some of this can’t be answered with absolute authority. What is clear from the sources: 1. Is nuxt a dependency or devDependency? In all the Nuxt 3/4 projects and examples in the sources, nuxt is always in devDependencies, not dependencies. Examples:

"devDependencies": {
  "nuxt": "^3.10.0",
  "nuxt-icon": "^0.6.8",
  "nuxt-primevue": "^0.2.2"
}

"devDependencies": {
  "nuxt": "^3.10.0",
  "nuxt-icon": "^0.6.8",
  "nuxt-primevue": "^0.2.2"
}

[Rollup error example]

"devDependencies": {
  "@nuxt/devtools": "latest",
  "@nuxt/image": "^1.0.0",
  "nuxt": "^3.9.0"
}

"devDependencies": {
  "@nuxt/devtools": "latest",
  "@nuxt/image": "^1.0.0",
  "nuxt": "^3.9.0"
}

[nuxt image prod] So, based on the examples Nuxt provides, keep nuxt in devDependencies. 2. Are Nuxt modules dependencies or devDependencies? Across the examples, Nuxt modules are almost always listed in devDependencies (when used in a standard Nuxt app, not as libraries): - @nuxt/image in devDependencies [nuxt image prod] - @nuxtjs/tailwindcss in devDependencies [Rollup error example] - @nuxt/devtools in devDependencies [nuxt image prod; DevTools getting started] There is one exception in the GAE answer where everything (including nuxt and modules) was moved to dependencies just to work around that platform’s install behavior, but the author explicitly notes it might not be necessary and did it as a workaround. [GAE deployment] So: for a normal Nuxt app, put Nuxt modules (like @nuxtjs/tailwindcss, @nuxt/devtools, etc.) in devDependencies. 3. “Minimal” Nuxt project dependencies The sources don’t define an official “minimal” set, but typical small apps in the docs look like:

{
  "devDependencies": {
    "nuxt": "^3.x",
    "@nuxt/devtools": "latest"
  }
}

{
  "devDependencies": {
    "nuxt": "^3.x",
    "@nuxt/devtools": "latest"
  }
}

with extra modules like @nuxt/image, @nuxtjs/tailwindcss, etc. also in devDependencies. [nuxt image prod; DevTools getting started] Your own app-specific runtime libraries (e.g. better-auth, better-sqlite3, AWS SDK clients) should be in dependencies, because they’re used by the built server code at runtime. 4. Feedback on your snippet Based on how Nuxt projects in the sources are structured:

"dependencies": {
  "@aws-sdk/client-s3": "^3.700.0",
  "@aws-sdk/s3-request-presigner": "^3.700.0",
  "better-auth": "^1.4.1",
  "better-sqlite3": "^12.4.6",
  "consola": "^3.4.2"
},
"devDependencies": {
  "@types/node": "^24.10.1",
  "@types/better-sqlite3": "^7.6.13",
  "nuxt": "^4.2.1"
}

"dependencies": {
  "@aws-sdk/client-s3": "^3.700.0",
  "@aws-sdk/s3-request-presigner": "^3.700.0",
  "better-auth": "^1.4.1",
  "better-sqlite3": "^12.4.6",
  "consola": "^3.4.2"
},
"devDependencies": {
  "@types/node": "^24.10.1",
  "@types/better-sqlite3": "^7.6.13",
  "nuxt": "^4.2.1"
}

is consistent with the patterns shown in the sources.
However, the entries like "/devtools", "js/tailwindcss", "/icon", "/kit" don’t appear anywhere in the Nuxt docs or examples provided, so I can’t confirm what they are or how they should be classified. If they’re meant to be @nuxt/devtools, @nuxtjs/tailwindcss, nuxt-icon, @nuxt/kit, then the examples show those being used as devDependencies in regular apps. [nuxt image prod; DevTools getting started] Because the knowledge sources don’t contain a single canonical “this is the minimal package.json for Nuxt”, I can’t give a stricter answer than this pattern‑based guidance. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•7d ago

<@239748199818985472> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Gaming

Programming

import defineNitroPlugin or not? Import aliases not working in /server/plugins/*.ts

Did you find this page helpful?