Nuxt•3w ago

Adding server only imports

In a module, is it possible to add a function that can be imported from #imports but only on the server/in a Nitro context? As in, I don't want those imports available on the client/Nuxt app.

14 Replies

kapa.ai•3w 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: ---------------------- Yes, in a Nuxt module, you can add imports that are only available in the server/Nitro context (not on the client or in the Nuxt app) by using the addServerImports or addServerImportsDir utilities from @nuxt/kit. - addServerImports: This function allows you to specify individual imports that will be auto-imported and available only in the Nitro/server context. These imports will not be available in the client or Vue app context.

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

  export default defineNuxtModule({
    setup() {
      addServerImports({
        name: 'myServerFunction',
        as: 'myServerFunction',
        from: '#build/my-server-function'
      })
    }
  })

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

  export default defineNuxtModule({
    setup() {
      addServerImports({
        name: 'myServerFunction',
        as: 'myServerFunction',
        from: '#build/my-server-function'
      })
    }
  })

This makes myServerFunction available for auto-import from #imports, but only in server-side code (e.g., server/api, server/middleware, etc.) and not in client-side or Vue components addServerImports. - addServerImportsDir: If you want to auto-import all exports from a directory (e.g., a set of server-only composables or utilities), you can use this function:

  import { defineNuxtModule, createResolver, addServerImportsDir } from '@nuxt/kit'

  export default defineNuxtModule({
    setup() {
      const { resolve } = createResolver(import.meta.url)
      addServerImportsDir(resolve('./runtime/server/composables'))
    }
  })

  import { defineNuxtModule, createResolver, addServerImportsDir } from '@nuxt/kit'

  export default defineNuxtModule({
    setup() {
      const { resolve } = createResolver(import.meta.url)
      addServerImportsDir(resolve('./runtime/server/composables'))
    }
  })

All exports from the specified directory will be available for auto-import in the Nitro/server context only addServerImportsDir. Summary:
Functions registered via addServerImports or addServerImportsDir are only available in the server/Nitro context and will not be exposed to the client or Nuxt app context. This is the recommended way to provide server-only auto-imports in a Nuxt module. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3w ago

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

rdOP•3w ago

Lol, wow. How did I miss that 😆 @kapa.ai And if I want to import them explicitly from #imports?

kapa.ai•3w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- Yes, when you use addServerImports or addServerImportsDir in your module, the functions you register will be available for explicit import from #imports, but only in the server/Nitro context. This means you can do:

import { myServerFunction } from '#imports'

import { myServerFunction } from '#imports'

inside files that run in the server context (such as server/api, server/routes, server/middleware, etc.). These imports will not be available in the client or Vue app context addServerImports addServerImportsDir. If you try to import them from #imports in client-side code, they will not be available. This ensures your server-only utilities remain server-only. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3w ago

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

rdOP•3w ago

@kapa.ai Hm, this doesn't seem to be the case? I don't need to update the Nitro config manually?

kapa.ai•3w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- You do not need to update the Nitro config manually to make server-only imports available from #imports in the server context. When you use addServerImports or addServerImportsDir in your Nuxt module, these functions are registered for auto-import in Nitro/server context, and you can explicitly import them from #imports in server files (like server/api, server/middleware, etc.) without further Nitro configuration addServerImports addServerImportsDir. There is no mention in the official documentation or recent PRs that you need to manually update the Nitro config for this to work. The registration via Nuxt Kit utilities is sufficient. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3w ago

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

rdOP•3w ago

@kapa.ai It seems there may be known typing issues? If I were to update the nitro config directly, how should I do that?

kapa.ai•3w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- There have been some known typing issues related to server-only imports and type sharing between contexts in Nuxt 4, particularly around the availability of types from the shared/ directory in server routes and Nitro context. For example, there was a bug where .nuxt/tsconfig.server.json did not include shared types, which was fixed by explicitly adding the ../shared/**/*.d.ts pattern to the include array in the server tsconfig generation. This ensures that types defined in shared/ are available in server routes and Nitro context (include shared types in tsconfig.server.json). If you need to update the Nitro config directly (for example, to add custom storage, plugins, or other advanced Nitro features), you can do so in your nuxt.config.ts using the nitro key:

export default defineNuxtConfig({
  nitro: {
    // Nitro configuration options here
    // For example, to add custom storage:
    storage: {
      redis: {
        driver: 'redis',
        port: 6379,
        host: "127.0.0.1",
        // ...other options
      }
    }
  }
})

export default defineNuxtConfig({
  nitro: {
    // Nitro configuration options here
    // For example, to add custom storage:
    storage: {
      redis: {
        driver: 'redis',
        port: 6379,
        host: "127.0.0.1",
        // ...other options
      }
    }
  }
})

Advanced Nitro usage However, for type issues specifically related to auto-imports and server-only utilities, the recommended approach is to ensure your types are placed in the correct directory (shared/ for shared types, server/ for server-only types) and that your project is using the latest Nuxt version, as recent updates have improved type sharing and auto-import declarations (include shared types in tsconfig.server.json). If you encounter issues with types not being recognized, double-check that your tsconfig.server.json includes the shared types pattern, and consider adopting the new TypeScript project references approach as described in the upgrade guide (TypeScript Configuration Splitting). ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3w ago

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

rdOP•3w ago

@kapa.ai Yep, it seems that unless I add it using addImports too, the types are missing. There is only one imports.d.ts file generated in the .nuxt folder, so I assume that's why

kapa.ai•3w ago

Let me check the knowledge base for you again. One moment! :books: ---------------------- You are correct that there have been issues with type declarations for server-only imports in Nuxt 4. The knowledge sources confirm that, by default, Nuxt generates a single imports.d.ts file in .nuxt for auto-imports, and this can lead to missing types for server-only imports unless additional steps are taken. A recent improvement introduced a dedicated types/shared.d.ts for shared auto-imports, referenced from all relevant declaration files, to solve issues where shared utilities were not recognized by TypeScript in their own directory or in server contexts. However, for server-only imports added via addServerImports or addServerImportsDir, the types may not always be included in the main imports.d.ts unless you also register them with addImports (which would make them available in both client and server contexts, not just server) feat: add dedicated shared auto-imports declaration file. If you want server-only auto-imports with proper type support, you may encounter limitations with the current auto-generated types system. The knowledge sources do not provide a documented workaround for generating a server-only imports.d.ts or for including server-only types in the main imports.d.ts without also exposing them to the client. Summary:
- There is only one imports.d.ts generated by default. - Server-only imports added via addServerImports may not have their types available unless also added via addImports, which exposes them to the client as well. - This is a known limitation, and the knowledge sources do not describe a built-in way to generate server-only type declarations for #imports without also exposing them to the client. If you need strict server-only type auto-imports, you may need to wait for further improvements in Nuxt or consider contributing to the auto-imports/type generation system. ---------------------- Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: ----------------------

kapa.ai•3w ago

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

Gaming

Programming

Adding server only imports

Did you find this page helpful?