Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
473 lines (344 loc) · 9.01 KB

DEVELOPMENT.md

File metadata and controls

473 lines (344 loc) · 9.01 KB

Development Guide

Overview

This guide provides information for developers working on Vectorizer Sync, including setup instructions, development workflow, and coding standards.

Prerequisites

Required Software

  • Node.js: Version 20.x or later
  • npm or pnpm: Package manager
  • Git: Version control
  • TypeScript: Version 5.x or later

Platform-Specific Requirements

Windows

  • Visual Studio Build Tools (for native modules)
  • Windows SDK

macOS

  • Xcode Command Line Tools
  • macOS 10.15 or later

Linux

  • Build essentials (gcc, make, etc.)
  • libnss3-dev (for Electron)

Project Setup

Clone Repository

git clone <repository-url>
cd vectorizer-sync

Install Dependencies

npm install
# or
pnpm install

Environment Setup

Create .env file (optional, for development):

NODE_ENV=development
LOG_LEVEL=debug
DB_PATH=./dev-database.db

Project Structure

vectorizer-sync/
├── src/
│   ├── main/              # Electron main process
│   │   ├── index.ts        # Main entry point
│   │   ├── database/       # Database management
│   │   ├── sync/           # Sync engine
│   │   ├── watcher/        # File system watcher
│   │   └── api/            # HiveHub API client
│   ├── renderer/           # Electron renderer process (React)
│   │   ├── components/     # React components
│   │   ├── pages/          # Page components
│   │   ├── hooks/          # React hooks
│   │   ├── store/          # State management
│   │   └── utils/          # Utility functions
│   └── shared/             # Shared code between main and renderer
│       ├── types/           # TypeScript types
│       └── constants/       # Constants
├── tests/                   # Test files
│   ├── unit/               # Unit tests
│   ├── integration/        # Integration tests
│   └── e2e/                # End-to-end tests
├── docs/                    # Documentation
├── scripts/                 # Build and utility scripts
├── public/                  # Static assets
└── package.json

Development Workflow

Running in Development Mode

npm run dev

This will:

  1. Start Electron in development mode
  2. Enable hot reload for renderer process
  3. Open DevTools automatically
  4. Watch for file changes

Building

# Build for current platform
npm run build

# Build for specific platform
npm run build:win
npm run build:mac
npm run build:linux

# Build for all platforms
npm run build:all

Testing

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests
npm run test:integration

# Run E2E tests
npm run test:e2e

# Run tests with coverage
npm run test:coverage

Linting

# Run linter
npm run lint

# Fix linting issues
npm run lint:fix

Type Checking

npm run type-check

Coding Standards

TypeScript

  • Use strict mode
  • Prefer interfaces over types for object shapes
  • Use const assertions where appropriate
  • Avoid any type (use unknown if needed)
  • Use async/await instead of promises
  • Handle errors explicitly

Code Style

  • Use 2 spaces for indentation
  • Use single quotes for strings
  • Use trailing commas
  • Maximum line length: 100 characters
  • Use meaningful variable and function names

File Naming

  • Components: PascalCase (e.g., ProjectList.tsx)
  • Utilities: camelCase (e.g., fileUtils.ts)
  • Types: PascalCase (e.g., Project.ts)
  • Constants: UPPER_SNAKE_CASE (e.g., MAX_FILE_SIZE.ts)

React Components

// Component structure
import React from 'react';
import { Project } from '../types';

interface ProjectListProps {
  projects: Project[];
  onSelect: (project: Project) => void;
}

export const ProjectList: React.FC<ProjectListProps> = ({ projects, onSelect }) => {
  // Component logic
  return (
    <div>
      {/* JSX */}
    </div>
  );
};

Error Handling

// Always handle errors explicitly
try {
  await someAsyncOperation();
} catch (error) {
  if (error instanceof Error) {
    console.error('Operation failed:', error.message);
    // Handle error appropriately
  }
}

Database Development

Database Setup

The database is automatically created on first run. For development:

import Database from 'better-sqlite3';

const db = new Database('./dev-database.db');
// Initialize schema

Running Migrations

npm run db:migrate

Database Reset

npm run db:reset

Warning: This will delete all data!

IPC Communication

Main Process → Renderer

// main/index.ts
import { BrowserWindow } from 'electron';

const window = BrowserWindow.getFocusedWindow();
window?.webContents.send('event-name', data);

Renderer → Main Process

// renderer/components/MyComponent.tsx
import { ipcRenderer } from 'electron';

const result = await ipcRenderer.invoke('action-name', data);

IPC Handlers

// main/ipc/handlers.ts
import { ipcMain } from 'electron';

ipcMain.handle('action-name', async (event, data) => {
  // Handle action
  return result;
});

File System Operations

Reading Files

import { readFile } from 'fs/promises';
import { join } from 'path';

const content = await readFile(join(projectPath, 'file.txt'), 'utf-8');

Watching Files

import chokidar from 'chokidar';

const watcher = chokidar.watch(projectPath, {
  ignored: /node_modules/,
  persistent: true
});

watcher.on('change', (path) => {
  // Handle file change
});

Testing

Unit Tests

// tests/unit/fileUtils.test.ts
import { describe, it, expect } from 'vitest';
import { isFileExcluded } from '../../src/shared/utils/fileUtils';

describe('fileUtils', () => {
  it('should exclude node_modules', () => {
    expect(isFileExcluded('node_modules/file.js')).toBe(true);
  });
});

Integration Tests

// tests/integration/database.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import Database from 'better-sqlite3';

describe('Database', () => {
  let db: Database.Database;

  beforeAll(() => {
    db = new Database(':memory:');
    // Initialize schema
  });

  afterAll(() => {
    db.close();
  });

  it('should create project', () => {
    // Test database operations
  });
});

E2E Tests

// tests/e2e/sync.test.ts
import { test, expect } from '@playwright/test';

test('should sync files', async ({ page }) => {
  await page.goto('http://localhost:3000');
  // Test user interactions
});

Debugging

Main Process Debugging

Add breakpoints in VS Code or use:

debugger; // Breakpoint

Renderer Process Debugging

Use Chrome DevTools (automatically opened in dev mode).

Database Debugging

// Enable verbose logging
const db = new Database('./database.db', {
  verbose: console.log
});

Performance Optimization

Database Queries

  • Use prepared statements
  • Use transactions for batch operations
  • Create appropriate indexes
  • Limit result sets

File Operations

  • Batch file operations
  • Use streaming for large files
  • Cache file metadata
  • Debounce file watcher events

React Performance

  • Use React.memo for expensive components
  • Use useMemo and useCallback appropriately
  • Avoid unnecessary re-renders
  • Code split large components

Building for Production

Electron Builder Configuration

Configuration in package.json:

{
  "build": {
    "appId": "com.hivellm.vectorizer-sync",
    "productName": "Vectorizer Sync",
    "directories": {
      "output": "dist"
    },
    "files": [
      "dist/**/*",
      "package.json"
    ],
    "win": {
      "target": "nsis"
    },
    "mac": {
      "target": "dmg"
    },
    "linux": {
      "target": "AppImage"
    }
  }
}

Code Signing

For production builds, configure code signing:

  • Windows: Configure in win section
  • macOS: Configure in mac section
  • Linux: Not required

Release Process

  1. Update version in package.json
  2. Update CHANGELOG.md
  3. Run tests: npm test
  4. Build: npm run build:all
  5. Create git tag: git tag v1.0.0
  6. Push tag: git push --tags

Troubleshooting

Common Issues

Database Locked

Solution: Ensure only one instance accesses the database at a time.

Native Module Build Fails

Solution: Install platform-specific build tools.

Electron DevTools Not Opening

Solution: Check main/index.ts for DevTools configuration.

File Watcher Not Working

Solution: Check file permissions and watcher configuration.

Resources