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

pnpm add @koppajs/koppajs-core
pnpm add -D @koppajs/koppajs-vite-plugin vite typescript

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:

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:

pnpm create koppajs my-app
cd my-app
pnpm install
pnpm dev

Manual registration with the public core API:

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
• ARCHITECTURE.md
• DECISION_HIERARCHY.md
• DEVELOPMENT_RULES.md
• TESTING_STRATEGY.md
• RELEASE.md
• ROADMAP.md
• CHANGELOG.md
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• docs/specs/README.md
• docs/specs/repository-documentation-contract.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.

Run the local document guard before committing:

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.

Community expectations live in CODE_OF_CONDUCT.md.

License

Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch