v4 (alpha)
Nuxt on GitHub

TypeScript

Nuxt is fully typed and provides helpful shortcuts to ensure you have access to accurate type information when you are coding.

Type-checking

By default, Nuxt doesn't check types when you run nuxt dev or nuxt build, for performance reasons.

To enable type-checking at build or development time, install vue-tsc and typescript as development dependency:

npm install --save-dev vue-tsc typescript

Then, run nuxt typecheck command to check your types:

Terminal
npx nuxt typecheck

To enable type-checking at build or development time, you can also use the typescript.typeCheck option in your nuxt.config file:

nuxt.config.ts
export default defineNuxtConfig({
  typescript: {
    typeCheck: true
  }
})

Auto-generated Types

When you run nuxt dev or nuxt build, Nuxt generates the following files for IDE type support (and type checking):

.nuxt/nuxt.d.ts

This file contains the types of any modules you are using, as well as the key types that Nuxt requires. Your IDE should recognize these types automatically.

Some of the references in the file are to files that are only generated within your buildDir (.nuxt) and therefore for full typings, you will need to run nuxt dev or nuxt build.

.nuxt/tsconfig.app.json

This file contains the recommended basic TypeScript configuration for your project, including resolved aliases injected by Nuxt or modules you are using, so you can get full type support and path auto-complete for aliases like ~/file or #build/file.

Consider using the imports section of nuxt.config to include directories beyond the default ones. This can be useful for auto-importing types which you're using across your app.

Read more about how to extend this configuration.

Watch a video from Daniel Roe explaining built-in Nuxt aliases.
Nitro also auto-generates types for API routes. Plus, Nuxt also generates types for globally available components and auto-imports from your composables, plus other core functionality.
For backward compatibility, Nuxt still generates ./.nuxt/tsconfig.json. However, we recommend using TypeScript project references with the new configuration files (.nuxt/tsconfig.app.json, .nuxt/tsconfig.server.json, etc.) for better type safety and performance.If you do extend from ./.nuxt/tsconfig.json, keep in mind that all options will be overwritten by those defined in your tsconfig.json. Overwriting options such as "compilerOptions.paths" with your own configuration will lead TypeScript to not factor in the module resolutions, which can cause module resolutions such as #imports to not be recognized.In case you need to extend options further, you can use the alias property within your nuxt.config. Nuxt will pick them up and extend the generated TypeScript configurations accordingly.

Project References

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.

How Nuxt Uses Project References

When you run nuxt dev or nuxt build, Nuxt will generate multiple tsconfig.json files for different parts of your application.

  • .nuxt/tsconfig.app.json - Configuration for your application code
  • .nuxt/tsconfig.node.json - Configuration for your nuxt.config and modules
  • .nuxt/tsconfig.server.json - Configuration for server-side code (when applicable)
  • .nuxt/tsconfig.json - Legacy configuration for backward compatibility

Each of these files is configured to reference the appropriate dependencies and provide optimal type-checking for their specific context.

Benefits of Project References

  • Faster builds: TypeScript can skip rebuilding unchanged projects
  • Better IDE performance: Your IDE can provide faster IntelliSense and error checking
  • Isolated compilation: Errors in one part of your application don't prevent compilation of other parts
  • Clearer dependency management: Each project explicitly declares its dependencies
The project reference setup is handled automatically by Nuxt. You typically don't need to modify these configurations manually, but understanding how they work can help you troubleshoot type-checking issues.

Strict Checks

TypeScript comes with certain checks to give you more safety and analysis of your program.

Strict checks are enabled by default in Nuxt to give you greater type safety.

If you are currently converting your codebase to TypeScript, you may want to temporarily disable strict checks by setting strict to false in your nuxt.config:

nuxt.config.ts
export default defineNuxtConfig({
  typescript: {
    strict: false
  }
})