N
Nuxt•4mo ago
rd

Type declarations with `addServerTemplate` in a module

When using addServerTemplate, how should I add type declarations? The docs here only explain how to do this for addTemplate. Thanks!
Nuxt
Module Author Guide · Nuxt Advanced v4
Learn how to create a Nuxt Module to integrate, enhance or extend any Nuxt applications.
11 Replies
kapa.ai
kapa.ai•4mo ago
Hi @rd. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- When using addServerTemplate in a Nuxt module, the official documentation does not provide a direct method for adding type declarations specifically for server templates. The documented approach for type declarations is with addTypeTemplate, which is designed to generate .d.ts files and register them for type augmentation in both Nuxt and Nitro contexts. This is separate from addServerTemplate, which is used to generate server-only virtual files for Nitro and does not handle type declarations by itself. If you want to add type declarations for code generated with addServerTemplate, you should use addTypeTemplate to generate the corresponding .d.ts file. You can control whether the type is available in the Nuxt context, the Nitro context, or both by passing the appropriate options to addTypeTemplate: 
import { defineNuxtModule, addServerTemplate, addTypeTemplate } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addServerTemplate({
      filename: '#my-module/test.mjs',
      getContents () {
        return 'export const test = 123'
      },
    })

    addTypeTemplate({
      filename: 'types/my-module-test.d.ts',
      getContents: () => `
        declare module '#my-module/test' {
          export const test: number
        }
      `
    }, {
      nitro: true // ensures the type is available in the Nitro (server) context
    })
  },
})
import { defineNuxtModule, addServerTemplate, addTypeTemplate } from '@nuxt/kit'

export default defineNuxtModule({
  setup () {
    addServerTemplate({
      filename: '#my-module/test.mjs',
      getContents () {
        return 'export const test = 123'
      },
    })

    addTypeTemplate({
      filename: 'types/my-module-test.d.ts',
      getContents: () => `
        declare module '#my-module/test' {
          export const test: number
        }
      `
    }, {
      nitro: true // ensures the type is available in the Nitro (server) context
    })
  },
})
This way, your server template is available for import in server code, and the type declaration is available for type checking and IDE support in the Nitro context addTypeTemplate API docs. Summary:
- Use addServerTemplate to generate server-only virtual files. - Use addTypeTemplate to generate and register type declarations for those files, specifying { nitro: true } if you want the types available in the server context. The documentation does not mention any other method for associating type declarations with files generated by addServerTemplate addServerTemplate API docs. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
kapa.ai
kapa.ai•4mo ago
<@336916275705937921> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
rd
rdOP•4mo ago
@kapa.ai So, this should work? Can't seem to make it 
addServerTemplate({
  filename: 'nitro-build-info.mjs',
  getContents: () =>
    `export const buildDir = ${JSON.stringify(nuxt.options.buildDir)}`,
})

addTypeTemplate(
  {
    filename: 'types/nitro-build-info.d.ts',
    getContents: () => `
    declare module '#nitro-build-info' {
      export const buildDir: string
    }
  `,
  },
  {
    nitro: true,
    node: true,
  }
)
addServerTemplate({
  filename: 'nitro-build-info.mjs',
  getContents: () =>
    `export const buildDir = ${JSON.stringify(nuxt.options.buildDir)}`,
})

addTypeTemplate(
  {
    filename: 'types/nitro-build-info.d.ts',
    getContents: () => `
    declare module '#nitro-build-info' {
      export const buildDir: string
    }
  `,
  },
  {
    nitro: true,
    node: true,
  }
)
kapa.ai
kapa.ai•4mo ago
Let me check the knowledge base for you again. One moment! :books: ---------------------- Based on the official Nuxt documentation and related sources, your approach is correct in principle: you should use addServerTemplate to generate the server-only virtual file, and addTypeTemplate to generate the corresponding type declaration, specifying { nitro: true } to make the type available in the Nitro (server) context addTypeTemplate API docs. However, there are a few things to double-check: 1. Module Path Consistency:
The module path in your type declaration (#nitro-build-info) must match exactly how you import the file in your server code. Since your addServerTemplate uses filename: 'nitro-build-info.mjs', you should import it as #nitro-build-info (without the .mjs extension) in your server files. 2. Type Template Context:
The node option in the context object is not documented in the official Nuxt 4 docs. Only nuxt and nitro are supported contexts according to the documentation. Using node: true may not have any effect and could potentially cause issues. Stick to { nitro: true } for server context types addTypeTemplate API docs. 3. Type Template Location:
Ensure your type template is placed in a directory that Nuxt recognizes for type augmentation (e.g., types/). 4. Rebuild and Restart:
After making changes to templates or types, always restart your Nuxt dev server to ensure the virtual files and types are regenerated and picked up by the IDE and build process. Example (adjusted): 
addServerTemplate({
  filename: 'nitro-build-info.mjs',
  getContents: () =>
    `export const buildDir = ${JSON.stringify(nuxt.options.buildDir)}`,
})
addTypeTemplate(
  {
    filename: 'types/nitro-build-info.d.ts',
    getContents: () => `
    declare module '#nitro-build-info' {
      export const buildDir: string
    }
  `,
  },
  {
    nitro: true, // Only use nitro context for server types
  }
)
addServerTemplate({
  filename: 'nitro-build-info.mjs',
  getContents: () =>
    `export const buildDir = ${JSON.stringify(nuxt.options.buildDir)}`,
})
addTypeTemplate(
  {
    filename: 'types/nitro-build-info.d.ts',
    getContents: () => `
    declare module '#nitro-build-info' {
      export const buildDir: string
    }
  `,
  },
  {
    nitro: true, // Only use nitro context for server types
  }
)
Summary:
- Your approach matches the documented pattern. - Remove node: true from the context, as it is not documented. - Make sure you import the module as #nitro-build-info in your server code. - Restart your dev server after changes. If it still doesn't work, the knowledge sources do not provide further troubleshooting steps for this specific scenario. If you encounter issues, double-check the generated files in .nuxt and ensure your IDE is picking up the new types addTypeTemplate API docs. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
kapa.ai
kapa.ai•4mo ago
<@336916275705937921> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
rd
rdOP•4mo ago
@kapa.ai of course! Thanks. 
addServerTemplate({
  filename: '#nitro-build-info',
  getContents: () =>
    `export const buildDir = ${JSON.stringify(nuxt.options.buildDir)}`,
})

addTypeTemplate(
  {
    filename: 'types/nitro-build-info.d.ts',
    getContents: () => `
    declare module '#nitro-build-info' {
      export const buildDir: string
    }
  `,
  },
  {
    nitro: true,
    node: true,
  }
)
addServerTemplate({
  filename: '#nitro-build-info',
  getContents: () =>
    `export const buildDir = ${JSON.stringify(nuxt.options.buildDir)}`,
})

addTypeTemplate(
  {
    filename: 'types/nitro-build-info.d.ts',
    getContents: () => `
    declare module '#nitro-build-info' {
      export const buildDir: string
    }
  `,
  },
  {
    nitro: true,
    node: true,
  }
)
kapa.ai
kapa.ai•4mo ago
Let me check the knowledge base for you again. One moment! :books: ---------------------- Your approach is almost correct, but there are a couple of important details to ensure it works as intended, based strictly on the Nuxt documentation: 1. Filename for addServerTemplate:
The filename should not start with a #. The # prefix is used when importing the virtual file, not when defining it. For example, use 'nitro-build-info.mjs' as the filename in addServerTemplate. When importing, you would use #nitro-build-info. 2. Type Template Context:
The addTypeTemplate context only officially supports nuxt and nitro as options. There is no documentation for a node context, so you should omit node: true and use only { nitro: true } if you want the type available in the Nitro (server) context addTypeTemplate API docs. 3. Import Path:
When importing in your server code, use #nitro-build-info (without the .mjs extension). Corrected Example: 
addServerTemplate({
  filename: 'nitro-build-info.mjs',
  getContents: () =>
    `export const buildDir = ${JSON.stringify(nuxt.options.buildDir)}`,
})

addTypeTemplate(
  {
    filename: 'types/nitro-build-info.d.ts',
    getContents: () => `
    declare module '#nitro-build-info' {
      export const buildDir: string
    }
  `,
  },
  {
    nitro: true, // Only use nitro context for server types
  }
)
addServerTemplate({
  filename: 'nitro-build-info.mjs',
  getContents: () =>
    `export const buildDir = ${JSON.stringify(nuxt.options.buildDir)}`,
})

addTypeTemplate(
  {
    filename: 'types/nitro-build-info.d.ts',
    getContents: () => `
    declare module '#nitro-build-info' {
      export const buildDir: string
    }
  `,
  },
  {
    nitro: true, // Only use nitro context for server types
  }
)
You can then import in your server code like this: 
import { buildDir } from '#nitro-build-info'
import { buildDir } from '#nitro-build-info'
Summary:
- Do not prefix the filename in addServerTemplate with #. - Only use { nitro: true } for the type template context. - Import using the # prefix in your server code. This matches the documented usage for both addServerTemplate and addTypeTemplate addServerTemplate API docs addTypeTemplate API docs. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
kapa.ai
kapa.ai•4mo ago
<@336916275705937921> Kapa.ai is still learning and improving, please let me know how I did by reacting below.
rd
rdOP•4mo ago
@kapa.ai Follow up... addServerTemplate doesn't support src like addTemplate. Why?
kapa.ai
kapa.ai•4mo ago
Let me check the knowledge base for you again. One moment! :books: ---------------------- The knowledge sources do not explicitly state why addServerTemplate does not support a src property like addTemplate. The documentation for addServerTemplate only describes the use of filename and getContents, and does not mention support for a src option or provide reasoning for this design choice addServerTemplate API docs. If you need to generate server templates from a file, you would need to manually read the file contents and provide them to getContents. There is no documented explanation for the absence of a src property in addServerTemplate. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------
kapa.ai
kapa.ai•4mo ago
<@336916275705937921> Kapa.ai is still learning and improving, please let me know how I did by reacting below.

Did you find this page helpful?