koppajs-documentation

Canonical documentation website for the KoppaJS ecosystem

The shared landing point for long-form docs, package guidance, and ecosystem-level explanations.

KoppaJS Core · Vite Plugin · Router · create-koppajs · Issues

Table of Contents

1. What is this repository?
2. Requirements
3. Getting Started
4. Documentation Surface
5. Testing & Quality
6. Architecture & Governance
7. Community & Contribution
8. License

---

What is this repository?

koppajs-documentation is the dedicated documentation website for the KoppaJS ecosystem.

It now combines two responsibilities in one place:

• a routed KoppaJS application shell for long-form framework documentation
• the canonical root repository docs and governance layer for the docs site itself

That keeps package repos focused on package-local contracts while broader guides, onboarding flows, and cross-package explanations have a real application surface to live in and be tested against.

---

Requirements

• Node.js >= 22
• npm >= 10

Install the Playwright browser locally if you want to run end-to-end tests:

npx playwright install chromium

---

Getting Started

npm install
npm run dev

Useful commands:

• npm run check
• npm run test:run
• npm run test:e2e
• npm run build
• npm run serve
• npm run validate
• npm run release:check

---

Documentation Surface

The website is intentionally small but real:

• src/components/app-shell.kpa owns the persistent frame, hero section, and route outlet
• src/app-routes.ts defines the documentation routes and explicit catch-all page
• src/pages/*.kpa contains route-level documentation pages
• src/main.ts registers KoppaJS components, boots Core(), and starts the router
• RELEASE.md and docs/quality/ define the current release and verification baseline

Current top-level routes:

• /
• /getting-started
• /packages
• /testing
• * -> not-found fallback

The main implementation references for the site are:

• @koppajs/koppajs-core
• @koppajs/koppajs-vite-plugin
• @koppajs/koppajs-router

---

Testing & Quality

The repository now treats the docs website as executable surface area:

• Vitest covers route metadata and bootstrap behavior
• Playwright covers real browser navigation and not-found handling
• GitHub Actions runs the main quality gate on Node.js 22 and 24
• the browser smoke test runs on Node.js 22 with Playwright Chromium

Local quality baseline:

npm run check

---

Architecture & Governance

Project intent, contributor rules, runtime boundaries, and documentation contracts live in the local repo meta layer:

• ARCHITECTURE.md
• DECISION_HIERARCHY.md
• TESTING_STRATEGY.md
• DEVELOPMENT_RULES.md
• CHANGELOG.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• RELEASE.md
• ROADMAP.md
• docs/adr/README.md
• docs/architecture/README.md
• docs/meta/README.md
• docs/quality/README.md
• docs/specs/README.md
• docs/specs/repository-documentation-contract.md
• docs/specs/documentation-website.md

The file-shape contract for README.md, CHANGELOG.md, CODE_OF_CONDUCT.md, and CONTRIBUTING.md is defined in docs/specs/repository-documentation-contract.md.

Run the local document guard before committing:

npm run check:docs

---

Community & Contribution

Issues and pull requests are welcome:

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

Contributor workflow details live in CONTRIBUTING.md.

Community expectations live in CODE_OF_CONDUCT.md.

---

License

Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch