src/module.ts and src/runtime/** sit in the same repository, are written in the same language and are built by the same command — and they run in different processes, on different machines, at different times. Every rule on this page follows from that one fact. Interviewers probe it with a single question: "why can't runtime/ import @nuxt/kit?" The answer tells them whether you have actually shipped a module or only read about one.

Know

• Never import @nuxt/kit from src/runtime/**, and never touch nuxt.options. Kit resolves the current Nuxt instance from an unctx context that exists only inside the build process; it also pulls in Node-only dependencies. Bundled into the client you get a resolution failure or a huge chunk, and on the server you get "Nuxt instance is unavailable".
• What runtime code may import: #imports (the auto-import registry), #app, vue, vue-router, h3, #build/<template>, and your own runtime/** files. Server runtime additionally has nitropack/runtime on Nuxt 4. Nuxt 5 moves to Nitro v3 and renames all of it Nuxt 5 — the package becomes nitro, types move to nitro/types, h3 helpers to nitro/h3, and the upgrade guide's preferred path for app and module runtime code is nuxt/server, so import { defineEventHandler } from 'nitropack/runtime' becomes import { defineEventHandler } from 'nuxt/server'.
• Import explicitly from #imports rather than relying on auto-imports. A consumer can set imports: { autoImport: false } in nuxt.config, and your module must still work. Writing import { defineNuxtPlugin, useRuntimeConfig } from '#imports' costs nothing and removes the whole class of "works in my playground" bugs.
• @nuxt/module-builder (mkdist under the hood) transpiles src/runtime file by file rather than bundling it. src/module.ts becomes dist/module.mjs plus dist/module.json and dist/types.d.mts; src/runtime/foo.ts becomes dist/runtime/foo.js plus a foo.d.ts at the same relative path. That one-to-one mapping is why resolver.resolve('./runtime/app/plugins/toolkit') still points at a real file after publishing — the path you resolve in src exists in dist.
• Because runtime files are transpiled, not bundled, their imports stay live. A import { something } from 'some-lib' in a runtime file becomes a real dependency of the consumer's app: it must be a dependency of your package, not a devDependency.
• .client.ts / .server.ts suffixes set a plugin's or component's mode: addPlugin infers mode from the suffix, addComponent({ mode: 'client' }) does it explicitly. Inside a universal file, guard with import.meta.client / import.meta.server; those are compile-time constants, so the dead branch is eliminated per environment bundle. Never process.client — that is Nuxt 2 vocabulary.
• build.transpile history. Modules used to push resolver.resolve('./runtime') onto nuxt.options.build.transpile so webpack would compile the untranspiled runtime. Nuxt now adds your module's package root to build.transpile automatically, and with Vite it is harmless but rarely needed. You still see it in every older module and will be asked what it was for.
• Server runtime needs Nitro to inline your directory. If a file under runtime/server/** imports #imports, Nitro must treat your directory as its own source, not as an external dependency, otherwise the alias never resolves in the built server. Add it to nitro.externals.inline from the nitro:config hook.
• Layers cannot do any of this. A layer ships app/ and server/ code that Nuxt merges; it has no runtime/ concept and no way to decide which files to inject. That is the line at which a team toolkit stops being a layer and becomes a layer plus a module.

How it works

The shape of the package, and what nuxt-module-build does with it:

src/                                dist/
├─ module.ts                  →     ├─ module.mjs       (bundled: kit, node deps, your build logic)
│                                   ├─ module.json      (name + version, read by Nuxt)
│                                   ├─ types.d.mts      (nuxt/schema augmentation)
└─ runtime/                   →     └─ runtime/         (transpiled file by file, same paths)
   ├─ app/                              ├─ app/
   │  ├─ plugins/toolkit.ts                ├─ plugins/toolkit.js  (+ .d.ts)
   │  └─ composables/useToolkit.ts         └─ composables/useToolkit.js
   └─ server/utils/version.ts           └─ server/utils/version.js

A correct runtime plugin — only allowed imports, mode from the filename:

import { defineNuxtPlugin, useRuntimeConfig } from '#imports'
import { features } from '#build/toolkit/features.mjs'

export default defineNuxtPlugin((nuxtApp) => {
  // .client suffix: this file is never in the server bundle at all
  const { apiBase } = useRuntimeConfig().public.toolkit

  const observer = new PerformanceObserver(() => {})
  observer.observe({ type: 'navigation', buffered: true })
  nuxtApp.hook('app:beforeMount', () => observer.disconnect())

  return { provide: { toolkit: { apiBase, features } } }
})

Making Nitro inline the server runtime so #imports resolves in the built output:

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

export default defineNuxtModule({
  meta: { name: 'nuxt-team-toolkit', configKey: 'toolkit' },
  setup (_options, nuxt) {
    const resolver = createResolver(import.meta.url)

    addServerImportsDir(resolver.resolve('./runtime/server/utils'))
    addServerHandler({ route: '/api/_toolkit/health', handler: resolver.resolve('./runtime/server/api/health') })

    nuxt.hook('nitro:config', (nitroConfig) => {
      nitroConfig.externals = defu(typeof nitroConfig.externals === 'object' ? nitroConfig.externals : {}, {
        inline: [resolver.resolve('./runtime')],
      })
    })
  },
})

Exercise

Be able to say