tessl/npm-nuxt--schema

Nuxt types and default configuration providing comprehensive TypeScript types, schema definitions, and configuration system for the Nuxt framework.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Module Development

Name: tessl/npm-nuxt--schema
Author: tessl

The module system in @nuxt/schema provides comprehensive type definitions for developing type-safe Nuxt modules, including module metadata, setup functions, dependency management, and compatibility checking.

Core Module Types

NuxtModule Interface

The main interface for creating Nuxt modules with full type safety.

interface NuxtModule<
  TOptions extends ModuleOptions = ModuleOptions,
  TOptionsDefaults extends Partial<TOptions> = Partial<TOptions>,
  TWith extends boolean = false,
> {
  (
    this: void,
    resolvedOptions: TWith extends true
      ? ResolvedModuleOptions<TOptions, TOptionsDefaults>
      : TOptions,
    nuxt: Nuxt
  ): ModuleSetupReturn
  
  getOptions?: (
    inlineOptions?: Partial<TOptions>,
    nuxt?: Nuxt
  ) => Promise<
    TWith extends true
      ? ResolvedModuleOptions<TOptions, TOptionsDefaults>
      : TOptions
  >
  
  getModuleDependencies?: (nuxt: Nuxt) => ModuleDependencies | undefined
}

type ModuleSetupReturn = Awaitable<false | void | ModuleSetupInstallResult>
type Awaitable<T> = T | Promise<T>

ModuleMeta Interface

Metadata for module identification and compatibility.

interface ModuleMeta {
  /** Module name */
  name?: string
  /** Module version */
  version?: string
  /** Configuration key used within nuxt.config */
  configKey?: string
  /** Version constraints for Nuxt or features */
  compatibility?: NuxtCompatibility
  /** @internal Fully resolved path */
  rawPath?: string
  [key: string]: unknown
}

Module Options and Results

type ModuleOptions = Record<string, any>

type ModuleSetupInstallResult = {
  /** Timing information for setup */
  timings?: {
    /** Total setup time in ms */
    setup?: number
    [key: string]: number | undefined
  }
}

type ModuleSetupReturn = void | ModuleSetupInstallResult | Promise<void | ModuleSetupInstallResult>

interface ResolvedModuleOptions<T = ModuleOptions> {
  src?: string
  handler: T
  options?: ModuleOptions
}

Module Dependencies

ModuleDependencies Interface

interface ModuleDependencies {
  [packageName: string]: ModuleDependencyMeta
}

interface ModuleDependencyMeta {
  /** Dependency version requirement */
  version?: string
  /** Whether dependency is optional */
  optional?: boolean
  /** Custom installation instructions */
  installCommand?: string
}

Compatibility System

NuxtCompatibility Interface

interface NuxtCompatibility {
  /** Required Nuxt version in semver format */
  nuxt?: string
  /** Builder compatibility requirements */
  builder?: Partial<Record<'vite' | 'webpack' | 'rspack' | (string & {}), false | string>>
}

interface NuxtCompatibilityIssue {
  name: string
  message: string
}

interface NuxtCompatibilityIssues extends Array<NuxtCompatibilityIssue> {
  /** Return formatted error message */
  toString(): string
}

Module Definition Patterns

Basic Module

import type { NuxtModule } from '@nuxt/schema';
import { defineNuxtModule } from '@nuxt/kit';

interface ModuleOptions {
  apiKey?: string
  timeout?: number
}

const myModule: NuxtModule<ModuleOptions> = defineNuxtModule<ModuleOptions>({
  meta: {
    name: 'my-module',
    version: '1.0.0',
    configKey: 'myModule',
    compatibility: {
      nuxt: '^3.0.0'
    }
  },
  
  defaults: {
    apiKey: '',
    timeout: 5000
  },
  
  setup(options, nuxt) {
    // Module setup logic
    console.log('Module options:', options);
    
    // Add runtime configuration
    nuxt.options.runtimeConfig.myModule = {
      apiKey: options.apiKey
    };
    
    // Register plugins
    addPlugin({
      src: path.resolve(__dirname, './runtime/plugin.client.ts'),
      mode: 'client'
    });
  }
});

export default myModule;

Advanced Module with Schema

import type { NuxtModule } from '@nuxt/schema';
import { defineNuxtModule, createResolver, addImports } from '@nuxt/kit';

interface ModuleOptions {
  enabled: boolean
  providers: {
    google?: {
      clientId: string
      clientSecret: string
    }
    github?: {
      clientId: string
      clientSecret: string
    }
  }
  redirectUrl: string
}

const authModule: NuxtModule<ModuleOptions> = defineNuxtModule<ModuleOptions>({
  meta: {
    name: '@my-org/nuxt-auth',
    version: '2.1.0',
    configKey: 'auth',
    compatibility: {
      nuxt: '^3.8.0',
      builder: {
        vite: '^4.0.0',
        webpack: false // Not compatible with webpack
      }
    }
  },
  
  defaults: {
    enabled: true,
    providers: {},
    redirectUrl: '/auth/callback'
  },
  
  // JSON Schema for options validation
  schema: {
    type: 'object',
    properties: {
      enabled: { type: 'boolean' },
      providers: {
        type: 'object',
        properties: {
          google: {
            type: 'object',
            properties: {
              clientId: { type: 'string' },
              clientSecret: { type: 'string' }
            },
            required: ['clientId', 'clientSecret']
          }
        }
      },
      redirectUrl: { type: 'string' }
    }
  },
  
  async setup(options, nuxt) {
    if (!options.enabled) return;
    
    const resolver = createResolver(import.meta.url);
    
    // Add composables
    addImports([
      {
        name: 'useAuth',
        from: resolver.resolve('./runtime/composables/useAuth')
      },
      {
        name: 'useAuthUser',
        from: resolver.resolve('./runtime/composables/useAuthUser')
      }
    ]);
    
    // Add server middleware
    addServerHandler({
      route: '/api/auth/**',
      handler: resolver.resolve('./runtime/server/auth.ts')
    });
    
    // Add type declarations
    addTypeTemplate({
      filename: 'types/auth.d.ts',
      getContents: () => `
        declare module '#app' {
          interface NuxtApp {
            $auth: {
              user: Ref<User | null>
              loggedIn: ComputedRef<boolean>
              login: (provider: string) => Promise<void>
              logout: () => Promise<void>
            }
          }
        }
      `
    });
    
    return {
      timings: {
        setup: performance.now()
      }
    };
  }
});

Module with Hooks

const analyticsModule: NuxtModule = defineNuxtModule({
  meta: {
    name: 'nuxt-analytics',
    version: '1.0.0'
  },
  
  hooks: {
    'ready': async (nuxt) => {
      console.log('Analytics module ready');
    },
    
    'build:before': async () => {
      // Pre-build analytics setup
    },
    
    'render:route': async (url, result, context) => {
      // Track page views
      console.log(`Page rendered: ${url}`);
    }
  },
  
  setup(options, nuxt) {
    // Additional setup beyond hooks
    nuxt.hook('app:resolve', async (app) => {
      // Modify app configuration
      app.head = app.head || {};
      app.head.script = app.head.script || [];
      app.head.script.push({
        src: 'https://analytics.example.com/script.js',
        async: true
      });
    });
  }
});

Module Utilities and Helpers

Module Definition Helper

function createModule<T = ModuleOptions>(
  definition: Omit<NuxtModule<T>, 'setup'> & {
    setup: (options: T, nuxt: Nuxt) => ModuleSetupReturn
  }
): NuxtModule<T> {
  return {
    ...definition,
    setup: definition.setup
  };
}

Conditional Module Loading

const conditionalModule: NuxtModule = defineNuxtModule({
  meta: {
    name: 'conditional-module'
  },
  
  setup(options, nuxt) {
    // Only load in development
    if (!nuxt.options.dev) {
      return;
    }
    
    // Check for required dependencies
    try {
      require.resolve('some-dev-dependency');
    } catch {
      console.warn('Development dependency not found, skipping module');
      return;
    }
    
    // Setup development features
    addDevtools();
  }
});

Module with Runtime Dependencies

interface DatabaseModuleOptions {
  provider: 'postgres' | 'mysql' | 'sqlite'
  connection: {
    host?: string
    port?: number
    database: string
    username?: string
    password?: string
  }
}

const databaseModule: NuxtModule<DatabaseModuleOptions> = defineNuxtModule({
  meta: {
    name: 'nuxt-database',
    configKey: 'database'
  },
  
  async setup(options, nuxt) {
    const resolver = createResolver(import.meta.url);
    
    // Add required dependencies
    await addBuildPlugin({
      name: 'database-types',
      setup(build) {
        build.onResolve({ filter: /^#database$/ }, () => ({
          path: resolver.resolve('./runtime/database'),
          namespace: 'database'
        }));
      }
    });
    
    // Generate connection configuration
    addTemplate({
      filename: 'database.config.js',
      getContents: () => `
        export default ${JSON.stringify({
          provider: options.provider,
          connection: options.connection
        }, null, 2)}
      `
    });
    
    // Add database composables
    addImports([
      { name: 'useDatabase', from: '#database' },
      { name: 'useQuery', from: '#database' }
    ]);
  }
});

Module Testing Pattern

// tests/module.test.ts
import { describe, it, expect } from 'vitest';
import { setup, createPage } from '@nuxt/test-utils';
import type { NuxtModule } from '@nuxt/schema';

describe('My Module', async () => {
  await setup({
    nuxtConfig: {
      modules: [
        ['./src/module', {
          apiKey: 'test-key',
          enabled: true
        }]
      ]
    }
  });
  
  it('should register composables', async () => {
    const page = await createPage('/test');
    
    const hasComposable = await page.evaluate(() => {
      return typeof window.$nuxt?.$myModule !== 'undefined';
    });
    
    expect(hasComposable).toBe(true);
  });
});

The module system provides a powerful foundation for extending Nuxt with full type safety, ensuring that modules integrate seamlessly with the Nuxt ecosystem while maintaining excellent developer experience.

Install with Tessl CLI