CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-nuxt--vite-builder

Vite bundler for Nuxt applications providing seamless integration between Nuxt's framework and Vite's build system

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

main-bundling.mddocs/

Main Bundling

Core bundling functionality that orchestrates the entire build process for both client and server targets in Nuxt applications.

Capabilities

Bundle Function

The primary export that handles the complete build process for Nuxt applications using Vite.

/**
 * Main bundling function for Nuxt applications using Vite
 * Configures and executes both client and server builds with optimized settings
 * @param nuxt - Nuxt instance containing configuration and build context
 */
function bundle(nuxt: Nuxt): Promise<void>;

Usage Example:

import type { Nuxt } from "@nuxt/schema";
import { bundle } from "@nuxt/vite-builder";

// Assuming you have a configured Nuxt instance
const nuxt: Nuxt = await loadNuxt({ for: 'build' });

// Execute the complete build process
await bundle(nuxt);

// This will:
// 1. Configure Vite settings for both client and server
// 2. Set up development servers (if in dev mode)
// 3. Configure all necessary plugins
// 4. Execute client build
// 5. Execute server build
// 6. Generate manifests

Build Context Creation

The bundle function creates and manages the ViteBuildContext throughout the build process.

interface ViteBuildContext {
  /** Nuxt application instance containing all configuration */
  nuxt: Nuxt;
  /** Merged Vite configuration for the build */
  config: ViteConfig;
  /** Resolved path to the application entry file */
  entry: string;
  /** Optional Vite development server for client-side assets */
  clientServer?: ViteDevServer;
  /** Optional Vite development server for SSR assets */
  ssrServer?: ViteDevServer;
}

Configuration Merging

The bundle function performs sophisticated configuration merging between Nuxt and Vite settings.

Key Configuration Areas:

  • Resolve Aliases: Maps Nuxt directory aliases to absolute paths
  • Build Options: Configures output directories, chunk naming, and sourcemaps
  • CSS Processing: Integrates PostCSS plugins and CSS handling
  • Plugin Registration: Adds all necessary Vite plugins for Nuxt functionality
  • Development Settings: Configures file watching, HMR, and dev server options

Core Configuration Applied:

// Example of key configuration areas managed by bundle()
const viteConfig = {
  resolve: {
    alias: {
      '#app': nuxt.options.appDir,
      // Asset directory aliases
      [basename(nuxt.options.dir.assets)]: resolve(nuxt.options.srcDir, nuxt.options.dir.assets),
      // All user-defined aliases from nuxt.config
      ...nuxt.options.alias,
    },
  },
  define: {
    __NUXT_VERSION__: JSON.stringify(nuxt._version),
    __NUXT_ASYNC_CONTEXT__: nuxt.options.experimental.asyncContext,
  },
  build: {
    rollupOptions: {
      output: {
        sanitizeFileName: sanitizeFilePath,
        assetFileNames: // Configures asset naming with hash patterns
      },
    },
  },
  plugins: [
    // All Nuxt-specific Vite plugins
  ],
};

Hook Integration

The bundle function integrates with Nuxt's hook system for extensibility.

Key Hooks Called:

  • vite:extend - Allows modification of the build context before processing
  • vite:extendConfig - Enables configuration modifications for both client and server
  • vite:serverCreated - Called when development servers are created
  • vite:compiled - Triggered after successful compilation

Hook Usage Example:

// In a Nuxt module or plugin
nuxt.hook('vite:extendConfig', (config, { isClient, isServer }) => {
  if (isClient) {
    // Modify client-specific configuration
    config.plugins.push(myClientPlugin());
  }
  if (isServer) {
    // Modify server-specific configuration  
    config.plugins.push(myServerPlugin());
  }
});

Development vs Production

The bundle function automatically adapts behavior based on nuxt.options.dev:

Development Mode:

  • Creates Vite dev servers with HMR
  • Enables file watching and fast refresh
  • Uses in-memory compilation
  • Provides detailed logging and error reporting

Production Mode:

  • Generates static bundled files
  • Applies minification and optimization
  • Creates asset manifests
  • Performs code splitting and chunk optimization

Error Handling

The bundle function includes comprehensive error handling and logging:

  • Configuration Validation: Ensures all required options are present
  • Plugin Error Recovery: Gracefully handles plugin initialization failures
  • Build Error Reporting: Provides detailed error messages with context
  • Performance Monitoring: Logs build times and performance metrics

Install with Tessl CLI

npx tessl i tessl/npm-nuxt--vite-builder

docs

client-building.md

css-processing.md

development-server.md

index.md

main-bundling.md

manifest-generation.md

plugin-system.md

server-building.md

tile.json