Augmenting PageMeta type for custom metadata
Custom page metadata can be added in a type-safe way by augmenting the PageMeta interface in index.d.ts: declare module '#app' { interface PageMeta { yourCustomField?: type } } with export {}.
typescript support
34 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
SharedAppConfig type augmentation
To type app config outside app code, extend the `SharedAppConfig` interface. The location of the augmentation file determines which contexts see it: a `.d.ts` file in the `shared/` directory covers app code, shared code and server routes.
app.config TypeScript inference context
Nuxt automatically generates a TypeScript interface from provided app config. The fully inferred type is only available in app code (components, composables, plugins and so on). In server routes, code in the `shared/` directory and `nuxt.config`, keys defined in `app.config` files are typed as `unknown`. Keys defined inline in the `appConfig` option of `nuxt.config` are typed everywhere.
AppConfigInput interface for module authors
Module authors can use the `AppConfigInput` interface to declare what valid input options are when setting app config. Extend this interface in a TypeScript declaration file by augmenting the 'nuxt/schema' module. This declares input types but does not affect the type of `useAppConfig()`.
AppConfig interface for type safety
To type the result of calling `useAppConfig()` in app code, extend the `AppConfig` interface by augmenting the 'nuxt/schema' module in a TypeScript declaration file. Outside app code (server routes, shared directory, nuxt.config), extend `SharedAppConfig` instead. Extending `AppConfig` will overwrite the types Nuxt infers from the actual app config.
Type auto-imports organization
Types can be auto-imported the same way as utilities. App-only types should be put in app/types/, server-only types in server/types/, and types shared between both in shared/types/.
Do not modify auto-generated tsconfig files directly
The auto-generated TypeScript configuration files in the .nuxt/ directory should not be modified directly, as doing so could overwrite important settings that Nuxt or other modules rely on.
Per-context management of types, paths, and noEmit
Nuxt manages types, paths, and noEmit per context, meaning these options are not shared across all contexts when set in typescript.tsConfig. The node, shared, and server configs deliberately emit nothing and scan no ambient types. Use the matching per-context option (appTsConfig, nodeTsConfig, sharedTsConfig, or serverTsConfig) to override these for specific contexts.
typescript.serverTsConfig and nitro.typescript.tsConfig synchronization
Both typescript.serverTsConfig and nitro.typescript.tsConfig extend tsconfig.server.json and are kept in sync, so setting either has the same effect. Prefer typescript.serverTsConfig to keep all four contexts in one place.
Extend TypeScript configuration via nuxt.config.ts
TypeScript configuration should be customized through the nuxt.config.ts file rather than modifying the auto-generated tsconfig files directly. Use the typescript object within defineNuxtConfig to set shared and per-context TypeScript options.
typescript.tsConfig for shared compiler options
Set shared compilerOptions for all TypeScript contexts at once using the typescript.tsConfig option in nuxt.config.ts. This allows you to define compiler options that apply to every generated tsconfig file.
Per-context TypeScript configuration options
Nuxt provides four per-context configuration options in nuxt.config.ts to customize each TypeScript context individually: appTsConfig (for tsconfig.app.json), sharedTsConfig (for tsconfig.shared.json), nodeTsConfig (for tsconfig.node.json), and serverTsConfig (for tsconfig.server.json).
DOM and Vue-specific compiler options apply only to app context
Most compilerOptions set in typescript.tsConfig are shared with every context, but DOM- and Vue-specific options such as lib, jsx, and jsxImportSource only make sense for application code, so they are applied only to tsconfig.app.json.
Root tsconfig.json structure
The root tsconfig.json file in a Nuxt project should have an empty files array and reference the four auto-generated tsconfig files via the references array, pointing to .nuxt/tsconfig.app.json, .nuxt/tsconfig.server.json, .nuxt/tsconfig.shared.json, and .nuxt/tsconfig.node.json.
Auto-generated TypeScript configuration files
Nuxt automatically generates multiple TypeScript configuration files in the .nuxt/ directory: tsconfig.app.json, tsconfig.server.json, tsconfig.node.json, and tsconfig.shared.json. These files include recommended basic TypeScript configuration, references to auto-imports, API route types, path aliases, and more.
tsconfig.json generated in .nuxt directory
The generated `tsconfig.json` files inside the `.nuxt` directory include recommended basic TypeScript configuration, references to auto-imports, API route types, path aliases like `#imports`, `~/file`, or `#build/file`, and more.
Type-checking disabled by default in dev and build
By default, Nuxt does not check types when you run `nuxt dev` or `nuxt build`, for performance reasons.
Enable type-checking with vue-tsc and typescript
To enable type-checking at build or development time, install `vue-tsc` and `typescript` as development dependencies. Then run `npx nuxt typecheck` to check your types.
Enable type-checking via nuxt.config
Type-checking can be enabled at build or development time using the `typescript.typeCheck` option set to `true` in your `nuxt.config.ts` file.
Auto-generated types in .nuxt directory
Nuxt projects rely on auto-generated types stored in the `.nuxt` directory. These types are generated when you run the dev server or build your application. You can also generate these files manually by running `nuxt prepare`.
Do not modify tsconfig.json directly
It is not recommended to modify your `tsconfig.json` file directly, as doing so could overwrite important settings. Instead, extend it via `nuxt.config.ts`. Nuxt relies on this configuration, and Nuxt modules can extend it as well.
TypeScript project references in Nuxt
Nuxt uses TypeScript project references to improve type-checking performance and provide better IDE support. This feature allows TypeScript to break up your codebase into smaller, more manageable pieces.
Multiple tsconfig.json files generated for project references
When you run `nuxt dev`, `nuxt build` or `nuxt prepare`, Nuxt generates multiple `tsconfig.json` files: `.nuxt/tsconfig.app.json` (for app/ directory), `.nuxt/tsconfig.node.json` (for nuxt.config.ts and files outside other contexts), `.nuxt/tsconfig.server.json` (for server-side code), and `.nuxt/tsconfig.shared.json` (for code shared between app and server contexts).
Benefits of TypeScript project references
Project references provide faster builds by allowing TypeScript to skip rebuilding unchanged projects, better IDE performance with faster IntelliSense and error checking, isolated compilation so errors in one part don't prevent compilation of others, and clearer dependency management with explicit declarations.
Augment types within the correct context
Since the project is divided into multiple type contexts, augmentations must be placed in the correct context. For the `app` context, place augmentation files in the `app/` directory. For the `server` context, place them in the `server/` directory. For types shared between app and server, place the file in the `shared/` directory.
Strict checks enabled by default with typeCheck enabled
Strict checks are enabled by default in Nuxt when the `typescript.typeCheck` option is enabled to give greater type safety.
Disable strict checks during TypeScript migration
If you are converting your codebase to TypeScript, you may want to temporarily disable strict checks by setting `typescript.strict` to `false` in your `nuxt.config.ts`.
TypeScript references bypass tsconfig exclude option
TypeScript references add files to the type context without being affected by the exclude option in tsconfig.json, according to TypeScript documentation.
Manual typing of runtime config
Runtime config can be manually typed by creating an index.d.ts file that augments the 'nuxt/schema' module. Create interfaces for RuntimeConfig and PublicRuntimeConfig to specify the types of configuration properties. End-users should use 'nuxt/schema', while module authors should augment '@nuxt/schema'.
typescriptPlugin experimental flag
Enable enhanced TypeScript developer experience with the @dxup/nuxt module. This experimental plugin provides improved TypeScript integration and development tooling for better DX when working with TypeScript in Nuxt applications. This flag is disabled by default. To use this feature, you need to have typescript installed as a dependency and configure VS Code to use your workspace TypeScript version.
typescriptBundlerResolution - Bundler module resolution for TypeScript
The typescriptBundlerResolution feature enables 'Bundler' module resolution mode for TypeScript, which is the recommended setting for frameworks like Nuxt and Vite. It improves type support when using modern libraries with exports. You can set it to false to use the legacy 'Node' mode, which is the default for TypeScript.
Server types auto-import
Types placed in server/types/ are auto-imported in the server context only, so they can be referenced in server routes, middleware, plugins, and utilities without importing them. Only files directly in server/types/ are scanned; nested subdirectories are not auto-imported.
Nuxt 3 is written in TypeScript
Both Vue 3 and Nuxt 3+ are written in TypeScript. A fully typed codebase prevents mistakes and documents APIs usage.
TypeScript is optional in Nuxt 3
You do not have to write your application in TypeScript to take advantage of it. With Nuxt 3, you can opt-in by renaming your file from .js to .ts, or add <script setup lang="ts"> in a component.