@koppajs/koppajs-vite-plugin

Official Vite plugin for KoppaJS Single File Components

The intentional bridge between Vite and the .kpa format: explicit, minimal, and predictable.

Documentation · create-koppajs · KoppaJS Core · Router · Issues

Table of Contents

1. What is this plugin?
2. Features
3. Installation
4. Requirements
5. Usage & Behavior
6. How it works
7. Debugging & Sourcemaps (Dynamic Code)
8. Plugin -> Core Contract
9. Architecture & Governance
10. Community & Contribution
11. License

---

What is this plugin?

@koppajs/koppajs-vite-plugin is the official build-time integration between Vite and KoppaJS Single File Components.

Its responsibility is deliberately narrow:

• parse .kpa files
• extract template, style, and script blocks
• normalize and compile those blocks into deterministic ES modules
• emit the contract consumed by @koppajs/koppajs-core

It is a transformation layer, not a runtime extension.

---

Features

• native .kpa file support
• TypeScript inside component scripts
• SCSS and SASS compilation
• explicit template, style, and script extraction
• zero runtime behavior
• fast HMR through Vite’s native mechanisms
• ESM-first package output with CJS compatibility
• minimal footprint and surface area

---

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

Add the plugin to vite.config.ts:

import { defineConfig } from 'vite'
import koppajsVitePlugin from '@koppajs/koppajs-vite-plugin'

export default defineConfig({
  plugins: [koppajsVitePlugin()],
})

No additional configuration is required for basic usage.

For most users, the fastest way to start from a working KoppaJS + Vite setup is still the official scaffolder:

pnpm create koppajs my-app

---

Requirements

For package consumers:

• Vite ^7.0.0
• TypeScript >=5.5 <6
• @koppajs/koppajs-core in the consuming project

For local repository work:

• Node.js >= 22
• pnpm >= 10.24.0

---

Usage & Behavior

Once configured:

• .kpa files are resolved by Vite like any other module
• transformations occur during both development and production builds
• Hot Module Replacement works through Vite’s normal module graph
• output modules remain statically analyzable and deterministic

The plugin performs no runtime work and injects no global state. All behavior stays inside the build pipeline.

---

How it works

Each .kpa file is transformed into a plain JavaScript module.

This is a simplified view of the generated output:

export default {
  template: '<escaped-template>',
  style: '<compiled-css>',
  script: '(()=>{ /* controller */ })()',
}

Supported transformations include:

• TypeScript to JavaScript
• SCSS and SASS to CSS
• composition-style controllers
• legacy return {} controllers

The output format stays intentionally explicit so the KoppaJS core can remain small and predictable.

---

Debugging & Sourcemaps (Dynamic Code)

KoppaJS component scripts are executed dynamically at runtime by the core. Because of that, inline //# sourceMappingURL comments must not be embedded directly into executable script strings.

How sourcemaps are handled

• sourceMappingURL and sourceURL comments are stripped during transformation
• sourcemaps are preserved as structured data and exposed as scriptMap
• the core runtime is responsible for reattaching sourcemaps when needed

If the runtime does not explicitly reattach sourcemaps, component scripts still execute correctly, but browser DevTools will not show the original source mapping.

---

Plugin -> Core Contract

This plugin emits ComponentSource objects with the following structure:

interface ComponentSource {
  contractVersion: number
  path: string
  template: string
  style: string
  script: string
  scriptMap: object | null
  deps: Record<string, () => Promise<unknown>>
  structAttr: string
}

Guarantees:

• all string fields are JSON-serialized
• emitted modules include contractVersion and normalized path metadata
• TypeScript blocks are transpiled before emission
• style blocks are compiled to plain CSS
• templates include structural identity attributes for reconciliation

For deeper semantics, use the package docs:

• docs/specs/kpa-module-transformation.md

---

Architecture & Governance

Project intent, contributor rules, release flow, 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-vite-plugin/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