https://github.com/koppajs/koppajs-core
Minimal frontend framework with .kpa components, proxy reactivity, and no hidden layers. Built for clarity, speed, and full control.
https://github.com/koppajs/koppajs-core
custom-components direct-dom fast frontend koppa koppajs lightweight modular no-virtual-dom performance pragmatic reactive single-file-components ui-framework vite web-development
Last synced: 3 months ago
JSON representation
Minimal frontend framework with .kpa components, proxy reactivity, and no hidden layers. Built for clarity, speed, and full control.
- Host: GitHub
- URL: https://github.com/koppajs/koppajs-core
- Owner: koppajs
- License: apache-2.0
- Created: 2025-03-11T22:25:40.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-26T15:12:02.000Z (3 months ago)
- Last Synced: 2026-03-27T05:52:36.291Z (3 months ago)
- Topics: custom-components, direct-dom, fast, frontend, koppa, koppajs, lightweight, modular, no-virtual-dom, performance, pragmatic, reactive, single-file-components, ui-framework, vite, web-development
- Language: TypeScript
- Homepage: http://koppajs.org
- Size: 870 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Roadmap: ROADMAP.md
Awesome Lists containing this project
README
@koppajs/koppajs-core
Core runtime and component model for KoppaJS
Reactive components, explicit lifecycle seams, and a small runtime without virtual DOM overhead.
Table of Contents
- What is KoppaJS Core?
- Features
- Installation
- Requirements
- Getting Started
- Runtime Model
- Roadmap
- Architecture & Governance
- Community & Contribution
- License
---
## What is KoppaJS Core?
`@koppajs/koppajs-core` is the runtime package at the center of the KoppaJS
stack.
It owns the public bootstrap surface, component registration, DOM runtime
setup, lifecycle coordination, and the stable contracts that other KoppaJS
packages build on top of.
In practice that means:
- applications register components through `Core.take(...)`
- the runtime boots once through `Core()`
- the Vite plugin handles `.kpa` transformation, while core stays focused on
runtime behavior
---
## Features
- component registration via the stable `Core.take(...)` API
- one-time runtime bootstrap through `Core()`
- reactive component model with explicit methods, refs, props, and lifecycle
hooks
- modular extension surface for plugins and modules
- no virtual DOM dependency
- published package with ESM, CommonJS, and TypeScript types
---
## Installation
```bash
pnpm add @koppajs/koppajs-core
pnpm add -D @koppajs/koppajs-vite-plugin vite typescript
```
```bash
npm install @koppajs/koppajs-core
npm install -D @koppajs/koppajs-vite-plugin vite typescript
```
The fastest path for most users is still the official starter:
```bash
pnpm create koppajs my-app
```
---
## Requirements
For package consumers:
- a browser-based application environment
- a build pipeline that can consume KoppaJS components, typically Vite plus
`@koppajs/koppajs-vite-plugin`
- package installation supports Node.js >= 22
For local repository work:
- Node.js >= 22
- pnpm >= 10.24.0
---
## Getting Started
Recommended bootstrap path:
```bash
pnpm create koppajs my-app
cd my-app
pnpm install
pnpm dev
```
Manual registration with the public core API:
```ts
import { Core } from '@koppajs/koppajs-core'
import appView from './app-view.kpa'
import counterComponent from './counter-component.kpa'
Core.take(appView, 'app-view')
Core.take(counterComponent, 'counter-component')
Core()
```
This mirrors the bootstrap used in the official example project.
---
## Runtime Model
KoppaJS Core deliberately keeps its top-level contract small:
- `Core.take(componentSource, name)` registers a component definition
- `Core.take(pluginOrModule)` installs an extension definition
- `Core()` initializes the DOM environment and flushes queued registrations
- repeated `Core()` calls are safe and idempotent
The runtime does not own `.kpa` parsing. That stays in
`@koppajs/koppajs-vite-plugin`, which emits the component source objects that
core consumes at runtime.
---
## Roadmap
- continue hardening the stable runtime contracts
- keep the public bootstrap surface small and explicit
- deepen runtime specs and package-level governance documents
- support ecosystem packages such as the router, component library, and editor
tooling without growing hidden runtime coupling
---
## Architecture & Governance
Project intent, contributor rules, and documentation contracts live in the local repo meta layer:
- [AI_CONSTITUTION.md](./AI_CONSTITUTION.md)
- [ARCHITECTURE.md](./ARCHITECTURE.md)
- [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md)
- [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md)
- [TESTING_STRATEGY.md](./TESTING_STRATEGY.md)
- [RELEASE.md](./RELEASE.md)
- [ROADMAP.md](./ROADMAP.md)
- [CHANGELOG.md](./CHANGELOG.md)
- [CONTRIBUTING.md](./CONTRIBUTING.md)
- [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
- [docs/specs/README.md](./docs/specs/README.md)
- [docs/specs/repository-documentation-contract.md](./docs/specs/repository-documentation-contract.md)
- [docs/meta/README.md](./docs/meta/README.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](./docs/specs/repository-documentation-contract.md).
Run the local document guard before committing:
```bash
pnpm run check:docs
```
---
## Community & Contribution
Issues and pull requests are welcome:
https://github.com/koppajs/koppajs-core/issues
Contributor workflow details live in [CONTRIBUTING.md](./CONTRIBUTING.md).
Community expectations live in [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md).
---
## License
Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch