Guide

Server Utils

Enjoy auto-imported server utils and extend with your own utils.

Auto imports

When reading the rest of the docs, you might notice that there are no imports in examples for using utilities. It is because Nitro uses unjs/unimport to auto import utilities when used with full tree-shaking support so you don't have to!

H3 utils

Nitro enables all h3 utils as auto imports so you can use defineEventHandler, readBody, etc. without manually importing them.

Read more in H3 Docs.

utils directory

You can add your application specific utils inside utils/ directory and they will be auto-imported when used. Every export in the utils directory and its subdirectories will become available globally in your application.

Example: Create a utils/sum.ts file where a function useSum is exported:

utils/sum.ts
export function useSum(a: number, b: number) { return a + b }

Use it in your routes/index.ts file without importing it:

routes/index.ts
export default defineEventHandler(() => {
  const sum = useSum(1, 2) // auto-imported
  return { sum }
})

Nitro utils

Nitro also exposes several built-in utils:

  • defineCachedFunction(fn, options) / cachedFunction(fn, options)
  • defineCachedEventHandler(handler, options) / cachedEventHandler(handler, options)
  • defineRenderHandler(handler)
  • defineRouteMeta(options) (experimental)
  • useRuntimeConfig(event?)
  • useAppConfig(event?)
  • useStorage(base?)
  • useNitroApp()
  • defineNitroPlugin(plugin)
  • nitroPlugin(plugin)
  • getRouteRules(event)
Check the source code for list of available Nitro auto imports.
The types are auto-generated for global auto-imports when running the prepare or dev command. See TypeScript guide, for IDE support.

Manual imports

For some edge cases (IDE support and libraries in node_modules) it is impossible to rely on auto imports.

You can explicitly import them from virtual #imports file.

Manually importing from #imports still has benefits of tree-shaking.
plugins/test.ts
import { useStorage } from '#imports'

Async Context (Experimental)

Nitro (2.6+) enables a new server development experience in order to split application logic into smaller "composable" utilities that are fully decoupled from each other and can directly assess to a shared context (request event) without needing it to be passed along. This pattern is inspired from Vue Composition API and powered by unjs/unctx.

This feature is currently supported for Node.js and Bun runtimes and also coming soon to other presets that support AsyncLocalStorage interface.

In order to enable async context feature, you have to enable asyncContext flag:

export default defineNitroConfig({
  experimental: {
    asyncContext: true
  }
});

After enabling this flag, you can use useEvent() (auto imported) in any utility or composable to access the request event without manually passing it along:

// routes/index.ts
export default defineEventHandler(async () => {
  const user = await useAuth()
})

// utils/auth.ts
export function useAuth() {
  return useSession(useEvent())
}