or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-system.mdcli-reference.mdconfiguration.mddevelopment-server.mdindex.mdplugins.mdpreview-mode.mdtype-definitions.mdutilities.md
tile.json

cli-reference.mddocs/

CLI Reference

The electron-vite command-line interface provides three main commands for development, building, and previewing Electron applications with comprehensive options for debugging and configuration.

Commands

Development Command

Start development server and Electron app with hot reloading and HMR.

electron-vite [root]
electron-vite dev [root]
electron-vite serve [root]

Root Parameter:

  • [root] - Optional project root directory (default: current directory)

Development Options:

-w, --watch                    # Rebuild when main process or preload script modules change on disk
--inspect [port]               # Enable V8 inspector on the specified port (default: 5858)
--inspectBrk [port]           # Enable V8 inspector with break on start (default: 5858)
--remoteDebuggingPort <port>  # Port for remote debugging
--noSandbox                   # Force renderer process to run un-sandboxed
--rendererOnly                # Only dev server for the renderer (skip main/preload)

Usage Examples:

# Basic development
electron-vite dev

# Development with watch mode
electron-vite dev --watch

# Development with debugging
electron-vite dev --inspect=9229

# Renderer-only development
electron-vite dev --rendererOnly

# Development with custom root
electron-vite dev ./my-app

Build Command

Build for production with optimization and minification.

electron-vite build [root]

Usage Examples:

# Basic production build
electron-vite build

# Build with custom output directory
electron-vite build --outDir=dist-electron

# Build with source maps
electron-vite build --sourcemap

# Build with custom config
electron-vite build --config=electron.vite.production.config.js

Preview Command

Start Electron app to preview production build.

electron-vite preview [root]

Preview Options:

--noSandbox    # Force renderer process to run un-sandboxed
--skipBuild    # Skip build step and use existing build

Usage Examples:

# Preview with build
electron-vite preview

# Preview existing build
electron-vite preview --skipBuild

# Preview without sandbox
electron-vite preview --noSandbox

Global Options

Available for all commands:

-c, --config <file>          # Use specified config file
-l, --logLevel <level>       # Set log level: info | warn | error | silent
--clearScreen                # Allow/disable clear screen when logging
-d, --debug [feat]           # Show debug logs
-f, --filter <filter>        # Filter debug logs
-m, --mode <mode>            # Set env mode
--ignoreConfigWarning        # Ignore config warning
--sourcemap                  # Output source maps for debug (default: false)
--outDir <dir>               # Output directory (default: out)
--entry <file>               # Specify electron entry file

Environment Variables

The CLI sets and recognizes these environment variables:

Development Mode

# Set by CLI during development
NODE_ENV_ELECTRON_VITE=development
ELECTRON_RENDERER_URL=http://localhost:5173  # Dev server URL

# Optional: Set by CLI options
V8_INSPECTOR_PORT=5858                        # --inspect
V8_INSPECTOR_BRK_PORT=5858                   # --inspectBrk  
REMOTE_DEBUGGING_PORT=9222                    # --remoteDebuggingPort
NO_SANDBOX=1                                  # --noSandbox
ELECTRON_CLI_ARGS=["--arg1", "--arg2"]       # Additional Electron args
ELECTRON_ENTRY=./custom-main.js              # --entry

Production Mode

# Set by CLI during build/preview
NODE_ENV_ELECTRON_VITE=production
NODE_ENV=production

Configuration Files

The CLI automatically detects these configuration files (in order):

  1. electron.vite.config.js
  2. electron.vite.config.ts
  3. electron.vite.config.mjs
  4. electron.vite.config.cjs
  5. electron.vite.config.mts
  6. electron.vite.config.cts

Custom Configuration:

# Use specific config file
electron-vite dev --config=custom.config.js

# Use config from different directory
electron-vite dev --config=./configs/dev.config.js

Debugging Options

V8 Inspector

Enable Node.js debugging for main process:

# Enable inspector (default port 5858)
electron-vite dev --inspect

# Enable inspector on custom port
electron-vite dev --inspect=9229

# Enable inspector with break on start
electron-vite dev --inspectBrk=9229

Connect with Chrome DevTools:

  1. Open chrome://inspect in Chrome
  2. Click "Configure" and add localhost:9229
  3. Click "inspect" under Remote Target

Remote Debugging

Enable remote debugging for renderer processes:

# Enable remote debugging (default port 9222)
electron-vite dev --remoteDebuggingPort=9222

Access renderer DevTools at: http://localhost:9222

Debug Logging

Enable detailed logging:

# Enable all debug logs
electron-vite dev --debug

# Enable specific debug logs
electron-vite dev --debug=vite:transform

# Filter debug logs
electron-vite dev --debug --filter=electron

Advanced Usage

Process Arguments

Pass arguments to Electron process:

# Pass arguments after --
electron-vite dev -- --electron-arg1 --electron-arg2

# Arguments are available via process.argv in main process

Multiple Configurations

Use different configurations for different environments:

# Development config
electron-vite dev --config=electron.vite.dev.config.js

# Production config
electron-vite build --config=electron.vite.prod.config.js

# Testing config
electron-vite dev --config=electron.vite.test.config.js --mode=test

Custom Entry Points

Specify custom main process entry:

# Custom main entry
electron-vite dev --entry=src/main/main.js

# Entry point must be relative to project root
electron-vite build --entry=./dist/main.js

Error Handling

Common CLI Errors

Configuration Errors:

# Config file not found
electron-vite dev --config=nonexistent.config.js
# Error: failed to load config from nonexistent.config.js

# Invalid config syntax
# Error: config must export or return an object

Build Errors:

# TypeScript errors
# Error: TS2304: Cannot find name 'unknown_variable'

# Missing dependencies
# Error: Cannot resolve dependency 'missing-package'

Runtime Errors:

# Electron launch errors
# Error: spawn electron ENOENT (Electron not installed)

# Port conflicts
# Error: Port 5173 is already in use

Exit Codes

  • 0 - Success
  • 1 - General error (config, build, or runtime error)
  • 130 - Interrupted by user (Ctrl+C)

Log Levels

Control output verbosity:

# Silent (errors only)
electron-vite build --logLevel=silent

# Warnings and errors
electron-vite build --logLevel=warn

# Info, warnings, and errors (default)
electron-vite build --logLevel=info