Local Development Setup

This guide will help you set up your development environment for Smyles Station.

Prerequisites

Required Software

Node.js >= 23.0.0
Download from nodejs.org
Verify installation: node --version
npm (included with Node.js)
Verify installation: npm --version
Git
Download from git-scm.com
Verify installation: git --version

Recommended Software

Visual Studio Code
Download from code.visualstudio.com
Recommended extensions:
- ESLint
- Prettier
- TypeScript and JavaScript Language Features
React Developer Tools
Browser extension for debugging React components
Available in development mode

Initial Setup

1. Clone the Repository

# Clone your fork
git clone https://github.com/buff-sudo/smyles-station.git
cd verbose-funicular

# Add upstream remote
git remote add upstream https://github.com/buff-sudo/smyles-station.git

2. Install Dependencies

# Install all dependencies for all packages
npm install

This will install dependencies for all packages in the monorepo (main, preload, renderer, etc.).

3. Verify Installation

# Check that TypeScript compiles without errors
npm run typecheck

# Try building all packages
npm run build

If these commands complete without errors, you're ready to develop!

Development Commands

Start Development Mode

npm start

This will: - Start the Vite dev server for the renderer - Launch Electron in development mode - Enable hot-reload for renderer changes - Auto-restart on main process changes

Note: The application will open in a development window. DevTools are available by default.

Type Checking

# Check types across all packages
npm run typecheck

Run this frequently during development to catch type errors early.

Building

# Build all packages
npm run build

# Build for production and create executable
npm run compile

# Build for debugging (unpacked, no asar)
npm run compile -- --dir -c.asar=false

Testing

# Run end-to-end tests
npm test

Tests are located in the tests/ directory and use Playwright.

Project Structure

graph TD
    root[smyles-station/]

    root --> packages[packages/]
    root --> tests[tests/<br/>E2E tests]
    root --> docs[docs/<br/>Documentation]
    root --> builder[electron-builder.mjs<br/>Build configuration]
    root --> pkgjson[package.json<br/>Root package.json]

    packages --> main[main/<br/>Electron main process]
    packages --> preload[preload/<br/>Preload scripts]
    packages --> renderer[renderer/<br/>React UI]
    packages --> integrate[integrate-renderer/<br/>Build tooling]
    packages --> versions[electron-versions/<br/>Version helpers]

    main --> main_src[src/]
    main --> main_pkg[package.json]
    main --> main_ts[tsconfig.json]
    main_src --> main_index[index.ts<br/>Entry point]
    main_src --> main_modules[modules/<br/>Feature modules]

    preload --> preload_src[src/]
    preload --> preload_pkg[package.json]
    preload --> preload_ts[tsconfig.json]
    preload_src --> preload_index[index.ts<br/>Exposed APIs]

    renderer --> renderer_src[src/]
    renderer --> renderer_pkg[package.json]
    renderer --> renderer_ts[tsconfig.json]
    renderer_src --> renderer_app[App.tsx]
    renderer_src --> renderer_comp[components/]
    renderer_src --> renderer_assets[assets/]

Development Workflow

Making Changes

Create a feature branch:
```
git checkout -b feature/my-feature
```
Start development mode:
```
npm start
```
Make your changes:
Edit files in the appropriate package
Renderer changes hot-reload automatically
Main process changes trigger automatic restart
Test your changes:
Manually test in the development window
Run type checking: npm run typecheck
Run tests: npm test

Commit your changes:

git add .
git commit -m "Descriptive commit message"

Working with Different Packages

Renderer (UI) Changes

Located in packages/renderer/src/:

React components: components/
Styles: Component-specific .css files
Assets: assets/

Changes hot-reload automatically - no restart needed.

Main Process Changes

Located in packages/main/src/:

Modules: modules/
Entry point: index.ts

Changes trigger automatic application restart in development mode.

Preload Changes

Located in packages/preload/src/:

Exposed APIs: index.ts

Changes require application restart. The preload script acts as a secure bridge between renderer and main.

Debugging

Renderer Process

Chrome DevTools:
Automatically available in development mode
Press Ctrl+Shift+I (Windows/Linux) or Cmd+Option+I (Mac)
Use React DevTools for component inspection
Console Logging:
```
console.log('Debugging info', data);
```

Main Process

Console Logging:
```
console.log('Main process log', data);
```
Output appears in the terminal where you ran npm start.

VS Code Debugging: Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug Main Process",
      "type": "node",
      "request": "launch",
      "cwd": "${workspaceFolder}",
      "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron",
      "windows": {
        "runtimeExecutable": "${workspaceFolder}/node_modules/.bin/electron.cmd"
      },
      "args": [".", "--remote-debugging-port=9223"],
      "outputCapture": "std",
      "console": "integratedTerminal"
    }
  ]
}

Preload Script

Logging appears in the renderer's console (DevTools):

console.log('Preload log', data);

Common Development Tasks

Adding a New npm Package

# Add to a specific workspace
npm install package-name --workspace @app/renderer

# Add to main package
npm install package-name --workspace @app/main

# Add dev dependency to root
npm install -D package-name

Updating Dependencies

# Update all dependencies
npm update

# Update specific package
npm update package-name

Clearing Cache

If you encounter build issues:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Clear Vite cache
rm -rf packages/renderer/.vite

Environment Variables

Environment variables are managed through .env files:

.env                # Shared across all modes
.env.local          # Local overrides (git-ignored)
.env.development    # Development mode only
.env.production     # Production mode only

Important: Only variables prefixed with VITE_ are exposed to the renderer:

# .env.local
VITE_API_KEY=your-key-here  # Available in renderer
SECRET_KEY=secret           # Only available in main process

Access in renderer:

const apiKey = import.meta.env.VITE_API_KEY;

Troubleshooting

"Module not found" errors

# Reinstall dependencies
npm install

TypeScript errors after pulling changes

# Rebuild all packages
npm run build

Application won't start

Check Node.js version: node --version (must be >= 23.0.0)

Clear cache and reinstall:

rm -rf node_modules package-lock.json
npm install

Hot reload not working

Restart development server: Ctrl+C, then npm start
Check that you're editing files in packages/renderer/src/
Main process changes require manual restart

Compiled app behaves differently than dev mode

Test with debug build:
```
npm run compile -- --dir -c.asar=false
```
Check console logs in compiled app (terminal output)
Verify environment variables are set correctly

Next Steps

Read the Architecture Overview to understand system design
Review the Contributing Guide for code standards
Check out existing modules in packages/main/src/modules/ for examples

Getting Help

Issues: Check existing issues or open a new one
Questions: Open a discussion on GitHub
Security: Email smyles-station-safety@proton.me

Happy coding!