Frontend Setup

Info

This guide covers the environment configuration for eIsland frontend development, including toolchain installation, project setup, and IDE configuration. For an overview of the frontend technologies, see Frontend Tech Stack.

Prerequisites

The eIsland frontend is an Electron + React + TypeScript desktop application. The following tools are required:

Tool	Version	Purpose	Recommended
Node.js	>= 22.x	JavaScript runtime	25.6.0
npm	>= 10.x	Package manager	11.15.0
Git	Latest	Version control	2.53.0.windows.2
VS Build Tools 2022	Latest	Compile native C/C++ plugins	"Desktop development with C++" workload
.NET 10 SDK	>= 10.0	Build temperature-helper	10.0

Warning

Node.js 22+ is required because the project uses --experimental-strip-types for native TypeScript execution in build scripts.

Installing Node.js

Windows (recommended — using nvm-windows):

# Install nvm-windows from https://github.com/coreybutler/nvm-windows
nvm install 25
nvm use 25
node -v  # Should print v25.x.x

Windows (alternative — direct download):

Note

Download the recommended version's installer from nodejs.org v25.6.0 and run it.

Important

Directly download Node.js v25.6.0 from node-v25.6.0-x64.msi and run it.

Verify installation:

node -v   # v25.6.0 or later
npm -v    # 11.x.x or later

Project Setup

Fork the Repository

Tips

1. Visit https://github.com/JNTMTMTM/eIsland
2. Click the Fork button in the top-right corner

Note

This creates a personal copy of the repository under your account (your-username/eIsland).

Caution

You must fork the repository before cloning. Do not clone the original JNTMTMTM/eIsland repository directly — you will not have push access and cannot create pull requests.

Clone Your Fork

# Clone your fork (NOT the original repository)
git clone https://github.com/your-username/eIsland.git
cd eIsland

Warning

Replace your-username with your actual GitHub username. Do not clone the original repository directly — you will not be able to push changes.

Add Upstream Remote

# Add the original repository as "upstream"
git remote add upstream https://github.com/JNTMTMTM/eIsland.git

# Verify remotes
git remote -v
# origin    https://github.com/your-username/eIsland.git (fetch)
# origin    https://github.com/your-username/eIsland.git (push)
# upstream  https://github.com/JNTMTMTM/eIsland.git (fetch)
# upstream  https://github.com/JNTMTMTM/eIsland.git (push)

Switch to Dev Branch

# Fetch latest branches from upstream
git fetch upstream

# Switch to dev branch (main development branch)
git checkout dev

# Keep your local dev branch in sync with upstream
git pull upstream dev

Info

The dev branch is the main development branch. All feature branches should be created from dev, and pull requests should target dev.

Push and Create Pull Request

After completing your changes, push to your fork (origin) and create a Pull Request on GitHub:

# Create a feature branch from dev
git checkout -b feat/your-feature-name

# ... make your changes and commit ...

# Push to YOUR fork (NOT upstream)
git push origin feat/your-feature-name

Then on GitHub:

1. Visit your fork: https://github.com/your-username/eIsland
2. Click Compare & pull request
3. Set the base repository to JNTMTMTM/eIsland and base branch to dev
4. Fill in the PR title and description, then submit

Caution

Always push to origin (your fork), never to upstream (the main repository). You do not have push access to the main repository. All contributions must go through Pull Request review.

Install Dependencies

npm install

Tips

The postinstall script automatically runs electron-builder install-app-deps to rebuild native modules for Electron's Node.js version.

Warning

npm install will automatically compile four native C/C++ plugins (eisland-windows-fullscreen-detector, eisland-windows-performance-monitor, windows-toast-listener, windows-processes-attacker) and one .NET helper (temperature-helper). This requires:

• Visual Studio Build Tools 2022 — with the "Desktop development with C++" workload installed
• .NET 10 SDK — required for building the eIslandTemperatureReader helper

If you see MSB8036: The Windows SDK version was not found or node-gyp build errors, install the build tools:

1. Download Visual Studio Build Tools 2022
2. In the installer, select "Desktop development with C++" workload
3. Install .NET 10 SDK
4. Restart your terminal and run npm install again

Development Commands

Development

Command	Description	When to Use
npm run dev	Start electron-vite dev mode with hot reload	Daily development — launches the app with React Fast Refresh and auto-restart on main process changes
npm run build	Build all three targets (main, preload, renderer) into out/	Before testing the production build, or when CI needs a clean build artifact
npm run preview	Preview the built application without dev server	Verify the production build works correctly before packaging

Info

npm run dev internals:

1. Compiles src/main/ → out/main/ (Node.js main process)
2. Compiles src/preload/ → out/preload/ (context bridge)
3. Starts a Vite dev server for src/renderer/ with React Fast Refresh
4. Launches Electron pointing at the dev server

Testing

Command	Description	When to Use
npm run test	Run both named test projects once (vitest run)	Before committing code, or in CI pipelines
npm run test:node	Run tests under src/ outside src/renderer/	When modifying main process, preload, or other Node.js code
npm run test:renderer	Run tests under src/renderer/	When modifying renderer stores, utilities, hooks, or components
npm run test:preload	Run only src/preload/index.test.ts	When modifying preload bridge code — faster than running the full suite
npm run test:coverage	Run both projects with V8 coverage reports	Before opening a PR, or periodically to audit test gaps
npm run build:e2e	Build Electron E2E artifacts into e2e/out/	Before running or debugging an existing E2E build
npm run test:e2e	Build and run Playwright Electron tests	Verify desktop UI, IPC, persistence, and cross-window behavior
npm run test:e2e:run	Run the existing E2E build	Filter or debug scenarios without rebuilding
npm run typecheck:e2e	Check E2E TypeScript and Electron-Vite configuration	After modifying the E2E suite or build configuration

Tips

For iterative development, run npx vitest (without run) to start Vitest in watch mode — it re-runs affected tests on file save.

Test configuration: Vitest defines node and renderer projects, both inheriting environment: 'node', clearMocks: true, and restoreMocks: true. Both collect .test.ts and .test.tsx; the node project excludes src/renderer/ to avoid duplicate collection.

Note

The renderer label is a project name, not a DOM environment. See Testing Commands for project filters, the latest verified test counts, and a renderer TSX coverage audit command.

For Windows/macOS desktop interaction tests, see Electron E2E Testing. It documents the separate installation steps, graphical session requirement, and root e2e/ directory. Normal development and release builds keep their regular output under out/.

Packaging & Release

Caution

These commands are for testing and maintainer use only. Regular developers do not have permission to upload build artifacts to remote storage (COS / MinIO). Use npm run package locally to verify the installer build, but do not run release:upload* commands.

Command	Description	When to Use
npm run package	Build + package into NSIS installer (dist/eIsland-{version}-Setup.exe)	Local testing — verify the installer builds correctly on your machine
release:upload	Package + upload release artifacts to COS (Cloud Object Storage)	Maintainer only — publish a new release to CDN
release:upload-only	Upload existing build artifacts to COS without rebuilding	Maintainer only — re-upload a previously built package
release:upload-minio	Upload artifacts to MinIO storage (--minio-only)	Maintainer only — internal/self-hosted release distribution
release:notes	Generate incremental release notes from git history since last tag	After merging PRs — outputs RELEASE_NOTES_SINCE_LAST_TAG.md
changelog:generate	Generate full changelog from git history	Periodic maintenance — regenerates docs/CHANGE_LOG.md

Code Quality

Command	Description	When to Use
lint	Run ESLint on the entire project (eslint . --max-warnings=0)	Before every commit — catches JS/TS, React, import, and JSDoc violations
lint:fix	Run ESLint with auto-fix	After pulling upstream changes or when lint reports fixable issues
lint:report	Generate HTML lint report (reports/eslint.html)	After large refactors — review all violations in a browser
lint:report:json	Generate JSON lint report (reports/eslint.json)	CI pipelines or custom tooling that consumes lint results
lint:css	Run Stylelint on all CSS/SCSS files	After modifying styles — enforces property order, selector limits, and naming
lint:css:fix	Run Stylelint with auto-fix	When Stylelint reports fixable CSS issues
lint:html	Validate HTML files against project standards	After modifying HTML files — enforces doctype, lang, and accessibility rules
lint:all	Run all checks in parallel (ESLint + Stylelint + HTML + i18n)	Before opening a PR — comprehensive quality gate
comment:check	Validate source files comply with comment standards	Before committing — ensures JSDoc headers and inline comments follow conventions
i18n:check	Validate i18n completeness — all t() keys in both locale files	After any UI change that adds or modifies t() translation calls

Warning

comment:check and i18n:check use --experimental-strip-types (Node.js 22+ native TS execution). Ensure your Node.js version meets the requirement. See Quality Commands for full details.

Lifecycle Hooks

Command	Description	When to Use
postinstall	Runs electron-builder install-app-deps automatically after npm install	Automatic — rebuilds native modules (e.g., windows-smtc-monitor) for Electron's Node.js version. Never run manually.

Build System

Electron-Vite Configuration

The project uses electron-vite to manage three separate build targets:

Target	Entry	Output	Description
main	src/main/index.ts, src/main/smtcWorker.ts	out/main	Node.js main process
preload	src/preload/index.ts	out/preload	Context bridge
renderer	src/renderer/html/DynamicIsland{Index,Standalone,Splash,Guide}.html, src/renderer/html/DynamicIslandAibackground/index.html	out/renderer/html	Renderer UI (5 HTML entries); assets in out/renderer/assets

Key Build Dependencies

Package	Version	Purpose
electron-vite	^3.0.0	Unified build toolchain
vite	^6.3.5	Build engine
@vitejs/plugin-react	^4.5.2	React Fast Refresh
@tailwindcss/vite	^4.2.2	Tailwind CSS v4 integration
electron-builder	^26.0.12	Application packaging

Packaging

npm run package

This runs electron-vite build followed by electron-builder to produce a Windows NSIS installer in the dist/ directory.

Output: dist/eIsland-{version}-Setup.exe

TypeScript Configuration

The project uses a multi-config setup with project references:

Config	Scope	Description
tsconfig.json	Root	References tsconfig.node.json and tsconfig.web.json
tsconfig.node.json	Main + Preload	Node.js target, CommonJS modules
tsconfig.web.json	Renderer	Browser target, react-jsx, bundler module resolution

Renderer path alias:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/renderer/*"]
    }
  }
}

Usage in renderer code:

import { useIslandStore } from '@/store/useIslandStore';

IDE Configuration

VS Code (Recommended)

Required extensions:

Extension	Purpose
ESLint	JavaScript/TypeScript linting
Prettier	Code formatting
Tailwind CSS IntelliSense	Tailwind class autocomplete
Vitest	Test runner UI

Recommended settings (.vscode/settings.json):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

Verifying the Setup

After completing the setup, verify everything works:

# 1. Check Node.js version
node -v  # Should be v22+ (project uses v25.6.0)

# 2. Install dependencies
npm install

# 3. Run tests
npm run test

# 4. Start development mode
npm run dev

Tips

If npm run dev launches the Electron window with the dynamic island visible, your frontend development environment is ready.

Troubleshooting

Native Module Errors

If you see errors about native modules (e.g., @coooookies/windows-smtc-monitor):

# Rebuild native modules for Electron
npx electron-builder install-app-deps

TypeScript Errors After Pull

If you see TypeScript errors after pulling new changes:

# Clean build artifacts and reinstall
rm -rf out/ node_modules/
npm install
npm run build

Electron Launch Fails

If Electron fails to launch in dev mode:

# Check if port is in use (default: 5173 for renderer)
netstat -ano | findstr :5173

# Kill the process if needed, then retry
npm run dev