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

client-building.mddocs/

Client Building

Client-side build pipeline handling browser-optimized bundles, CSS processing, and development server setup for Nuxt applications.

Capabilities

Build Client Function

Creates browser-optimized builds with development server integration for client-side assets.

/**
 * Build client-side assets with Vite
 * Handles browser-specific configuration, development server setup, and production optimization
 * @param nuxt - Nuxt instance with client configuration
 * @param ctx - Vite build context containing entry and config
 */
function buildClient(nuxt: Nuxt, ctx: ViteBuildContext): Promise<void>;

Usage Example:

import { buildClient } from "@nuxt/vite-builder/client";
import type { ViteBuildContext } from "@nuxt/vite-builder";

// Called internally by bundle(), but can be used directly
const ctx: ViteBuildContext = {
  nuxt,
  config: viteConfig,
  entry: './app/entry.client.ts'
};

await buildClient(nuxt, ctx);

Client Configuration

The buildClient function applies browser-specific Vite configuration.

Key Configuration Areas:

// Client-specific configuration applied
const clientConfig = {
  define: {
    'process.server': false,
    'process.client': true,
    'process.browser': true,
    'import.meta.server': false,
    'import.meta.client': true,
    'import.meta.browser': true,
  },
  optimizeDeps: {
    entries: [ctx.entry],
    exclude: [
      // Vue ecosystem packages excluded from optimization
      'vue', '@vue/runtime-core', '@vue/runtime-dom',
      'vue-router', 'nuxt', 'nuxt/app',
      // Nuxt dependencies
      '@unhead/vue', 'consola', 'defu', 'h3', 'ofetch'
    ]
  },
  build: {
    sourcemap: nuxt.options.sourcemap.client,
    manifest: 'manifest.json',
    outDir: resolve(nuxt.options.buildDir, 'dist/client'),
    rollupOptions: {
      input: { entry: ctx.entry }
    }
  }
};

Development Server

In development mode, buildClient creates and configures a Vite development server.

/**
 * Vite development server created for client builds
 * Provides HMR, file watching, and middleware integration
 */
interface ViteDevServer {
  /** Middleware stack for handling requests */
  middlewares: Connect.Server;
  /** Module graph for dependency tracking */
  moduleGraph: ModuleGraph;
  /** Close the development server */
  close(): Promise<void>;
}

Development Server Features:

  • Hot Module Replacement: Instant updates without full page reload
  • File Watching: Automatic rebuild on source changes
  • Middleware Mode: Integration with Nuxt's server middleware
  • CORS Handling: Configurable cross-origin request support
  • Static Asset Serving: Automatic serving of public assets

Development Server Example:

// Development server is automatically created and configured
// Access via build context after buildClient() completes
if (nuxt.options.dev && ctx.clientServer) {
  // Server is available for middleware integration
  const viteMiddleware = defineEventHandler(async (event) => {
    // Vite handles the request through its middleware stack
    await new Promise((resolve, reject) => {
      ctx.clientServer!.middlewares.handle(event.node.req, event.node.res, (err) => {
        err ? reject(err) : resolve(null);
      });
    });
  });
}

Production Build

In production mode, buildClient generates optimized static assets.

Production Features:

  • Code Splitting: Automatic chunk optimization for better caching
  • Asset Optimization: Minification, compression, and fingerprinting
  • Manifest Generation: Asset manifest for efficient loading
  • Sourcemap Generation: Optional sourcemaps for debugging
// Production build output structure
// .nuxt/dist/client/
//   ├── manifest.json          // Asset manifest
//   ├── [hash].js             // Entry chunks
//   ├── assets/[hash].css     // Extracted CSS
//   └── assets/[hash].[ext]   // Static assets

Client-Specific Plugins

The buildClient function registers several client-specific Vite plugins.

/**
 * Development style SSR plugin for client builds
 * @param options - Plugin configuration for style handling
 * @returns Vite plugin instance
 */
function DevStyleSSRPlugin(options: {
  srcDir: string;
  buildAssetsURL: string;
}): Plugin;

/**
 * Runtime paths plugin for asset URL resolution
 * @returns Vite plugin instance  
 */
function RuntimePathsPlugin(): Plugin;

/**
 * Module preload polyfill for older browsers
 * @returns Vite plugin instance
 */
function ModulePreloadPolyfillPlugin(): Plugin;

/**
 * Stable entry plugin for consistent chunk hashing
 * @param nuxt - Nuxt instance
 * @returns Vite plugin instance
 */
function StableEntryPlugin(nuxt: Nuxt): Plugin;

Asset Handling

Client builds handle various asset types with specific processing.

Asset Types Processed:

  • Vue Components: SFC compilation with scoped styles
  • CSS/SCSS/PostCSS: Style processing and extraction
  • TypeScript: Compilation with type checking
  • Static Assets: Copying with fingerprinting
  • Images: Optimization and format conversion (via plugins)

Asset Configuration:

// Asset file naming patterns
const assetConfig = {
  chunkFileNames: nuxt.options.dev ? undefined : '[hash].js',
  entryFileNames: nuxt.options.dev ? 'entry.js' : '[hash].js',
  assetFileNames: chunk => 
    withoutLeadingSlash(join(nuxt.options.app.buildAssetsDir, 
      `${sanitizeFilePath(filename(chunk.names[0]!))}.[hash].[ext]`))
};

HMR Configuration

Hot Module Replacement is configured for optimal development experience.

interface HMRConfig {
  /** Protocol for HMR connection (ws/wss) */
  protocol?: 'ws' | 'wss';
  /** Port for HMR server */
  port?: number;
  /** Custom HMR server instance */
  server?: Server;
}

HMR Features:

  • Vue SFC Updates: Instant component updates with state preservation
  • CSS Updates: Style updates without page reload
  • Asset Updates: Dynamic asset replacement
  • Error Overlay: Development error display

Bundle Analysis

Optional bundle analysis integration for production builds.

/**
 * Analyze plugin for bundle visualization
 * @param nuxt - Nuxt instance with analysis configuration
 * @returns Promise resolving to array of Vite plugins
 */
function AnalyzePlugin(nuxt: Nuxt): Promise<Plugin[]>;

Analysis Configuration:

// Enable in nuxt.config.ts
export default defineNuxtConfig({
  build: {
    analyze: true, // or { enabled: true, ... }
  }
});

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