What is this plugin?

This is the official Vite integration for KoppaJS.

Its responsibility is deliberately narrow: to transform .kpa Single File Components into standard ES modules that can participate in Vite’s normal module graph — nothing more, nothing less.

Vite is fast. KoppaJS is minimal.
This plugin connects the two without hidden behavior, runtime magic, or implicit coupling.

Specifically, it:

• parses .kpa files,
• extracts template, style, and script blocks,
• compiles and normalizes their contents,
• and emits deterministic ES module output understood by the KoppaJS core.

It is a build-time transformation layer, not a framework extension.

Features

• Native .kpa file support
• TypeScript inside component scripts
• SCSS / SASS compilation
• Explicit template, style, and script extraction
• Zero runtime behavior
• Fast HMR through Vite’s native mechanisms
• Pure ESM output
• Minimal footprint and surface area

Installation

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

Add the plugin to your 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.

Usage & Behavior

Once configured:

• .kpa files are resolved by Vite like any other module
• transformations occur during dev and build
• Hot Module Replacement works without custom handling
• output modules are statically analyzable and deterministic

The plugin performs no runtime work and injects no global state. All behavior is confined to Vite’s build pipeline.

How it works

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

The following example shows a simplified representation of the generated output, focusing on the core transformation result. The complete and binding runtime contract consumed by the KoppaJS core is defined in the Plugin → Core Contract section below.

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

Supported transformations include:

• TypeScript → JavaScript
• SCSS / SASS → CSS
• composition-style controllers
• legacy return {} controllers

The output format is intentionally explicit to allow the KoppaJS core to remain small, predictable, and framework-agnostic.

Debugging & Sourcemaps (Dynamic Code)

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

How sourcemaps are handled

• All sourceMappingURL and sourceURL comments are stripped during transformation
• Sourcemaps are preserved as structured data and exposed as scriptMap
• The KoppaJS core is responsible for attaching sourcemaps at runtime (for example via Blob or data: URLs)

⚠️ If the runtime does not explicitly reattach sourcemaps, component scripts will execute correctly, but browser DevTools will not display original source mappings.

This behavior is intentional and prevents syntax errors in dynamically evaluated code.

Plugin → Core Contract

This plugin produces ComponentSource objects with the following structure:

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

Guarantees:

• All string fields are JSON-serialized
• TypeScript blocks are transpiled before emission
• Style blocks are compiled to plain CSS
• Templates include structural identity attributes for reconciliation
• Script functions always return valid controller objects

For detailed integration semantics, see the Integration Contracts Documentation.

Community & Contribution

Issues and pull requests are welcome:

https://github.com/koppajs/koppajs-vite-plugin/issues

Please keep contributions focused on:

• correctness,
• determinism,
• and maintaining a minimal public surface.

License

Apache License 2.0 — © 2026 KoppaJS, Bastian Bensch