Build fails with compatibilityVersion: 4 and TypeScript templates added via addTemplate #28995

Activity

1. dulnan

   added

   pending triage

   on Sep 14, 2024
2. github-actions commented on Sep 14, 2024

   

   github-actionsbot

   on Sep 14, 2024 – with GitHub Actions

   Contributor

   More actions

   Stackblitz link for the reproduction: Stackblitz
3. vernaillen commented on Sep 14, 2024

   

   vernaillen

   on Sep 14, 2024

   Last edited by vernaillen

   More actions

   This error started appearing after upgrading to Nuxt 3.13.1, in which this new build cache feature was introduced: #28726

   When not in compatibilityVersion 4, the buildCache is disabled by default, and then the error does not occur.
   The error appears when enabling the buildCache or when enabling compatibilityVersion 4.

   I also noticed that the error does not occur when there is no build cache yet from a previous build.
   To be able to build and deploy on vercel I'm using this build command as a workaround:

   rm -rf .nuxt && npx nuxi cleanup && nuxt build
   
4. danielroe commented on Sep 14, 2024

   

   danielroe

   on Sep 14, 2024

   Member

   More actions

   Your code is assuming a relative path from the Nuxt build directory:

   // Import the user's server options file.
   import serverOptions from './../server/myModule.serverOptions'

   https://github.com/dulnan/nuxt4-server-options-reproduction/blob/main/src/module.ts#L34

   There are a couple of problems with this:

   1. if the user has a different server directory, this will not work (this is configurable in nuxt.options.serverDir
   2. if the nuxt buildDir is not at the top level, next to server/, this will not work (this is configurable in nuxt.options.buildDir)

   The reason this happens after turning on compatibilityVersion: 4 is not because buildCache is turned on, but rather because the Nuxt production buildDir is located within node_modules/.cache/nuxt. It is also possible for users to configure this even without compatibilityVersion: 4 and your module should ideally handle both cases.

   However, the fix is simple. Instead of using a hard-coded relative path, you can compute the path relative to nuxt.options.buildDir and nuxt.options.serverDir... Or, you could use an absolute path or even a Nuxt alias.

   I hope this helps 🙏

   Let me know if there's anything else I can help with - and thank you for your work on those modules ❤️

   👍React with 👍1Reacted by Wouter Vernaillen
5. danielroe

   closed this as not plannedon Sep 14, 2024
6. dulnan commented on Sep 21, 2024

   

   dulnan

   on Sep 21, 2024

   Author

   More actions

   Thank you very much for the explanation! I gave it a try with computing the correct relative path using the relative util. That did not work unfortunately.

   I have reduced the example to the absolute minimum, with no complex relative imports at all. I am now generating 2 templates, the existing serverOptions file and a file that exports the type. I'm no longer importing anything from the project's serverDir.

   import {
     defineNuxtModule,
     createResolver,
     addTemplate,
     addServerHandler,
   } from '@nuxt/kit'
   
   // Module options TypeScript interface definition
   export interface ModuleOptions {}
   
   export default defineNuxtModule<ModuleOptions>({
     meta: {
       name: 'my-module',
       configKey: 'myModule',
     },
     // Default configuration options of the Nuxt module
     defaults: {},
     setup(_options, nuxt) {
       // Resolves paths relative to the module.
       const moduleResolver = createResolver(import.meta.url)
   
       // Directly generate the types in the same folder as the serverOptions file.
       addTemplate({
         write: true,
         filename: 'example.types.ts',
         getContents: function () {
           return `
   export type ExampleModuleFunctionType = () => string
   `
         },
       })
   
       const template = addTemplate({
         write: true,
         filename: 'example.serverOptions.ts',
         getContents: function () {
           return `
   // Import type from file in same directory.
   import type { ExampleModuleFunctionType } from './example.types'
   
   export const foobar: ExampleModuleFunctionType = () => {
     return 'Default Value'
   }`
         },
       })
   
       nuxt.options.alias['#my-module-server-options'] = template.dst
       nuxt.options.build.transpile.push(template.dst)
   
       // Add an example server handler.
       addServerHandler({
         handler: moduleResolver.resolve('./runtime/server/test'),
         route: '/api/test',
       })
     },
   })

   This is the generated file that imports the type from a file in the same folder:

   // Import type from file in same directory.
   import type { ExampleModuleFunctionType } from './example.types'
   
   export const foobar: ExampleModuleFunctionType = () => {
     return 'Default Value'
   }

   And the error is still the same:

    ERROR  RollupError: playground/node_modules/.cache/nuxt/.nuxt/example.serverOptions.ts (3:12): Expected ',', got '{' (Note that you need plugins to import files that are not JavaScript)                                                                                                                                                                                                                                nitro 06:57:45
   
   
   1: 
   2: // Import type from file in same directory.
   3: import type { ExampleModuleFunctionType } from './example.types'
                  ^
   4: 
   5: export const foobar: ExampleModuleFunctionType = () => {
   
   
    ERROR  playground/node_modules/.cache/nuxt/.nuxt/example.serverOptions.ts (3:12): Expected ',', got '{' (Note that you need plugins to import files that are not JavaScript)                                                                                                                                                                                                                                                   06:57:45
   
     at getRollupError (node_modules/rollup/dist/es/shared/parseAst.js:392:41)
     at ParseError.initialise (node_modules/rollup/dist/es/shared/node-entry.js:11495:28)
     at convertNode (node_modules/rollup/dist/es/shared/node-entry.js:13193:10)
     at convertProgram (node_modules/rollup/dist/es/shared/node-entry.js:12537:12)
     at Module.setSource (node_modules/rollup/dist/es/shared/node-entry.js:14356:24)
     at async ModuleLoader.addModuleSource (node_modules/rollup/dist/es/shared/node-entry.js:19047:13) 
   
7. danielroe

   reopened this on Sep 21, 2024
8. frasza commented on Sep 23, 2024

   

   frasza

   on Sep 23, 2024

   Contributor

   More actions

   Might not be related, but I found out that my CI docker builds are also failing due to compat 4 option -> #29098
9. dulnan commented on Oct 19, 2024

   

   dulnan

   on Oct 19, 2024

   Author

   More actions

   After some more digging I think that generating a .ts file with addTemplate is likely something that just happened to work previously, but isn't really supported. I looked at various modules and the Nuxt repository itself and haven't found anyone else doing this. The workaround (or likely "proper" way anyway) is to split each template into two, one .mjs and one .d.ts file. Basically only generate non-TS files that can be properly bundled. I will update my modules accordingly.

   👍React with 👍1Reacted by Wouter Vernaillen
10. danielroe commented on Nov 4, 2024

    

    danielroe

    on Nov 4, 2024

    Member

    More actions

    I think the issue here is likely that we don't transpile the buildDir by default (if it's in node_modules, which it is for compatibilityVersion: 4).

    This should be fixed in Nuxt.

    👍React with 👍1Reacted by Torma Gábor
11. danielroe

    added

    🐛 bugSomething isn't working as expectedSomething isn't working as expected

    🔨 p3-minorMinor issue, should be fixedMinor issue, should be fixed

    4.x

    and removed

    pending triage

    on Nov 4, 2024
12. dulnan commented on Mar 21, 2025

    

    dulnan

    on Mar 21, 2025

    Author

    More actions

    Just ran into this problem again, this time because I'm adding a template with the .ts extension where the source is provided by a third party library. There is no easy way for me to split this into two templates with separate .js and .d.ts files. I tried pushing the path of the generated template to nuxt.options.build.transpile, however that did not work. Is there a potential workaround I could do until it's fixed?
13. 7 remaining items

    Load more
14. danielroe

    closed this as completedon Apr 29, 2026
15. Gwynerva commented on May 12, 2026

    

    Gwynerva

    on May 12, 2026

    Last edited by Gwynerva

    Contributor

    More actions

    @danielroe With addTemplate and write: true there is a way to write full TypeScript template with runtime code and types together and use both types and runtime code in Nuxt App.

    // In module setup
    
    addTemplate({
      write: true,
      filename: 'my-module/template.ts
      getContents: () => `export const myArr = [1, 2, 3] as const;`
    })
    
    // In Nuxt App
    
    import { myArr } from '#build/my-module/template';
    
    myArr; // correctly infers type as [1,2,3]
    
    // On server side
    
    import { myArr } from '#build/my-module/template'; // errors "#build" is not accessible from server-side
    import { myArr } from '#my-module-alias/template': // works fine in dev mode, breaks when building if file contains TS code

    However, the server side has no access to templates added via addTemplate. Attempting to bypass this by creating an alias to such a template throws an error during the build — Rolldown complains about the TS code (although it works fine in dev mode). Additionally, addServerTemplate has no write property and does not seem to be detected by the project's TypeScript system, resulting in the error: "Cannot find module ... or its corresponding type declarations."

    Is support for TypeScript templates on the server side planned?

    It is really annoying to manually split everything into .mjs and .d.ts files, and it requires a lot of extra effort to make Nitro pick up these types...
16. github-actions

    reopened this on May 12, 2026
17. github-actions

    added

    pending triage

    possible regression

    on May 12, 2026
18. danielroe commented on May 12, 2026

    

    danielroe

    on May 12, 2026

    Last edited by danielroe

    Member

    More actions

    @Gwynerva you expose types to your nitro + nuxt apps like this:

    addTypeTemplate({
      filename: 'my-module/template.d.ts',
      getContents: () => `export const myArr = [1, 2, 3] as const;`
    }, { nitro: true, nuxt: true })

    does that work for you?
19. Gwynerva commented on May 12, 2026

    

    Gwynerva

    on May 12, 2026

    Last edited by Gwynerva

    Contributor

    More actions

    @danielroe

    In my module setup I have:

      addServerTemplate({
        filename: '#my-module/template.mjs',
        getContents() {
          return `export const test = [1,2,3];`;
        },
      });
    
      addTypeTemplate(
        {
          filename: '#my-module/template.d.ts',
          getContents: () => `export const myArr = [1, 2, 3] as const;`,
        },
        { nuxt: true, nitro: true },
      );

    In server plugin I have:

    import { bootTheiServer } from './boot/process';
    import { test } from '#my-module/template.mjs';
    
    export default defineNitroPlugin(async (nitroApp) => {
      console.log(test);
      THEI_SERVER.console.log('Server plugin started.');
      await bootTheiServer();
    });

    It still errors of missing types but at least the console log works in dev mode.
    Changing the extension to .ts or .js or none at all breaks server and errors "unknown module, treating as external" so the docs there should be corrected as well: https://nuxt.com/docs/4.x/api/kit/templates#creating-a-virtual-file-for-nitro

    I tried to fix all this like a week ago and figured out you need to manually configure tsConfig for types to work which is even worse: 3 actions needed to make TypeScript work on Nitro side. I dropped this idea and tried to trick Nitro with global Nuxt alias pointing to addTemplate file. Works in dev but breaks of TS code when building sadly.

    So no it does not work correctly, no TS support and it still requires painful manual splitting of code with duplicating content.
20. danielroe commented on May 12, 2026

    

    danielroe

    on May 12, 2026

    Member

    More actions

    I tried to fix all this like a week ago and figured out you need to manually configure tsConfig for types to work which is even worse: 3 actions needed to make TypeScript work on Nitro side.

    how did you manually configure tsConfig? what do you mean by this?
21. Gwynerva commented on May 12, 2026

    

    Gwynerva

    on May 12, 2026

    Contributor

    More actions

    Can't remember right now, it was Claude doing this stuff, but I think it added additional include for .d.ts with types for Nitro server tsconfig or something like that.
22. danielroe commented on May 12, 2026

    

    danielroe

    on May 12, 2026

    Last edited by danielroe

    Member

    More actions

    that is exactly what passing the second option: { nitro: true } does. (assuming you have the version of nuxt/kit that the feature is implemented in)
23. Gwynerva commented on May 12, 2026

    

    Gwynerva

    on May 12, 2026

    Last edited by Gwynerva

    Contributor

    More actions

    Well I tried exactly this right now and it fails. I can create a new issue if you want like in 10 minutes.
    Also worth noting that I use layers setup "base project" + ".playground" so maybe this breaks it.
    I am using lastest Nuxt.
24. Gwynerva commented on May 12, 2026

    

    Gwynerva

    on May 12, 2026

    Contributor

    More actions

    @danielroe I was able to reproduce it on clean latest Nuxt version without any layers involved: #35064
25. danielroe commented on May 12, 2026

    

    danielroe

    on May 12, 2026

    Last edited by danielroe

    Member

    More actions

    @Gwynerva I had another look and realised there was an issue with the content of the type template in the example I provided earlier.

    I've provided a better example in the linked issue, which works.
26. danielroe

    closed this as not plannedon May 12, 2026
27. fukcrz commented on May 28, 2026

    

    fukcrz

    on May 28, 2026

    More actions

    @danielroe

    I can still reproduce a similar issue with Nuxt 4.4.5 / Nitro 2.13.4.

    The root cause seems to be that Nuxt moves the production buildDir under node_modules/.cache/nuxt/.nuxt when .nuxt already exists.

    In Nuxt 4.4.5, the related source is in:

    @nuxt/kit/dist/index.mjs

    The relevant logic is:

    const defaultBuildDir = join(nuxtConfig.rootDir, ".nuxt")
    if (
      !opts.overrides?._prepare &&
      !nuxtConfig.dev &&
      !nuxtConfig.buildDir &&
      existsSync(defaultBuildDir)
    ) {
      nuxtConfig.buildDir = join(nuxtConfig.rootDir, "node_modules/.cache/nuxt/.nuxt")
    }

    Then .ts templates generated by addTemplate also live under node_modules, and Nitro/Rollup seems to parse them as plain JS instead of transforming them as TS.

    The related Nitro source seems to be in:

    nitropack/dist/rollup/index.mjs

    where the esbuild transform excludes node_modules:

    const EXCLUDE_REGEXP = /node_modules/

    Example error:

    RollupError: node_modules/.cache/nuxt/.nuxt/resources.ts (1:12): Expected ',', got '{'
    1: import type { Permission } from "../../../../../auth/shared/utils/access"
                   ^

    A temporary workaround is to explicitly set:

    export default defineNuxtConfig({
      buildDir: ".nuxt",
    })

    With this, #build stays in .nuxt, and the TS template parse error disappears.

    Leaving this here in case it helps clarify the failure mode. If this should be tracked as a separate Nuxt/Nitro issue, I can open one with a minimal reproduction.