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

server-building.mddocs/

Server Building

Server-side build pipeline for SSR support, optimized for Node.js runtime with external dependency handling and development server integration.

Capabilities

Build Server Function

Creates Node.js-optimized builds for server-side rendering with proper external dependency handling.

/**
 * Build server-side assets for SSR
 * Handles Node.js-specific configuration, external dependencies, and SSR optimization
 * @param nuxt - Nuxt instance with server configuration
 * @param ctx - Vite build context containing entry and config
 */
function buildServer(nuxt: Nuxt, ctx: ViteBuildContext): Promise<void>;

Usage Example:

import { buildServer } from "@nuxt/vite-builder/server";
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.server.ts'
};

await buildServer(nuxt, ctx);

Server Configuration

The buildServer function applies Node.js-specific Vite configuration for SSR.

Key Configuration Areas:

// Server-specific configuration applied
const serverConfig = {
  define: {
    'process.server': true,
    'process.client': false,
    'process.browser': false,
    'import.meta.server': true,
    'import.meta.client': false,
    'import.meta.browser': false,
    // Browser globals undefined in Node.js
    'window': 'undefined',
    'document': 'undefined',
    'navigator': 'undefined',
    'location': 'undefined',
    'XMLHttpRequest': 'undefined',
  },
  ssr: {
    external: [
      'nitro/runtime',
      '#internal/nitro',
      '#internal/nitro/utils',
    ],
    noExternal: [
      // Transpile these packages for server use
      ...transpile({ isServer: true, isDev: nuxt.options.dev }),
      '/__vue-jsx',
      '#app',
      /^nuxt(\/|$)/,
      /(nuxt|nuxt3|nuxt-nightly)\/(dist|src|app)/,
    ]
  },
  build: {
    ssr: true,
    outDir: resolve(nuxt.options.buildDir, 'dist/server'),
    rollupOptions: {
      input: { server: serverEntry },
      output: {
        entryFileNames: '[name].mjs',
        format: 'module'
      }
    }
  }
};

Entry Point Resolution

Server builds use different entry points based on SSR configuration.

/**
 * Resolve server entry point based on SSR settings
 * @param nuxt - Nuxt instance
 * @param ctx - Build context  
 * @returns Resolved server entry path
 */
function resolveServerEntry(nuxt: Nuxt, ctx: ViteBuildContext): Promise<string>;

Entry Point Logic:

// Entry point selection
const serverEntry = nuxt.options.ssr 
  ? ctx.entry  // Full SSR entry
  : await resolvePath(resolve(nuxt.options.appDir, 'entry-spa')); // SPA mode entry

External Dependencies

Server builds carefully manage external vs bundled dependencies.

External Dependencies:

  • nitro/runtime - Nitro server runtime
  • #internal/nitro - Internal Nitro utilities
  • #internal/nuxt/paths - Path resolution utilities
  • #app-manifest - Application manifest
  • Node.js built-ins

Bundled Dependencies:

  • Vue ecosystem packages that need transpilation
  • Nuxt framework code
  • User application code
  • Dependencies requiring server-side processing
/**
 * Transpile configuration for server builds
 * @param options - Transpilation options
 * @returns Array of packages to transpile
 */
function transpile(options: { 
  isServer: boolean; 
  isDev: boolean; 
}): string[];

Development SSR Server

In development mode, buildServer creates a Vite SSR development server.

/**
 * SSR development server for server-side rendering
 * Provides module transformation and hot updates for SSR code
 */
interface ViteSSRServer extends ViteDevServer {
  /** Plugin container for server-side transformations */
  pluginContainer: PluginContainer;
  /** Transform modules for SSR execution */
  ssrTransform(code: string, url: string): Promise<SSRTransformResult>;
}

SSR Development Features:

  • Module Transformation: Real-time server code transformation
  • Dependency Tracking: Proper invalidation of server modules
  • Hot Updates: Server-side hot module replacement
  • Plugin Integration: Full plugin support for SSR

Production Server Build

In production mode, buildServer generates optimized server bundles.

// Production server build output
// .nuxt/dist/server/
//   ├── server.mjs            // Main server entry
//   ├── chunks/[hash].mjs     // Code-split chunks  
//   └── manifest.json         // Server manifest

Production Optimizations:

  • Code Splitting: Separate chunks for better caching
  • Tree Shaking: Remove unused server-side code
  • External Optimization: Proper external dependency handling
  • Source Maps: Optional sourcemaps for server debugging

Server-Specific Plugins

The buildServer function registers server-specific Vite plugins.

/**
 * Vue feature flags plugin for server builds
 * @param nuxt - Nuxt instance
 * @returns Vite plugin instance
 */
function VueFeatureFlagsPlugin(nuxt: Nuxt): Plugin;

/**
 * Sourcemap preserver plugin for build pipeline integration
 * @param nuxt - Nuxt instance  
 * @returns Vite plugin instance
 */
function SourcemapPreserverPlugin(nuxt: Nuxt): Plugin;

Nitro Integration

Server builds integrate closely with Nitro, Nuxt's server engine.

/**
 * Write development server configuration for Nitro integration
 * @param nuxt - Nuxt instance
 */
function writeDevServer(nuxt: Nuxt): Promise<void>;

/**
 * Write manifest files for server bundle resolution
 * @param ctx - Build context with server information
 */
function writeManifest(ctx: ViteBuildContext): Promise<void>;

Nitro Integration Features:

  • Runtime Compatibility: Ensures compatibility with Nitro runtime
  • Route Generation: Supports Nitro's file-based routing
  • Middleware Integration: Seamless server middleware support
  • API Routes: Automatic API route compilation

SSR vs SPA Mode

Server builds adapt based on Nuxt's rendering mode.

SSR Mode (nuxt.options.ssr = true):

  • Full server-side rendering
  • Hydration support
  • SEO optimization
  • Initial page load performance

SPA Mode (nuxt.options.ssr = false):

  • Client-side only rendering
  • Simplified server bundle
  • Faster build times
  • Reduced server complexity

Module Resolution

Server builds use specialized module resolution for Node.js environments.

// Module resolution configuration
const resolveConfig = {
  conditions: nitro.options.exportConditions, // Node.js export conditions
  alias: {
    // Server-specific aliases
    'nitro/runtime': join(nuxt.options.buildDir, 'nitro.server.mjs'),
  }
};

Error Handling

Server builds include specialized error handling for SSR scenarios.

Error Handling Features:

  • SSR Error Recovery: Graceful handling of server-side errors
  • Module Resolution Errors: Clear error messages for missing dependencies
  • Build Validation: Ensures server bundle integrity
  • Performance Monitoring: Tracks server build performance

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