Merge pull request #303 from knockout/modern-tooling/phase-1-bun

Replace Karma with Vitest, add Bun support

Author: brianmhunt

.github/workflows/lint-and-typecheck.yml

@@ -1,6 +1,4 @@
 # Combined lint, format, and typecheck workflow.
-# Replaces separate eslint.yml, prettier.yml, and run-tsc.yml to avoid
-# running npm install three times.
 name: Lint & Typecheck
 
 on:
@@ -15,14 +13,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v6
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 22.x
-          cache: 'npm'
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
 
       - name: Install dependencies
-        run: npm install
+        run: bun install --frozen-lockfile
 
       - name: Check Prettier
         run: make format
@@ -34,4 +29,4 @@ jobs:
         run: make
 
       - name: Typecheck
-        run: npx tsc
+        run: bunx tsc

.github/workflows/main-build.yml

@@ -2,41 +2,37 @@
 name: Build
 
 on:
-  # Runs on pushes targeting the default branch
   push:
     branches: ["main"]
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 jobs:
   test:
     runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [24.x]
+    container:
+      image: mcr.microsoft.com/playwright:v1.59.1-noble
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+      - name: Install system dependencies
+        run: apt-get update && apt-get install -y unzip make
 
-      - name: Install dependencies
-        run: npm install
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
 
-      - name: Audit for vulnerabilities (prod-mode)
-        run: npm audit --audit-level=high --production
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
 
       - name: Run Build
         run: make
 
       - name: Run tests
-        run: make test-headless
+        run: bunx vitest run
+        env:
+          HOME: /root
+          VITEST_BROWSERS: chromium,firefox,webkit
 
       - name: Upload build artifacts
         uses: actions/upload-artifact@v7

.github/workflows/publish-check.yml

@@ -14,14 +14,16 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v6
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+
       - name: Setup Node.js
         uses: actions/setup-node@v6
         with:
-          node-version: 22.x
-          cache: 'npm'
+          node-version: 24.x
 
       - name: Install dependencies
-        run: npm install
+        run: bun install --frozen-lockfile
 
       - name: Build all packages
         run: make

.github/workflows/test-headless.yml

@@ -2,35 +2,33 @@
 name: Check Tests
 
 on:
-  # Runs for every pull-requests created
   pull_request:
-  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 jobs:
-  testheadless:
+  test:
     runs-on: ubuntu-latest
-
-    strategy:
-      matrix:
-        node-version: [24]
-        run: ['test-headless','test-headless-jquery', 'test-headless-ff']
+    container:
+      image: mcr.microsoft.com/playwright:v1.59.1-noble
 
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+      - name: Install system dependencies
+        run: apt-get update && apt-get install -y unzip make
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
 
       - name: Install dependencies
-        run: npm install
+        run: bun install --frozen-lockfile
 
       - name: Run Build
         run: make
 
-      - name: Run ${{ matrix.run }}
-        run: make ${{ matrix.run }}
+      - name: Run Tests
+        run: bunx vitest run
+        env:
+          HOME: /root
+          VITEST_BROWSERS: chromium,firefox,webkit

.gitignore

@@ -34,3 +34,4 @@ builds/**/meta
 .vscode/settings.json
 .playwright-mcp
 .playwright-cli
+__screenshots__

.tool-versions

@@ -0,0 +1 @@
+bun 1.3.12

.vscode/launch.json

@@ -1,18 +1,13 @@
 {
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
         {
             "type": "chrome",
             "request": "attach",
-            "name": "Attach to Karma-Chrome",
-            "sourceMaps": true, 
-           // "restart": true,         
-           // "timeout":180000,  
-            "port": 9222,            
+            "name": "Attach to Vitest Browser",
+            "sourceMaps": true,
+            "port": 9222,
             "webRoot": "${workspaceFolder}"
         }
     ]
-}
+}

AGENTS.md

@@ -51,7 +51,7 @@ Lerna monorepo with npm workspaces. Current version: see `lerna.json`.
 ```
 packages/          # 25 modular @tko/* packages (all TypeScript)
 builds/            # 2 bundled distributions (knockout, reference)
-tools/             # Shared build config (build.mk, karma.conf.js, repackage.mjs)
+tools/             # Shared build config (build.mk, repackage.mjs)
 skills/            # AI agent skills (on-demand workflow instructions)
 tko.io/            # Documentation site (Astro + Starlight, deployed to GitHub Pages)
 Makefile           # Top-level build orchestrator
@@ -63,25 +63,26 @@ Key packages: `@tko/observable`, `@tko/computed`, `@tko/bind`,
 Builds: `@tko/build.knockout` (backwards-compatible) and
 `@tko/build.reference` (modern/recommended).
 
+## Prerequisites
+
+- **Bun** — package manager and script runner. Install via [mise](https://mise.jdx.dev/): `mise install` (reads `.tool-versions`), or [bun.sh](https://bun.sh).
+- Use `bun install` instead of `npm install`.
+
 ## Build Commands
 
 All builds use Make + esbuild. Run from the repo root:
 
 ```bash
-npm install               # Install all dependencies (uses npm workspaces)
+bun install               # Install all dependencies (uses Bun workspaces)
 make                      # Build all packages (ESM, CommonJS, MJS)
-make test                 # Run all tests with Electron
-make test-headless        # Run all tests with headless Chrome
-make test-headless-ff     # Run all tests with headless Firefox
-make test-headless-jquery # Run tests with jQuery enabled
-make test-coverage        # Run tests and generate coverage report
+make test                 # Run all tests (Vitest, headless Chromium via Playwright)
+bunx vitest run           # Same as make test, directly
 make eslint               # Run ESLint
 make eslint-fix           # Run ESLint with auto-fix
 make format               # Check Prettier formatting
 make format-fix           # Fix Prettier formatting
 make tsc                  # TypeScript type-check (no emit)
 make dts                  # Generate TypeScript declaration files
-make knip                 # Run Knip for Linting imports and exports
 make sweep                # Clean dist/ and coverage/ dirs
 make clean                # Full clean (node_modules, lockfiles, dist)
 ```
@@ -91,17 +92,14 @@ Make targets (they include `tools/build.mk`).
 
 ## Testing
 
-- **Runner**: Karma
-- **Frameworks**: Mocha + Chai + Sinon
-- **Browsers**: Electron (default), Chrome Headless, Firefox Headless
-- **Coverage**: nyc/Istanbul (~89% statements, ~83% branches)
-- **Test files**: `packages/*/spec/` directories
-
-Use Mocha/Chai/Sinon for repository tests.
+- **Runner**: Vitest browser mode (Playwright, headless Chromium)
+- **Assertions**: Chai (expect) + Sinon (spies/stubs/timers)
+- **Config**: `vitest.config.ts` at repo root
+- **Test files**: `packages/*/spec/**/*.ts`, `builds/*/spec/**/*.js`
+- **Run**: `bunx vitest run` (all tests) or `bunx vitest run <path>` (single file)
 
-Do not:
-- split shared specs into runner-specific versions while they still need to run
-  in the browser harness
+Tests run in a real browser via Playwright — not jsdom. This is required
+because TKO does low-level DOM manipulation, MutationObserver, and event handling.
 
 ## Code Style
 
@@ -231,7 +229,7 @@ When validating `tko.io` documentation changes with the local docs site:
 
 ## Important Guidelines
 
-- Do not modify `tools/build.mk` or `tools/karma.conf.js` without understanding
+- Do not modify `tools/build.mk` or `vitest.config.ts` without understanding
   the full impact — they are shared across all 25+ packages.
 - Do not add runtime dependencies to core packages. TKO is zero-dependency.
 - The `builds/` packages bundle everything into a single distributable.

AI_COMPLIANCE.md

@@ -84,7 +84,7 @@ security-critical rule.
 
 - `.github/workflows/`
 - `tools/build.mk`
-- `tools/karma.conf.js`
+- `vitest.config.ts`
 - release and publish controls (`.changeset/`, release scripts/workflows)
 - authentication/publishing and CI secret flow configuration
 

Makefile

@@ -1,7 +1,5 @@
-NPX		:= npx
-NODE  	:= node
-NPM		:= npm
-LERNA	:= npx lerna
+BUNX	:= bunx
+LERNA	:= $(BUNX) lerna
 DOCKER	:= docker
 
 # Some make settings
@@ -15,50 +13,38 @@ default: all
 
 package.json:
 
-node_modules: package-lock.json
+node_modules: package.json bun.lock packages/*/package.json
+	bun install
 
-all:: node_modules package-lock.json
+all:: node_modules
 	$(LERNA) --concurrency $(CONCURRENCY) exec --stream -- $(MAKE)
 
-test:
-	$(LERNA) exec --stream -- $(MAKE) test
-
-test-headless:
-	$(LERNA) exec --stream -- $(MAKE) test-headless
-
-# Instrumentalization via CLI: $(LERNA) exec --stream -- $(NPX) instrument dist --in-place
-# We have done it with a Esbuild-Plugin in the karma.conf.js-file
-# To manually merge coverage files: $(NPX) nyc merge coverage ../../coverage-temp/coverage-final.json
-test-coverage:
-	$(LERNA) exec --stream -- $(MAKE) test-coverage   
-	$(NPX) nyc report --reporter=html --reporter=text --reporter=cobertura --report-dir=coverage --temp-dir=coverage-temp --exclude="**/browser.min.js" --exclude="**/spec/*" > COVERAGE.md
-
-test-headless-jquery:
-	$(LERNA) exec --stream -- $(MAKE) test-headless-jquery
+test test-headless:
+	$(BUNX) vitest run
 
 test-headless-ff:
-	$(LERNA) exec --stream -- $(MAKE) test-headless-ff
+	VITEST_BROWSERS=firefox $(BUNX) vitest run
 
-ci:
-	$(LERNA) exec --stream --concurrency=1 -- $(MAKE) test-ci
+test-headless-jquery:
+	VITEST_BROWSERS=chromium $(BUNX) vitest run
 
 format:
-	$(NPX) prettier . --check
+	$(BUNX) prettier . --check
 
 format-fix:
-	$(NPX) prettier . --write
+	$(BUNX) prettier . --write
 
 tsc:
-	$(NPX) tsc
+	$(BUNX) tsc
 
 eslint:
-	$(NPX) eslint .
+	$(BUNX) eslint .
 
 eslint-fix:
-	$(NPX) eslint . --fix
+	$(BUNX) eslint . --fix
 
 dts:
-	$(NPX) tsc --build tsconfig.dts.json
+	$(BUNX) tsc --build tsconfig.dts.json
 
 docker-build:
 	$(DOCKER) build . --tag tko
@@ -77,20 +63,18 @@ bump:
 publish-unpublished: all link
 	$(LERNA) publish from-package
 
-package-lock.json: package.json packages/*/package.json
-	$(NPM) i
+bun.lock: package.json packages/*/package.json
+	bun install
 
 package.json:
 
-install: node_modules
-
 outdated-list:
-	$(NPM) outdated
+	bun outdated
 
 outdated-upgrade:
-	$(NPM) upgrade-interactive --latest
+	bun upgrade-interactive --latest
 
-install: package-lock.json
+install: bun.lock
 
 sweep:
 	rm -rf packages/*/dist/*
@@ -100,12 +84,9 @@ sweep:
 
 clean: sweep
 	rm -rf node_modules/
-	rm -f package-lock.json
-	rm -rf packages/*/package-lock.json
-	rm -rf builds/*/package-lock.json
 
 
 # Local linking of these packages, so they
 # are available for local testing/dev.
 link:
-	$(LERNA) exec --stream -- npm link
+	$(LERNA) exec --stream -- bun link