Server alias not working - '~~/server' or '#server' | Nuxt | Page 1

shadow kelp Feb 11, 2026, 8:28 AM

#

I'm having a lot of issues with the server aliases.

Considerations

My server folder structure:
- server
  - api
  - middleware
  - types
  - utils
Both alias work in all folder except in the middleware folder!
If i create a folder "server/services" the alias don't work!

My procedures

Every change that i tried, after i use:
- npx nuxi prepare
- Restarted TypeScript server (vsc)
- Reload window (vsc)
In some cases rebuild the app
- Remove the folders "node_modules", ".nuxt" and the file pnpm-lock.yaml
- After "pnpm install"

My configurations files

sage oxideBOT Feb 11, 2026, 8:28 AM

#

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

#

Nuxt’s server alias behavior has recently changed, and the knowledge sources only partially cover it, so I can’t fully diagnose your exact project setup. But there are a few confirmed points and known issues that match what you’re seeing.

1. Prefer `#server` over `~~/server`

Nuxt 4 introduced a dedicated #server alias for imports inside the server directory, e.g.:

// server/api/users/[id].ts
import { helper } from '#server/utils/helper'

This was added specifically to avoid problems with ~ / ~~ pointing to app / project root and conflicting between Nuxt and Nitro. [feat #server]

The docs are being updated to consistently recommend #server instead of ~/server. [docs server alias]

So for anything under server (api, middleware, utils, types, services, etc.), you should be using:

import { something } from '#server/utils/something'
import type { MyType } from '#server/types/my-type'

2. `#server` only works inside the server context

#server is meant for server code only and is protected from being used in client/shared code. [feat #server]

From your description, it works in server/api and server/utils but not in server/middleware and server/services. That matches a known issue where #server was not resolving correctly in some server locations (including middleware) even though the docs say it should. [issue 33953]

In that issue, imports like:

// server/api/helloWorld.ts
import { hello } from '#server/utils/hello'

failed with:

#

"#server/utils/hello" is imported by "server/api/helloWorld.ts", but could not be resolved – treating it as an external dependency. [issue 33953]

So if you’re on a Nuxt version around 4.2.x / Nitro 2.12.x, you may be hitting the same bug.

3. `~` / `~~` aliases and `tsconfig.server.json`

There was also a bug where the generated .nuxt/tsconfig.server.json mapped ~/* to ../app/*, which is not ideal for server imports and caused confusion about how to import from server. [issue 33853]

The fix for that issue was precisely to introduce #server and recommend using it instead of relying on ~ / ~~ for server code. [feat #server]

So:

~ / @ → app directory
~~ / @@ → project root
#server → server directory (intended for all server subfolders)

4. What you can do right now

Based on the issues and PRs:

Use #server everywhere in server/* and avoid ~~/server for server-internal imports.
Check your Nuxt version: if you’re on a version before or around the introduction of #server, upgrade to a Nuxt 4 release that includes PR #33870. [feat #server]
If you’re already on a recent 4.x and #server still fails specifically in server/middleware or server/services, you’re likely hitting the same unresolved bug as in issue #33953. In that case, the only fully confirmed workaround from the issue discussion is to fall back to relative imports in those problematic files, e.g.:
```
// server/middleware/auth.ts
import { verifyToken } from '../utils/auth'
```
[issue 33853; issue 33953]

#

Because the knowledge sources don’t include the final fix for `#server` in middleware/services, I can’t say with certainty which exact Nuxt version fully resolves it. If you share your Nuxt/Nitro versions and a minimal example of a failing import (file path + import line), I can map it more precisely to the referenced issues.

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

#

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

shadow kelp Feb 11, 2026, 8:31 AM

#

My files

nuxt.config.ts

import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
  'compatibilityDate': '2026-02-08',
  'devtools': { enabled: false },
  'ssr': false,
  'sourcemap': {
    'client': true,
    'server': true
  },
  'components': {
    'dirs': []
  },
  'css': ['~/assets/css/main.css'],
  'modules': [
    '@nuxt/image',
    '@nuxt/test-utils/module',
    '@nuxt/ui',
    'nuxt-auth-utils',
    '@pinia/nuxt'
  ],
  'pinia': {
    'storesDirs': ['./app/stores/**']
  },
  'runtimeConfig': {
    My env variables    
      // Public keys that are exposed to the client
    'public': {
      // apiBase: process.env.NUXT_PUBLIC_API_BASE || '/api/'
    },
  }
})

#

package.json

{
  "name": "kitchen-pantry",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "nuxt build",
    "dev": "nuxt dev",
    "generate": "nuxt generate",
    "preview": "nuxt preview",
    "postinstall": "nuxt prepare"
  },
  "dependencies": {
    "@nuxt/image": "^2.0.0",
    "@nuxt/test-utils": "^4.0.0",
    "@nuxt/ui": "^4.4.0",
    "@pinia/nuxt": "^0.11.3",
    "@sparticuz/chromium": "^143.0.4",
    "bcryptjs": "^3.0.3",
    "chart.js": "^4.5.1",
    "chartjs-plugin-datalabels": "^2.2.0",
    "fast-copy": "^4.0.2",
    "mongoose": "^9.2.0",
    "nuxt": "^4.3.1",
    "nuxt-auth-utils": "^0.5.28",
    "pinia": "^3.0.4",
    "puppeteer-core": "^24.37.2",
    "tailwindcss": "^4.1.18",
    "typescript": "^5.9.3",
    "uuid": "^13.0.0",
    "vue": "^3.5.27",
    "vue-router": "^5.0.2",
    "xlsx": "^0.18.5",
    "zod": "^4.3.6"
  },
  "devDependencies": {
    "@iconify-json/heroicons": "^1.2.3",
    "@iconify-json/ic": "^1.2.4",
    "@iconify-json/mdi": "^1.2.3",
    "@tanstack/vue-table": "^8.21.3",
    "@types/lodash": "^4.17.23",
    "@types/node-cron": "^3.0.11",
    "@types/nodemailer": "^7.0.9",
    "@vue/test-utils": "^2.4.6",
    "happy-dom": "^20.6.0",
    "nodemailer": "^8.0.1",
    "playwright-core": "^1.58.2",
    "puppeteer": "^24.37.2",
    "vitest": "^4.0.18"
  }
}

tsconfig.json

{
  // https://nuxt.com/docs/guide/concepts/typescript
  "extends": "./.nuxt/tsconfig.json"
}

spark grove Feb 11, 2026, 3:20 PM

#

do you have a reproduction? are you importing from your server directory anywhere else in your app?

shadow kelp Feb 11, 2026, 3:36 PM

#

Hi @spark grove !!
I don't know how to reproduce the issue, i found the issue was having inside folder "server/something/..." two files with the same name
This issue is solved, but now i'm fighting with the issue, that any file in the server folder "/server/nodemailer/reports/..." only works the relative imports, all the alias imports and all the auto imported nuxt commands (createError, etc) are unknown.
I'm frustratred!!! I've clean the app multiple times, also after every try i use "npx nuxt prepare", resest typescript server, reload new window.... and nothing stops this issue!

I'm thinking to refactor all the app, hundred of files, to declare all the imports and using relative imports, and disable auto imports.

I forgot to mention, this also ocurrs in all my server middlewares, i have to use relative imports and don't recognize the "defineEventHandler"!

import { appConn, productionsConn, kitchenPantryConn } from '../api/mongoose/mongooseConnections'

export default defineEventHandler(async (event: any) => {
...
}

spark grove Feb 11, 2026, 3:57 PM

#

probably this isn't actually a problem within your server

#

probably you're importing from your server into your nuxt.config, or into your shared/ directory

#

and in this case, those auto-imports aren't known within the nuxt.config/module context, and they don't work in the shared context, so the types are unknown.

#

it's probably revealing that you are importing cross-context, which is really an architectural issue to fix

shadow kelp Feb 11, 2026, 4:22 PM

#

Sorry but i don't understood your explanation, are you referring to the middleware folder? Do you know where I can find documentation regarding this type of issue?

spark grove Feb 11, 2026, 4:27 PM

#

no, I think you are importing something from server/ from a file which is outside this directory.

#

here are some docs: https://nuxt.com/docs/4.x/guide/concepts/typescript#project-references

Nuxt

TypeScript · Nuxt Concepts v4

Nuxt is fully typed and provides helpful shortcuts to ensure you have access to accurate type information when you are coding.

shadow kelp Feb 12, 2026, 5:26 AM

#

Hi @spark grove , sorry for not saying nothing else, but i was very tired and frustrated, nothing then a good night's sleep don't resolve!
After your pointing me the direction, today when i wake up, just goes to the tsconfig.json file, and updated from:

Old configuration

{
  // https://nuxt.com/docs/guide/concepts/typescript
  "extends": [
    "./.nuxt/tsconfig.json"
  ]
}

New configuration

{
  // 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"
    }
  ]
}

That's all...all issues solved!

Nothing a good night's sleep can't fix and of course your help.

All problems solved!

Thank you again, my passion for Nuxt has been rekindled, I was very disappointed and frustrated. 👍👍

#Server alias not working - '~~/server' or '#server'