Nuxt•3mo ago

Properly export types from a custom Nuxt module

Hi, I have a custom Nuxt module with some type declarations that I'd like users to be able to import: my types.ts files inside src/ are ignored when packaging though, and they do not make it to the dist/ directory. I am having trouble finding the right docs about this, can someone point me to the right direction?

16 Replies

kapa.ai•3mo ago

Hi @nborges. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave: ---------------------- To properly export types from a custom Nuxt module so that users can import them, you should ensure that your type declarations are included in your module's published package and registered with Nuxt's type system. Here are the recommended steps based on the official Nuxt documentation and recent updates: 1. Use addTypeTemplate in Your Module
Nuxt provides the addTypeTemplate utility to write type declaration files to the user's project and add references to them in the generated nuxt.d.ts file. This ensures your types are available to consumers of your module:

   import { defineNuxtModule, addTypeTemplate } from '@nuxt/kit'

   export default defineNuxtModule({
     setup () {
       addTypeTemplate({
         filename: 'types/my-module.d.ts',
         getContents: () => `// Generated by my-module
           export interface MyType { foo: string }
           export type MyOtherType = number;
           export {}`
       })
     }
   })

   import { defineNuxtModule, addTypeTemplate } from '@nuxt/kit'

   export default defineNuxtModule({
     setup () {
       addTypeTemplate({
         filename: 'types/my-module.d.ts',
         getContents: () => `// Generated by my-module
           export interface MyType { foo: string }
           export type MyOtherType = number;
           export {}`
       })
     }
   })

This will generate a types/my-module.d.ts file in the user's project and make the types available for import.
See: Adding Type Declarations 2. Ensure Types Are Included in Your Package
If you want users to import types directly from your module (e.g., import type { MyType } from 'my-nuxt-module'), make sure your build process copies .d.ts files from src/ to dist/. This is a common issue—by default, only compiled JavaScript files may be copied.
A recent Nuxt PR specifically addressed including types in the dist folder for modules:
fix(kit): include types in module dist/runtime/ in tsconfig file You may need to adjust your build configuration (e.g., using tsc --declaration or a custom copy script) to ensure .d.ts files are present in your published dist/. 3. Reference Types in Your Module's package.json
Set the types or typings field in your package.json to point to your main type declaration file (e.g., "types": "./dist/types/index.d.ts"). 4. Document How to Import Types
In your module's documentation, show users how to import your types, either from the Nuxt auto-generated types (if using addTypeTemplate) or directly from your module package. Summary:
- Use addTypeTemplate to inject types into the user's Nuxt project. - Ensure your build process copies .d.ts files to dist/. - Reference your types in package.json. If you follow these steps, your types should be available for users to import as intended. If you need more granular control, you can also use the prepare:types Nuxt hook to inject type references manually. For more details, see the official Nuxt documentation on Adding Type Declarations and the related PR about including types in dist. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

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

nborgesOP•3mo ago

@kapa.ai I don't want my types to be global though: I want users to be able to import them

kapa.ai•3mo ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- To allow users to import your types (rather than making them global), you need to ensure that your type declaration files (.d.ts) are included in your published module's dist/ directory. This way, users can import types directly from your module, e.g., import type { MyType } from 'my-nuxt-module'. Key points from the knowledge sources: - There was a recent fix in Nuxt to ensure that types in the dist folder are included in the module's tsconfig file, which helps with type resolution for consumers of your module. However, you still need to make sure your build process copies .d.ts files from src/ to dist/ when you publish your module. This is not handled automatically by Nuxt—you must configure your build tool (like tsc or a copy script) to do this. See the related PR:
fix(kit): include types in module dist/runtime/ in tsconfig file - The Nuxt documentation on Adding Type Declarations focuses on using addTypeTemplate to inject types into the user's project, which is useful for global augmentation or auto-imports, but not for direct imports. What you should do: 1. Export your types in .d.ts files in your src/ directory. 2. Ensure your build process copies these .d.ts files to your dist/ directory.
This is essential—otherwise, the types will not be available to consumers. 3. Reference your types in your module's package.json using the types or typings field, e.g.:

   {
     "types": "./dist/types/index.d.ts"
   }

   {
     "types": "./dist/types/index.d.ts"
   }

4. Document for users how to import your types:

   import type { MyType } from 'my-nuxt-module'

   import type { MyType } from 'my-nuxt-module'

Summary:
You do not need to use addTypeTemplate for this use case. Just make sure your type files are present in your published package and referenced correctly. The knowledge sources confirm the importance of including types in dist/ for module consumers, but do not provide a Nuxt-specific mechanism for direct type imports beyond standard TypeScript packaging practices fix(kit): include types in module dist/runtime/ in tsconfig file. If you need more details on configuring your build process, you may need to consult TypeScript or your bundler's documentation, as the Nuxt docs do not cover this aspect in depth. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

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

nborgesOP•3mo ago

@kapa.ai Please, explain step 2

kapa.ai•3mo ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Certainly! Step 2 is about ensuring your .d.ts type declaration files are present in your module's dist/ directory when you publish your Nuxt module, so users can import them. However, the knowledge sources do not provide detailed, Nuxt-specific instructions for how to configure your build process to copy .d.ts files from src/ to dist/. They do confirm that including types in the dist folder is important for module consumers, as seen in the Nuxt PR that addresses including types in the module's dist/runtime/ in the tsconfig file fix(kit): include types in module dist/runtime/ in tsconfig file. If you are using the Nuxt module builder or a standard TypeScript setup, you will need to ensure your build process outputs the type files to dist/, but the exact steps for this are not covered in the provided documentation. In summary:
The knowledge sources confirm the importance of having your type declarations in the dist/ directory for consumers to import, but do not provide explicit, step-by-step instructions for configuring your build process to achieve this. If you need more details, you may need to consult TypeScript or your bundler's documentation. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3mo ago

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

harlan•3mo ago

easiest is subpath exports

harlan•3mo ago

https://github.com/nuxt-modules/sitemap/blob/main/package.json#L30

GitHub

sitemap/package.json at main · nuxt-modules/sitemap

Powerfully flexible XML Sitemaps that integrate seamlessly, for Nuxt. - nuxt-modules/sitemap

harlan•3mo ago

nuxt ui exports like this https://github.com/nuxt/ui/blob/v3/src/module.ts#L7

GitHub

ui/src/module.ts at v3 · nuxt/ui

The Intuitive Vue UI Library powered by Reka UI & Tailwind CSS. - nuxt/ui

harlan•3mo ago

but i have mixed success

nborgesOP•3mo ago

One thing I'm having trouble understanding is that unless I re-export my types from module.ts they are not picked up at all. I'm not that savy about packaging, so I'm not sure what I am doing wrong (Thanks, I'm taking a look at this right now) If I do this, I get a nice "Out of memory" error 🥲

harlan•3mo ago

try subpaths

nborgesOP•3mo ago

But it seems to me that the subpath approach is the default when using npm create nuxt -- -t module <module-name> I have the following in my package.json:

  "exports": {
   ".": {
      "types": "./dist/types.d.mts",
      "import": "./dist/module.mjs"
    }
  },

  "exports": {
   ".": {
      "types": "./dist/types.d.mts",
      "import": "./dist/module.mjs"
    }
  },

Which is the default for the module starter. But in ./dist/types.d.mts my types are not included after the build... I'm clearly missing something here My types are defined in a single place: src/types/index.ts

harlan•3mo ago

a subpath is a path besides . i.e ./types see my first link

Gaming

Programming

Properly export types from a custom Nuxt module

Did you find this page helpful?