1.1 Getting Started

Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• .nvmrc
• .prettierrc
• eslint.config.js
• package.json
• scripts/dev-electron.mjs
• src/ui/lollipop.js
• src/ui/table.js
• src/ui/viewer3d.js
• vite.config.js
• vitest.config.js

Purpose and Scope

This page covers the technical setup, installation prerequisites, execution scripts, deployment modes, and build tool configurations (Vite, Vitest, ESLint, and Prettier) for the VariantScope codebase.

Sources: package.json:1-46, vite.config.js:1-62

---

Prerequisites and Node Environment

VariantScope requires Node.js version 22.13 or higher as specified in package.json engines package.json:16-18. The project repository includes an .nvmrc configuration locking the development environment to Node 22 .nvmrc:1-2.

To install dependencies, run:

npm install

Sources: package.json:16-18, .nvmrc:1-2

---

NPM Scripts and Execution Modes

The package.json defines scripts for running local development servers, production web builds, Electron desktop application packaging, testing, linting, and formatting package.json:19-31.

Script	Command	Description
dev	vite	Starts the Vite dev server for browser-based development package.json:20.
dev:electron	node scripts/dev-electron.mjs	Spawns the Vite dev server and launches Electron pointing to its local URL package.json:21, scripts/dev-electron.mjs:1-20.
build:web	vite build	Builds the static web bundle for GitHub Pages package.json:22.
build:electron	vite build --mode electron	Builds the renderer bundle targeting Electron (./ base path and Electron CSP) package.json:23, vite.config.js:43-44.
build:e2e	vite build --mode e2e	Builds the application bundle configured with __E2E__ flags package.json:24, vite.config.js:43-49.
start:electron	npm run build:electron && electron .	Builds the Electron renderer and starts the main process package.json:25.
dist	npm run build:electron && electron-builder	Packages the desktop application into distributable binaries package.json:26.
test	vitest run	Executes unit test suites package.json:27.
test:e2e	npm run build:electron && playwright test	Builds and executes Playwright end-to-end tests package.json:28.
lint	eslint .	Runs ESLint across the codebase package.json:29.
format	prettier --write .	Formats files using Prettier package.json:30.

Deployment Modes Flow

graph TD
    A["npm_run_dev"] -->|Spawns| B["vite_DevServer"]
    C["npm_run_dev_electron"] -->|Executes| D["scripts/dev-electron.mjs"]
    D -->|Starts| B
    D -->|Launches| E["electron_MainProcess"]
    F["npm_run_build_web"] -->|Vite Default Mode| G["dist/web"]
    H["npm_run_build_electron"] -->|Vite Mode Electron| I["dist/electron-renderer"]
    J["npm_run_dist"] -->|Triggers| K["electron-builder"]

Loading

Sources: package.json:19-31, scripts/dev-electron.mjs:1-20 Sources: package.json:19-31, scripts/dev-electron.mjs:1-20

---

Build Tooling and Configuration Architecture

VariantScope utilizes Vite for module bundling, Vitest for unit testing, ESLint for static analysis and security checks, and Prettier for code style enforcement.

Vite Configuration (vite.config.js)

The Vite configuration handles two primary build targets (web for GitHub Pages and electron for desktop) from a single codebase rooted at src/ vite.config.js:1-46. Key plugins include:

• cspPlugin(isElectron): Injects a Content Security Policy <meta> tag into the built HTML depending on the target environment vite.config.js:7-22.
• noEvalPlugin(): Intercepts 3Dmol.es6.js builds to replace an unused eval() call with a thrown error, enforcing strict CSP compatibility vite.config.js:26-41.

graph TD
    A["vite.config.js"] -->|Defines| B["cspPlugin"]
    A -->|Defines| C["noEvalPlugin"]
    B -->|Calls| D["electron/csp.js"]
    C -->|Transforms| E["3Dmol.es6.js"]
    A -->|Outputs| F["dist/web"]
    A -->|Outputs| G["dist/electron-renderer"]
    A -->|Outputs| H["dist/e2e"]

Loading

Sources: vite.config.js:1-62, electron/csp.js Sources: vite.config.js:1-62, electron/csp.js:1-1, package.json:43

Unit Testing with Vitest (vitest.config.js)

Vitest is configured separately from Vite because unit tests reside in tests/unit while application source code resides in src/ vitest.config.js:1-3. It runs under a Node environment and targets core modules for V8 code coverage vitest.config.js:5-9.

Sources: vitest.config.js:1-10

Static Analysis and Code Formatting (eslint.config.js, .prettierrc)

• ESLint Flat Config (eslint.config.js): Implements strict security rules (no-eval, no-implied-eval, no-new-func) across renderer files (src/**/*.js), Node tools (electron/**/*.js, scripts/**/*.mjs, *.config.js), and CommonJS preload scripts (electron/**/*.cjs) eslint.config.js:1-51.
• Prettier (.prettierrc): Enforces single quotes, a print width of 100 characters, and trailing commas lib/.prettierrc:1-5.

Sources: eslint.config.js:1-51, .prettierrc:1-5

---