@koppajs/koppajs-example

Minimal starter template for KoppaJS

Everything you need to start building, plus a proportional quality baseline.

Documentation · KoppaJS Core · Vite Plugin · Issues

Table of Contents

1. What is this?
2. Requirements
3. Getting Started
4. Quality Workflow
5. Release Workflow
6. Project Structure
7. Meta Layer
8. Community & Contribution
9. License

---

What is this?

This is the official minimal starter template for KoppaJS.

It keeps the runtime intentionally small:

• one HTML shell
• one TypeScript bootstrap file
• one root view
• one stateful child component

It also carries a small quality baseline so the starter stays runnable and trustworthy:

• ESLint for source and tooling files
• Prettier plus .editorconfig for supported text formats
• Vitest for local unit and integration coverage
• Playwright for a real-browser smoke test
• Husky plus lint-staged for fast staged-file checks
• Conventional Commits enforcement via commitlint
• a tag-driven GitHub release baseline with CHANGELOG.md and RELEASE.md

Use it as a starting point for new KoppaJS projects or as a reference for how components are registered, composed, and validated.

Note: This repository uses published npm packages, so it works as a standalone starter after pnpm install.

---

Requirements

• Node.js >= 20
• pnpm >= 10

---

Getting Started

pnpm install
pnpm dev

Install the Playwright browser once if you want to run the browser smoke test locally:

pnpm exec playwright install chromium

Useful commands:

pnpm lint
pnpm format:check
pnpm typecheck
pnpm test:run
pnpm test:coverage
pnpm build
pnpm serve
pnpm release:check

Commit messages follow Conventional Commits, for example:

feat: add release workflow
docs: update starter governance
fix: align counter button labels

---

Quality Workflow

Fast local baseline:

pnpm check

Full validation, including Playwright:

pnpm validate

Standalone browser smoke test:

pnpm test:e2e

---

Release Workflow

Tagged releases are documented in CHANGELOG.md. The maintainer procedure lives in RELEASE.md.

Release tags must use the form vX.Y.Z and match package.json. The automation creates GitHub Releases only; this repository remains private and is not published to npm.

---

Project Structure

koppajs-example/
├── .npmrc
├── CHANGELOG.md
├── commitlint.config.mjs
├── AI_CONSTITUTION.md
├── ARCHITECTURE.md
├── CONTRIBUTING.md
├── DECISION_HIERARCHY.md
├── DEVELOPMENT_RULES.md
├── RELEASE.md
├── ROADMAP.md
├── TESTING_STRATEGY.md
├── eslint.config.mjs
├── index.html
├── package.json
├── playwright.config.ts
├── prettier.config.mjs
├── tsconfig.json
├── vite.config.mjs
├── vitest.config.mjs
├── docs/
│   ├── adr/
│   ├── architecture/
│   ├── meta/
│   ├── quality/
│   └── specs/
├── public/
│   └── favicon.svg
├── src/
│   ├── main.ts
│   ├── style.css
│   ├── app-view.kpa
│   └── counter-component.kpa
└── tests/
    ├── e2e/
    ├── integration/
    └── unit/

---

Meta Layer

The repository includes an explicit meta layer so architecture, testing, and contributor rules evolve together with the codebase.

Start here:

• DECISION_HIERARCHY.md
• AI_CONSTITUTION.md
• ARCHITECTURE.md
• DEVELOPMENT_RULES.md
• TESTING_STRATEGY.md
• CHANGELOG.md
• RELEASE.md
• docs/quality/quality-gates.md
• docs/adr/
• docs/specs/

---

Community & Contribution

Issues and pull requests are welcome:

https://github.com/koppajs/koppajs-example/issues

Contribution workflow details live in CONTRIBUTING.md.

---

License

Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch