Quick Start - Kid Pix Maintainer Guide

Table of Contents

Prerequisites

Before you begin, make sure you understand what Kid Pix is by reading the user quick-start guide.

Required Software:

  • Node.js v18 or higher
  • Yarn package manager
  • Git
  • Python v3.8 or higher (for documentation building)
  • Modern IDE with TypeScript support (VS Code recommended)

Development Environment Setup

1. Get the Code

git clone https://github.com/justinpearson/kidpix.git
cd kidpix

2. Install Dependencies

# Install Node.js dependencies
yarn install

# Install Python dependencies for documentation
# (Optional but recommended: create a virtual environment first)
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

python3 -m pip install -r requirements.txt

This installs:

JavaScript Dependencies:

  • React 19 - UI framework
  • TypeScript - Type safety and developer experience
  • Vite - Fast build tool with HMR
  • Vitest - Jest-compatible testing framework
  • Playwright - Browser automation for e2e tests
  • ESLint + Prettier - Code quality and formatting
  • Husky - Git hooks for automated quality checks

Python Dependencies:

  • MkDocs - Documentation site generator

3. Start Development Server

yarn dev
# Open http://localhost:5173/

Available Development Endpoints:

  • http://localhost:5173/ - Original app using modular JS files (main entry point)

The development server includes:

  • Hot module replacement (HMR) for instant updates
  • TypeScript compilation with error reporting
  • Source maps for debugging
  • Direct serving of individual JS files for easier debugging

4. Verify Your Setup

# Run linting
yarn lint

# Run unit tests
yarn test

# Run e2e tests (opens browser)
yarn test:e2e

# Build for production
yarn build

Development Workflow

Code Organization

New React/TypeScript Structure:

src/
├── assets/           # Static assets (images, sounds, CSS)
├── components/       # React components
├── hooks/           # Custom React hooks
├── utils/           # Utility functions
├── types/           # TypeScript type definitions
├── __tests__/       # Unit tests
└── App.tsx          # Main application component

Legacy JavaScript Structure:

js/
├── init/            # Original initialization code (kiddopaint.js, submenus.js)
├── util/            # Core utilities (display, colors, caching, filters)
├── tools/           # Drawing tools (pencil, brush, eraser, effects)
├── textures/        # Fill pattern generators
├── submenus/        # UI submenu definitions for tool options
├── brushes/         # Brush pattern generators
├── builders/        # Complex shape builders (arrows, roads, rails)
├── stamps/          # Stamp and text systems
└── sounds/          # Audio system and sound library

Important Notes:

  • The main application now loads individual modular files for easier development
  • Individual files in js/ directories are the primary source code
  • Files are loaded in specific order via <script> tags in index.html

Making Changes

For New React Development:

  1. Create/edit components in src/
  2. Add unit tests in src/__tests__/
  3. Add e2e tests in tests/e2e/
  4. Use TypeScript for type safety
  5. Pre-commit hooks automatically run linting and formatting

For JavaScript Development:

  • Edit individual files in js/ subdirectories (init, util, tools, etc.)
  • Changes are automatically picked up by the dev server
  • Files are loaded in specific order: init → util → tools → textures → submenus → brushes → builders → stamps → sounds
  • Use this codebase as foundation for porting to React

Git Workflow

Conventional Commits (enforced by commitlint):

# Examples of proper commit messages
git commit -m "feat(canvas): add drawing tool component"
git commit -m "fix(ui): resolve color picker accessibility issue"
git commit -m "test(tools): add unit tests for brush generator"

Pre-commit Hooks:

  • ESLint automatically fixes code style issues
  • Prettier formats all files
  • TypeScript compilation checked
  • Commit message format validated

Testing Your Changes

Unit Testing (Vitest)

yarn test          # Run tests once
yarn test:ui       # Interactive test runner
yarn test --watch  # Watch mode during development

End-to-End Testing (Playwright)

yarn test:e2e                    # Run all browsers
yarn test:e2e --project=chromium # Single browser
yarn test:e2e --headed           # See browser during test

Manual Testing Checklist

  • [ ] Drawing tools work correctly
  • [ ] Color picker functions properly
  • [ ] Audio plays when expected
  • [ ] Responsive design works on mobile
  • [ ] Keyboard shortcuts function
  • [ ] Local storage saves/loads artwork

Performance Testing

  • [ ] Large drawings remain responsive
  • [ ] No memory leaks during extended use
  • [ ] Canvas operations are smooth
  • [ ] Build bundle size is reasonable

Deployment

Automatic Deployment

  • Main branch: Auto-deploys to GitHub Pages via GitHub Actions
  • PR branches: Build and test verification only

Manual Deployment Testing

yarn build          # Create production build
yarn preview        # Test production build locally

Technology Decisions

Why These Tools?

Vite over Create React App:

  • Faster development server with native ESM
  • Better TypeScript integration
  • Smaller bundle sizes
  • Modern tooling ecosystem

Vitest over Jest:

  • Native Vite integration
  • Faster test execution
  • Same API as Jest (easy migration)
  • Better ESM support

Playwright over Cypress:

  • Multiple browser testing (Chrome, Firefox, Safari)
  • Better CI/CD integration
  • More reliable for canvas testing
  • Native TypeScript support

Yarn over npm:

  • Deterministic dependency resolution
  • Better workspace management
  • Faster installation

Next Steps