Preview Mode

Preview mode allows you to test production builds locally before distribution, providing a quick way to verify that your Electron app works correctly in production mode.

Capabilities

Preview Function

Start Electron app to preview production build with optional build step.

/**
 * Start electron app to preview production build
 * @param inlineConfig - Optional inline configuration overrides
 * @param options - Preview options
 * @returns Promise that resolves when preview starts
 */
function preview(
  inlineConfig?: InlineConfig,
  options?: { skipBuild?: boolean }
): Promise<void>;

type InlineConfig = Omit<ViteConfig, 'base'> & {
  /** Path to config file or false to disable */
  configFile?: string | false;
  /** Disable .env file loading */
  envFile?: false;
  /** Ignore configuration warnings */
  ignoreConfigWarning?: boolean;
};

Usage Examples:

import { preview } from "electron-vite";

// Preview with automatic build
await preview();

// Skip build and preview existing build
await preview({}, { skipBuild: true });

// Preview with custom configuration
await preview({
  configFile: 'electron.vite.production.config.js',
  mode: 'production'
});

Preview Workflow

Standard Preview Process

1. Build Phase (unless skipBuild: true):

   • Runs production build for all processes
   • Optimizes and minifies code
   • Generates final distribution files

2. Launch Phase:

   • Starts Electron app using built files
   • Loads production renderer from filesystem
   • Runs with production environment variables

Skip Build Mode

When using skipBuild: true:

• Uses existing build output from previous build
• Faster startup for iterative testing
• Useful when only testing Electron app behavior, not code changes

Production Environment

Environment Variables

Preview mode sets production environment:

// Available in all processes
process.env.NODE_ENV // Set to 'production' 
process.env.NODE_ENV_ELECTRON_VITE // Set to 'production'

// No development server URL
process.env.ELECTRON_RENDERER_URL // undefined

File Loading

• Main Process: Loads from build output directory
• Preload Scripts: Loads from build output directory
• Renderer: Loads static HTML/CSS/JS files (no dev server)

CLI Integration

Preview mode is commonly used via CLI:

# Build and preview
electron-vite preview

# Preview existing build
electron-vite preview --skipBuild

# Preview with custom options
electron-vite preview --noSandbox --entry=custom-main.js

CLI Options

Available CLI options for preview:

• --skipBuild: Skip the build step
• --noSandbox: Force renderer process to run un-sandboxed
• --entry <file>: Specify custom electron entry file
• --config <file>: Use specific config file
• --mode <mode>: Set environment mode
• --logLevel <level>: Set logging level

Testing Scenarios

Production Validation

Preview mode is ideal for testing:

• Performance: Production optimizations and minification
• Asset Loading: Bundled assets and file paths
• Security: Sandboxed renderer behavior
• Distribution: Final build structure and organization

Debugging Production Issues

Common debugging scenarios:

// Test asset loading in production
const assetPath = process.env.NODE_ENV === 'development' 
  ? './assets/icon.png'
  : path.join(__dirname, '../renderer/assets/icon.png');

// Test different behavior between dev and production
if (process.env.NODE_ENV === 'development') {
  // Development-only code
} else {
  // Production code path
}

Build Verification

Verify production build integrity:

• File Structure: Ensure all required files are present
• Dependencies: Check that externalized dependencies resolve correctly
• Code Splitting: Verify lazy loading works in production
• Source Maps: Test source map generation if enabled

Configuration for Preview

Preview-Specific Configuration

Configure behavior specifically for preview mode:

// In electron.vite.config.js
export default defineConfig(({ command, mode }) => {
  const isPreview = process.env.NODE_ENV_ELECTRON_VITE === 'production';
  
  return {
    main: {
      build: {
        sourcemap: isPreview ? 'inline' : false, // Source maps for preview debugging
        minify: !isPreview // Disable minification for preview debugging
      }
    },
    renderer: {
      base: './', // Relative base for filesystem loading
      build: {
        assetsDir: 'assets',
        rollupOptions: {
          output: {
            format: 'es'
          }
        }
      }
    }
  };
});

Output Directory Structure

Ensure proper structure for preview mode:

out/
├── main/
│   └── index.js          # Main process entry
├── preload/
│   └── index.js          # Preload script
└── renderer/
    ├── index.html        # Renderer entry point
    └── assets/           # Static assets
        ├── main.js
        ├── main.css
        └── images/

Error Handling

Preview mode provides specific error handling:

• Build Errors: If build fails, preview aborts with error details
• File Missing: Clear errors when expected build outputs are missing
• Electron Launch: Detailed error reporting for Electron startup issues
• Renderer Loading: File loading errors from production builds

Common Preview Issues

• File Paths: Incorrect relative paths in production builds
• Asset Loading: Missing or incorrectly referenced assets
• External Dependencies: Unresolved externalized dependencies
• Security Policies: CSP or sandbox restrictions in production mode