fix: rewrite #app to nuxt/app in build output

Author: danielroe

src/commands/build.ts

@@ -185,6 +185,10 @@ export default defineCommand({
 
           // Generate types
           await writeTypes(ctx.options.outDir, ctx.options.stub)
+
+          if (!ctx.options.stub) {
+            await rewriteRuntimeTypeAliases(resolve(ctx.options.outDir, 'runtime'))
+          }
         },
         async 'build:done'(ctx) {
           const logs = [...ctx.warnings].filter(l => l.startsWith('Potential missing package.json files:'))
@@ -277,6 +281,34 @@ ${moduleReExports.filter(e => e.type === 'star').map(e => `\nexport * from '${e.
   await fsp.writeFile(dtsFile, dtsContents, 'utf8')
 }
 
+const DECLARATION_RE = /\.d\.[^/]*ts$/
+
+// `#app`/`#app/*` are build-time-only aliases with no package resolution, so leaking
+// them into emitted declarations breaks `tsc`/`attw` for consumers. `nuxt/app` is the
+// resolvable public entry and re-exports the `#app/*` symbols.
+async function rewriteRuntimeTypeAliases(runtimeDir: string) {
+  if (!existsSync(runtimeDir)) {
+    return
+  }
+
+  const entries = await fsp.readdir(runtimeDir, { recursive: true })
+  await Promise.all(entries.map(async (entry) => {
+    if (!DECLARATION_RE.test(entry)) {
+      return
+    }
+
+    const file = join(runtimeDir, entry)
+    const contents = await fsp.readFile(file, 'utf8')
+    const rewritten = contents
+      .replace(/import\("#app(?:\/[^"]*)?"\)/g, 'import("nuxt/app")')
+      .replace(/(\bfrom\s*)(['"])#app(?:\/[^'"]*)?\2/g, '$1$2nuxt/app$2')
+
+    if (rewritten !== contents) {
+      await fsp.writeFile(file, rewritten, 'utf8')
+    }
+  }))
+}
+
 async function loadTSCompilerOptions(path: string): Promise<NonNullable<TSConfig['compilerOptions']>> {
   const config = await parse(path)
   const resolvedCompilerOptions = config?.tsconfig.compilerOptions || {}

test/build.spec.ts

@@ -120,8 +120,7 @@ describe('module builder', () => {
 
   it('should generate typed plugin', async () => {
     const pluginDts = await readFile(join(distDir, 'runtime/plugins/plugin.d.ts'), 'utf-8')
-    // aliases flip between `nuxt/app` and `#app` in repo vs ecosystem-ci
-    const appAlias = `import\\("(?:nuxt/app|#app)"\\)`
+    const appAlias = `import\\("nuxt/app"\\)`
     expect(pluginDts).toMatch(/^export type SharedTypeFromRuntime = 'shared-type';$/m)
     expect(pluginDts).toMatch(
       new RegExp(
@@ -131,6 +130,16 @@ describe('module builder', () => {
     expect(pluginDts).toMatch(/^export default _default;$/m)
   })
 
+  it('should not leak build-only virtual aliases into emitted runtime declarations', async () => {
+    const files = await readdir(runtimeDir, { recursive: true })
+    const declarations = files.filter(file => /\.d\.[^/]*ts$/.test(file))
+    expect(declarations.length).toBeGreaterThan(0)
+    for (const file of declarations) {
+      const contents = await readFile(join(runtimeDir, file), 'utf-8')
+      expect(contents, file).not.toMatch(/(["'])#app(?:\/[^"']*)?\1/)
+    }
+  })
+
   it('should correctly add extensions to imports from runtime/ directory', async () => {
     const moduleDts = await readFile(join(distDir, 'module.d.mts'), 'utf-8')
     const runtimeImport = findStaticImports(moduleDts).find(i => i.specifier.includes('runtime'))
@@ -158,16 +167,15 @@ describe('module builder', () => {
 
   it('should generate wrapped composables', async () => {
     const componentFile = await readFile(join(distDir, 'runtime/composables/useWrappedFetch.d.ts'), 'utf-8')
-    // aliases flip between `nuxt/app` and `#app` in repo vs ecosystem-ci
     // `null` vs `undefined` error-type difference between Nuxt 3 and 4+ is intentional.
     // Nuxt 4+ moved the default error from `FetchError` to `NuxtError<unknown>` (nuxt/nuxt#35346); accept both until it lands in a release.
     const expectedErrorType = satisfies(nuxtVersion, '^3') ? 'null' : 'undefined'
     const errorType = satisfies(nuxtVersion, '^3')
       ? 'import\\("ofetch"\\)\\.FetchError<any>'
-      : '(?:import\\("ofetch"\\)\\.FetchError<any>|import\\("(?:nuxt/app|#app)"\\)\\.NuxtError<unknown>)'
+      : '(?:import\\("ofetch"\\)\\.FetchError<any>|import\\("nuxt/app"\\)\\.NuxtError<unknown>)'
     expect(componentFile).toMatch(
       new RegExp(
-        `^export declare const useWrappedFetch: \\(\\) => import\\("(?:nuxt/app|#app)"\\)\\.AsyncData<unknown, ${errorType} \\| ${expectedErrorType}>;\\s*$`,
+        `^export declare const useWrappedFetch: \\(\\) => import\\("nuxt/app"\\)\\.AsyncData<unknown, ${errorType} \\| ${expectedErrorType}>;\\s*$`,
       ),
     )
   })