Project Setup: Package scaffold, Happy DOM fork, directory structure, CI #1

New issue

Closed

opened 2026-06-17 13:37:42 +00:00 by Artur · 1 comment

Artur commented

2026-06-17 13:37:42 +00:00

Owner

Goal

Set up the project foundation: fork Happy DOM, install dependencies, create directory structure, configure TypeScript strict mode, set up CI.

What to Build

1.1 Happy DOM Fork

bun add happy-dom

Happy DOM already provides: Window, Document, HTMLElement, SVGElement, Event/CustomEvent, Custom Elements, Shadow DOM, MutationObserver (real), HTML Parser (basic), Form APIs, TreeWalker/NodeIterator/Range.

We fork and store under src/dom/happy-dom-fork/ so we can patch behavior without waiting for upstream.

1.2 Directory Structure

src/
  dom/               -> HTML parser, Document, Element implementations
  js/                -> Script loader, module graph, timers
  network/           -> fetch, XHR, WebSocket, cookies, log
  storage/           -> localStorage, sessionStorage, document.cookie
  observers/         -> MutationObserver, IntersectionObserver, ResizeObserver
  fakes/             -> Canvas/WebGL, Layout, Media/Fonts, Permissions
  pages/             -> Runner, Stabilizer, Output
  diagnostics/       -> API logger, failure recorder
  tolerant-proxy.ts  -> Central tolerantProxy
  runtime-isolation.ts -> Isolated context factory
  browser-context.ts -> Full context factory
tests/
  unit/              -> Unit tests
  fixtures/          -> HTML fixture files
scripts/             -> Issue creation scripts
index.ts             -> CLI entry point

1.3 TypeScript Strict Mode

compilerOptions:
  strict: true
  noUncheckedIndexedAccess: true
  noImplicitReturns: true
  noFallthroughCasesInSwitch: true
  exactOptionalPropertyTypes: true
  forceConsistentCasingInFileNames: true
  noEmit: true
  moduleResolution: bundler
  allowImportingTsExtensions: true
  verbatimModuleSyntax: true

1.4 Package Scripts

scripts:
  crawl:strict:   bun run src/index.ts
  test:           bun test
  test:coverage:  bun test --coverage
  typecheck:      bun run tsc --noEmit
  lint:           bun run typecheck

1.5 CI (Forgejo Actions)

File: .forgejo/workflows/ci.yml

on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun run typecheck
      - run: bun test --coverage

Tests

Unit Tests

Test	Verifies
project-structure.test.ts	All directories exist, all src/*.ts have corresponding tests
tsconfig.test.ts	tsconfig.json has strict:true
happy-dom-import.test.ts	Happy DOM can be imported, Window/Document are instantiable
ci-config.test.ts	.forgejo/workflows/ci.yml exists, is valid YAML

Definition of Done

bun add happy-dom done
All directories exist
tsconfig.json with strict mode
package.json with all scripts
.forgejo/workflows/ci.yml exists
bun test --coverage runs without error
bun run typecheck runs without error

## Goal Set up the project foundation: fork Happy DOM, install dependencies, create directory structure, configure TypeScript strict mode, set up CI. ## What to Build ### 1.1 Happy DOM Fork ``` bun add happy-dom ``` Happy DOM already provides: Window, Document, HTMLElement, SVGElement, Event/CustomEvent, Custom Elements, Shadow DOM, MutationObserver (real), HTML Parser (basic), Form APIs, TreeWalker/NodeIterator/Range. We fork and store under `src/dom/happy-dom-fork/` so we can patch behavior without waiting for upstream. ### 1.2 Directory Structure ``` src/ dom/ -> HTML parser, Document, Element implementations js/ -> Script loader, module graph, timers network/ -> fetch, XHR, WebSocket, cookies, log storage/ -> localStorage, sessionStorage, document.cookie observers/ -> MutationObserver, IntersectionObserver, ResizeObserver fakes/ -> Canvas/WebGL, Layout, Media/Fonts, Permissions pages/ -> Runner, Stabilizer, Output diagnostics/ -> API logger, failure recorder tolerant-proxy.ts -> Central tolerantProxy runtime-isolation.ts -> Isolated context factory browser-context.ts -> Full context factory tests/ unit/ -> Unit tests fixtures/ -> HTML fixture files scripts/ -> Issue creation scripts index.ts -> CLI entry point ``` ### 1.3 TypeScript Strict Mode ``` compilerOptions: strict: true noUncheckedIndexedAccess: true noImplicitReturns: true noFallthroughCasesInSwitch: true exactOptionalPropertyTypes: true forceConsistentCasingInFileNames: true noEmit: true moduleResolution: bundler allowImportingTsExtensions: true verbatimModuleSyntax: true ``` ### 1.4 Package Scripts ``` scripts: crawl:strict: bun run src/index.ts test: bun test test:coverage: bun test --coverage typecheck: bun run tsc --noEmit lint: bun run typecheck ``` ### 1.5 CI (Forgejo Actions) File: `.forgejo/workflows/ci.yml` ``` on: [push, pull_request] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: oven-sh/setup-bun@v2 - run: bun install - run: bun run typecheck - run: bun test --coverage ``` ## Tests ### Unit Tests | Test | Verifies | |------|----------| | project-structure.test.ts | All directories exist, all src/*.ts have corresponding tests | | tsconfig.test.ts | tsconfig.json has strict:true | | happy-dom-import.test.ts | Happy DOM can be imported, Window/Document are instantiable | | ci-config.test.ts | .forgejo/workflows/ci.yml exists, is valid YAML | ## Definition of Done - [ ] `bun add happy-dom` done - [ ] All directories exist - [ ] tsconfig.json with strict mode - [ ] package.json with all scripts - [ ] .forgejo/workflows/ci.yml exists - [ ] `bun test --coverage` runs without error - [ ] `bun run typecheck` runs without error