tessl/npm-electron-vite

Electron build tooling based on Vite with pre-configured development environments, plugins, and hot reloading

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Utilities

Name: tessl/npm-electron-vite
Author: tessl

Utility functions for environment variable loading, configuration support, and common development helpers.

Capabilities

Environment Loading

Load environment variables with Electron-specific prefixes for different processes.

/**
 * Load .env files within the envDir (default: process.cwd())
 * By default, only env variables prefixed with VITE_, MAIN_VITE_, PRELOAD_VITE_ and
 * RENDERER_VITE_ are loaded, unless prefixes is changed
 * @param mode - Environment mode (development, production, etc.)
 * @param envDir - Directory containing .env files
 * @param prefixes - Variable prefixes to load
 * @returns Object containing loaded environment variables
 */
function loadEnv(
  mode: string,
  envDir?: string,
  prefixes?: string | string[]
): Record<string, string>;

Usage Examples:

import { loadEnv } from "electron-vite";

// Load environment variables for development mode
const env = loadEnv('development');
console.log(env.VITE_API_URL);

// Load from custom directory
const env = loadEnv('production', './config');

// Load with custom prefixes
const env = loadEnv('development', process.cwd(), [
  'VITE_',           // Standard Vite variables
  'MAIN_VITE_',      // Main process variables  
  'PRELOAD_VITE_',   // Preload script variables
  'RENDERER_VITE_',  // Renderer process variables
  'ELECTRON_'        // Custom Electron variables
]);

Process-Specific Environment Variables

Environment variables are loaded with process-specific prefixes:

# .env file
VITE_API_URL=https://api.example.com           # Available in all processes
MAIN_VITE_DEBUG=true                           # Available in main process
PRELOAD_VITE_CONTEXT_ISOLATION=false          # Available in preload scripts
RENDERER_VITE_FEATURE_FLAG=enabled            # Available in renderer process

Access in Code:

// In main process
const debug = import.meta.env.MAIN_VITE_DEBUG;

// In preload script  
const isolation = import.meta.env.PRELOAD_VITE_CONTEXT_ISOLATION;

// In renderer process
const featureFlag = import.meta.env.RENDERER_VITE_FEATURE_FLAG;

// Available in all processes
const apiUrl = import.meta.env.VITE_API_URL;

Internal Utilities

These utilities are used internally by electron-vite but may be useful for advanced configurations:

Type Utilities

/**
 * Check if value is a plain object
 * @param value - Value to check
 * @returns True if value is plain object
 */
function isObject(value: unknown): value is Record<string, unknown>;

Network Utilities

/**
 * Resolve hostname for development server
 * @param optionsHost - Host option from Vite config
 * @returns Resolved hostname string
 */
function resolveHostname(optionsHost: string | boolean | undefined): string;

/** Set of wildcard host patterns */
const wildcardHosts: Set<string>; // ['0.0.0.0', '::', '0000:0000:0000:0000:0000:0000:0000:0000']

URL Utilities

/**
 * Parse request URL parameters
 * @param id - URL or file path with query parameters
 * @returns Parsed query parameters object or null
 */
function parseRequest(id: string): Record<string, string> | null;

/**
 * Remove hash and query from URL
 * @param url - URL to clean
 * @returns Cleaned URL
 */
function cleanUrl(url: string): string;

/** Regular expression for matching query parameters */
const queryRE: RegExp; // /\?.*$/s

/** Regular expression for matching URL hash */
const hashRE: RegExp; // /#.*$/s

File System Utilities

/**
 * Generate SHA256 hash for text or buffer
 * @param text - Input text or buffer
 * @returns Hash string (first 8 characters)
 */
function getHash(text: Buffer | string): string;

/**
 * Convert absolute path to relative path
 * @param filename - Target file path
 * @param importer - Reference file path
 * @returns Relative path with ./ prefix if needed
 */
function toRelativePath(filename: string, importer: string): string;

Package Management Utilities

/**
 * Load package.json data with caching
 * @param root - Root directory to search for package.json
 * @returns Package data or null if not found
 */
function loadPackageData(root?: string): PackageData | null;

/**
 * Check if file path should be treated as ESM
 * @param filePath - File path to check
 * @returns True if file should be treated as ESM
 */
function isFilePathESM(filePath: string): boolean;

interface PackageData {
  main?: string;
  type?: 'module' | 'commonjs';
  dependencies?: Record<string, string>;
}

Environment File Structure

Standard Environment Files

Electron Vite loads environment files in this order:

.env - Default environment variables
.env.local - Local overrides (ignored by git)
.env.[mode] - Mode-specific variables
.env.[mode].local - Mode-specific local overrides

Example Environment Configuration

# .env - Base configuration
VITE_APP_TITLE=My Electron App
VITE_API_BASE_URL=https://api.example.com

# .env.development - Development overrides  
VITE_API_BASE_URL=http://localhost:3000
MAIN_VITE_DEVTOOLS=true
RENDERER_VITE_DEBUG=true

# .env.production - Production configuration
MAIN_VITE_AUTO_UPDATER=true
RENDERER_VITE_ANALYTICS=enabled
PRELOAD_VITE_SECURITY_MODE=strict

Process-Specific Usage

Main Process:

// Available: VITE_*, MAIN_VITE_*
const devtools = process.env.MAIN_VITE_DEVTOOLS === 'true';
const apiUrl = process.env.VITE_API_BASE_URL;

Preload Script:

// Available: VITE_*, PRELOAD_VITE_*
const securityMode = process.env.PRELOAD_VITE_SECURITY_MODE;
const apiUrl = process.env.VITE_API_BASE_URL;

Renderer Process:

// Available: VITE_*, RENDERER_VITE_*  
const debug = import.meta.env.RENDERER_VITE_DEBUG === 'true';
const analytics = import.meta.env.RENDERER_VITE_ANALYTICS;
const appTitle = import.meta.env.VITE_APP_TITLE;

Configuration Integration

Environment variables can be used in configuration files:

// electron.vite.config.ts
import { defineConfig, loadEnv } from "electron-vite";

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode);
  
  return {
    main: {
      define: {
        __API_URL__: JSON.stringify(env.VITE_API_BASE_URL),
        __DEVTOOLS__: env.MAIN_VITE_DEVTOOLS === 'true'
      }
    },
    renderer: {
      define: {
        __DEBUG_MODE__: env.RENDERER_VITE_DEBUG === 'true'
      }
    }
  };
});

Install with Tessl CLI