Development Guide

Development Guide

Prerequisites

• Node.js 20 or 22
• npm (included with Node.js)
• Git
• Python (for native module compilation via node-gyp)
• C++ build tools:
  • Windows: Visual Studio Build Tools or npm install -g windows-build-tools
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux: build-essential, libsecret-1-dev

Linux Dependencies

# Debian/Ubuntu
sudo apt install build-essential libsecret-1-dev

# Fedora
sudo dnf install gcc-c++ libsecret-devel

Getting Started

# Clone the repository
git clone https://github.com/Snowy7/sncode.git
cd sncode

# Install dependencies
npm install

# Start development mode
npm run dev

Development mode runs:

1. Vite dev server at http://127.0.0.1:5188 with hot module replacement
2. TypeScript compiler in watch mode for the main process
3. Electron connecting to the Vite dev server

Available Scripts

Script	Command	Description
npm run dev	concurrently dev:renderer dev:electron	Full dev environment with HMR
npm run build	vite build && tsc -p tsconfig.node.json	Production build
npm run lint	eslint .	Run ESLint
npm run typecheck	tsc --noEmit (both configs)	Type check without emitting
npm test	vitest run	Run test suite
npm run package	npm run build && electron-builder	Build and create installers
npm run icons	node scripts/generate-icons.mjs	Generate app icons
npm start	electron .	Launch the built app

Project Structure

TypeScript Configurations

Config	Target	Module	Output
tsconfig.json	Renderer (React)	ESNext / Bundler	N/A (Vite handles)
tsconfig.node.json	Main process (Electron)	CommonJS / Node	dist-electron/

Build Output

Directory	Contents
dist/	Vite-built renderer (HTML, CSS, JS)
dist-electron/	Compiled main process JS
release/	Electron-builder output (installers)

Testing

Tests use Vitest and are located alongside source files:

# Run all tests
npm test

# Run tests in watch mode
npx vitest

# Run a specific test file
npx vitest src/shared/models.test.ts

Current test suites:

• src/shared/models.test.ts — Model catalog and helper functions
• src/shared/schema.test.ts — Zod validation schemas
• src/main/project-tools.test.ts — File and command tool functions

Linting

npm run lint

ESLint 9 with:

• @typescript-eslint/eslint-plugin
• eslint-plugin-react-hooks
• eslint-plugin-react-refresh

Type Checking

npm run typecheck

Checks both the renderer (tsconfig.json) and main process (tsconfig.node.json) configurations.

Packaging

# Build installers for the current platform
npm run package

# Build without publishing
npx electron-builder --publish never

Platform Targets

Platform	Target	Output
Windows	NSIS installer	.exe
macOS	DMG	.dmg (x64 + arm64)
Linux	AppImage	.AppImage

Electron Builder Configuration

The full electron-builder config is in package.json under the "build" key:

• App ID: com.sncode.desktop
• ASAR packaging enabled (with keytar unpacked for native access)
• Artifact naming: ${productName}-${version}-${platform}-${arch}.${ext}

CI/CD

CI Pipeline (.github/workflows/ci.yml)

Runs on pull requests to main:

1. Lint + Typecheck + Test — Ubuntu, Node.js 20 and 22
2. Build — Ubuntu, Windows, macOS (depends on step 1 passing)

Release Pipeline (.github/workflows/release.yml)

Triggered by tag pushes (v*) or manual dispatch:

1. Validate — Lint, typecheck, test
2. Package — Build installers on all three platforms
3. Release — Create GitHub Release with auto-generated notes and upload artifacts

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run npm run lint && npm run typecheck && npm test to validate
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.