Skip to content

README.md

Latest commit

 

History

History
216 lines (161 loc) · 8.49 KB

README.md

File metadata and controls

216 lines (161 loc) · 8.49 KB
Raw

LiveCodes Contribution Guide

This directory contains comprehensive documentation for contributors working on the LiveCodes codebase. Each document covers a specific system or aspect of the application.

New to contributing? Start with the beginner-friendly introduction, including setup instructions, pull request guidelines, and code of conduct.

Quick Start

  1. Read the Architecture Overview first to understand the high-level design
  2. Review the Build System to understand how the project is built
  3. Check the Code Style section below for coding conventions

Documentation Index

Core Systems

Document Description
architecture.mdx High-level architecture overview with diagrams of all major systems
compiler-system.mdx Language compilation pipeline, worker architecture, and import resolution
config-system.mdx Configuration management, validation, and URL parameter handling
storage-system.mdx Client-side storage using IndexedDB and localStorage

Editor & UI

Document Description
editor-system.mdx Multi-editor support (Monaco, CodeMirror, CodeJar) and themes
ui-design-system.mdx UI components, styling, theming, and responsive design
tools-pane-system.mdx Console, compiled code viewer, and test runner
notifications-system.md Toast notification system

Language Support

Document Description
language-support-system.mdx Language specifications, processors, and utilities
adding-languages.mdx Step-by-step guide to add new language support
type-loader-system.mdx TypeScript type acquisition for IntelliSense

Features

Document Description
import-system.mdx Import from GitHub, GitLab, files, URLs, and more
export-system.mdx Export to JSON, ZIP, HTML, CodePen, JSFiddle, GitHub Gist
result-page.mdx Result iframe generation and sandbox creation
code-formatting-system.mdx Prettier integration and custom formatters

Services & Infrastructure

Document Description
services-system.mdx External services: auth, share, CDN resolution, CORS proxy
build-system.mdx Build scripts, outputs, and development workflow

Internationalization

Document Description
i18n.mdx Translation workflow, Lokalise integration, and script reference

SDK

Document Description
sdk.mdx SDK architecture, framework wrappers, and API communication

Testing & Development

Document Description
storybook.mdx Storybook setup for SDK component testing

Release

Document Description
release.mdx Release workflow and version management

Deployment

Document Description
deployment.mdx GitHub Actions deployment workflows and guards

Code Style

LiveCodes follows specific coding conventions documented in AGENTS.md at the repository root. Key points:

Formatting (Prettier)

  • Semicolons: always
  • Single quotes
  • Trailing commas: all
  • Print width: 100

Imports

Use import type for type-only imports:

import type { Config, Language } from '../models';
import { someFunction } from '../utils';

Naming Conventions

  • Files/directories: kebab-case (build-config.ts)
  • Functions/variables: camelCase (createEventsManager)
  • Types/interfaces: PascalCase (CompileResult)
  • No enums: use string union types

Functions and Exports

  • Arrow function constants preferred
  • Named exports only (no default exports)
  • No classes in application code
  • Use factory functions (createXxx())
  • One variable per statement

Testing

Tests are co-located in __tests__/ directories:

import { debounce } from '..';

describe('utils', () => {
  test('debounce', async () => {
    expect(num).toBe(1);
  });
});

Running Tests

npm run test              # Run all tests (typecheck + lint + unit)
npm run test:unit         # Run Jest unit tests only
npm run test:unit -- --testPathPattern="compiler"  # Run specific tests
npm run e2e               # Run Playwright e2e tests
npm run typecheck:app     # TypeScript type check
npm run lint:eslint       # ESLint check
npm run fix               # Auto-fix all linting issues

Development Workflow

npm run start             # Dev server with watch (http://127.0.0.1:8080)
npm run build             # Full production build
npm run docs              # Start documentation server (http://localhost:3000/docs)
npm run storybook         # Start storybook (http://localhost:6006)

Architecture Overview

flowchart TD
    subgraph "Core"
        A[core.ts<br/>Main Application]
        B[config/<br/>Configuration]
        C[storage/<br/>Persistence]
        D[events/<br/>Event System]
    end

    subgraph "Editors"
        E[monaco.ts]
        F[codemirror.ts]
        G[codejar.ts]
    end

    subgraph "Compilation"
        H[compiler/<br/>Worker-based]
        I[languages/<br/>Language Specs]
        J[formatter/<br/>Prettier + Custom]
    end

    subgraph "UI"
        K[UI/<br/>App Controllers]
        L[html/<br/>Templates]
        M[toolspane/<br/>Console/Tests]
    end

    subgraph "Services"
        N[auth.ts]
        O[share.ts]
        P[modules.ts]
        Q[sandbox.ts]
    end

    A --> B & C & D
    A --> E & F & G
    A --> H
    H --> I
    A --> J
    A --> K
    K --> L
    A --> M
    A --> N & O & P & Q
Loading

Key Design Principles

  1. Client-side only - All compilation happens in the browser
  2. Worker-based compilation - Heavy work off main thread
  3. Lazy loading - Compilers and editors loaded on demand
  4. Modular architecture - Factory functions, no classes
  5. Type safety - Strict TypeScript with explicit types

Getting Help