0
# @nuxt/schema
1

2
## Overview
3

4
@nuxt/schema provides comprehensive TypeScript types, schema definitions, and default configuration for the Nuxt framework. It serves as the foundational type system that ensures type safety across the entire Nuxt ecosystem, defining interfaces for configuration options, hooks, modules, components, routing, and application structure.
5

6
## Package Information
7

8
- **Name**: @nuxt/schema
9
- **Type**: TypeScript Library
10
- **Language**: TypeScript
11
- **License**: MIT
12

13
## Installation
14

15
```bash
16
npm install @nuxt/schema
17
# or
18
pnpm add @nuxt/schema
19
# or
20
yarn add @nuxt/schema
21
```
22

23
## Core Imports
24

25
```typescript
26
// Import types
27
import type { 
28
  NuxtConfig, 
29
  NuxtOptions, 
30
  NuxtHooks,
31
  NuxtModule,
32
  RuntimeConfig 
33
} from '@nuxt/schema';
34

35
// Import default schema configuration
36
import NuxtConfigSchema from '@nuxt/schema';
37

38
// Import builder environment constants
39
import { builders } from '@nuxt/schema/builder-env';
40
```
41

42
## Basic Usage
43

44
```typescript
45
import type { NuxtConfig, NuxtModule } from '@nuxt/schema';
46

47
// Define a Nuxt configuration
48
const config: NuxtConfig = {
49
  modules: ['@nuxtjs/tailwindcss'],
50
  runtimeConfig: {
51
    apiSecret: 'secret-key',
52
    public: {
53
      apiBase: '/api'
54
    }
55
  }
56
};
57

58
// Create a Nuxt module with proper typing
59
const myModule: NuxtModule = {
60
  meta: {
61
    name: 'my-module',
62
    version: '1.0.0'
63
  },
64
  setup(options, nuxt) {
65
    // Module setup logic with full type safety
66
  }
67
};
68
```
69

70
## Architecture
71

72
@nuxt/schema is organized into several key areas:
73

74
- **Configuration Types**: Complete type definitions for Nuxt configuration
75
- **Core Types**: Fundamental interfaces for Nuxt application structure
76
- **Hook System**: Comprehensive hook definitions for extensibility
77
- **Module System**: Type-safe module development interfaces
78
- **Schema Configuration**: Default configuration resolvers and validation
79

80
## Capabilities
81

82
### [Configuration System](./configuration-types.md)
83
The configuration system provides complete TypeScript coverage for all Nuxt configuration options, from basic app settings to advanced build configuration.
84

85
```typescript { .api }
86
interface NuxtConfig extends DeepPartial<Omit<ConfigSchema, 'vue' | 'vite' | 'runtimeConfig' | 'webpack' | 'nitro'>> {
87
  vue?: Omit<DeepPartial<ConfigSchema['vue']>, 'config'> & { config?: Partial<Filter<VueAppConfig, string | boolean>> }
88
  vite?: ConfigSchema['vite']
89
  nitro?: NitroConfig
90
  runtimeConfig?: Overrideable<RuntimeConfig>
91
  webpack?: DeepPartial<ConfigSchema['webpack']> & {
92
    $client?: DeepPartial<ConfigSchema['webpack']>
93
    $server?: DeepPartial<ConfigSchema['webpack']>
94
  }
95
  $schema?: SchemaDefinition
96
}
97
```
98

99
### [Core Application Types](./core-types.md)  
100
Essential interfaces that define the structure of Nuxt applications, including the main Nuxt instance, app interface, and plugin system.
101

102
```typescript { .api }
103
interface Nuxt extends Hookable<NuxtHooks> {
104
  options: NuxtOptions
105
  hooks: Hookable<NuxtHooks>
106
  hook: Nuxt['hooks']['hook']
107
  callHook: Nuxt['hooks']['callHook']
108
  addHooks: Nuxt['hooks']['addHooks']
109
  ready: () => Promise<void>
110
  close: () => Promise<void>
111
  server?: any
112
  vfs: Record<string, string>
113
  apps: Record<string, NuxtApp>
114
}
115
```
116

117
### [Hook System](./hooks.md)
118
Comprehensive hook definitions that enable extensibility throughout the Nuxt lifecycle, from build-time to runtime.
119

120
```typescript { .api }
121
type HookResult = Promise<void> | void
122

123
interface NuxtHooks {
124
  'kit:compatibility': (compatibility: NuxtCompatibility, issues: NuxtCompatibilityIssues) => HookResult
125
  'ready': (nuxt: Nuxt) => HookResult
126
  'close': (nuxt: Nuxt) => HookResult
127
  'restart': (options?: { hard?: boolean }) => HookResult
128
  // ... many more lifecycle hooks
129
}
130
```
131

132
### [Module Development](./modules.md)
133
Type-safe interfaces for developing Nuxt modules, including module metadata, setup functions, and dependency management.
134

135
```typescript { .api }
136
interface NuxtModule<TOptions = any, TSetupReturn = any> {
137
  meta?: ModuleMeta
138
  defaults?: TOptions | ((nuxt: Nuxt) => TOptions)
139
  schema?: TOptions
140
  hooks?: Partial<NuxtHooks>
141
  setup?: (
142
    this: void,
143
    resolvedOptions: TOptions,
144
    nuxt: Nuxt & { [key: string]: any }
145
  ) => Awaitable<TSetupReturn>
146
}
147
```
148

149
### [Component System](./components.md)
150
Type definitions for Nuxt's component auto-registration and management system.
151

152
```typescript { .api }
153
interface Component {
154
  pascalName: string
155
  kebabName: string
156
  export: string
157
  filePath: string
158
  shortPath: string
159
  chunkName: string
160
  prefetch: boolean
161
  preload: boolean
162
  global?: boolean | 'sync'
163
  island?: boolean
164
  meta?: ComponentMeta
165
  mode?: 'client' | 'server' | 'all'
166
  priority?: number
167
}
168
```
169

170
### [Runtime Configuration](./runtime-config.md)
171
Type-safe runtime configuration system with environment variable support and public/private separation.
172

173
```typescript { .api }
174
interface RuntimeConfig extends RuntimeConfigNamespace {
175
  app: NitroRuntimeConfigApp
176
  nitro?: NitroRuntimeConfig['nitro']
177
  public: PublicRuntimeConfig
178
}
179

180
type RuntimeValue<T, B extends string> = T & { [message]?: B }
181
```
182

183
### [Schema Validation](./schema-validation.md)
184
Default configuration schema and validation system that ensures proper Nuxt configuration.
185

186
```typescript { .api }
187
const NuxtConfigSchema: SchemaDefinition
188
```
189

190
The schema includes configuration resolvers for all major Nuxt subsystems: app, build, dev, experimental, nitro, typescript, vite, webpack, and more.
191

192
### [Compatibility System](./compatibility.md)
193
Module compatibility checking and validation system for ensuring proper module integration.
194

195
```typescript { .api }
196
interface NuxtCompatibility {
197
  nuxt?: string
198
  builder?: Partial<Record<'vite' | 'webpack' | 'rspack' | (string & {}), false | string>>
199
}
200
```
201

202
This comprehensive type system enables full IntelliSense support and compile-time error checking across the entire Nuxt ecosystem, making it essential for any TypeScript-based Nuxt application or module development.