Cygnus is an HTML preprocessor (not a framework & not a PHP) that adds component reuse, CSS injection, and variable templating to native .html files. It runs as a Vite plugin via @peakk/cygnus.
Cygnus is a library. You import its helpers in your own vite.config.js there's no scaffolding CLI.
npm install @peakk/cygnus
npm install -D viteNote: Vite is a peer dependency. Cygnus will print a warning at startup if Vite is not installed.
1. Create your project's vite.config.js (see templates/vite.config.js):
import { defineConfig } from 'vite';
import { cygnusPlugin } from '@peakk/cygnus';
export default defineConfig({
root: 'src',
build: {
outDir: '../dist',
emptyOutDir: true
},
server: {
fs: { strict: false }
},
plugins: [cygnusPlugin()]
});2. Add scripts to your package.json:
{
"scripts": {
"dev": "vite",
"build": "vite build",
"preview": "vite preview"
}
}3. Create src/index.html:
@name('My App')
<html lang="en">
<body>
<h1>Hello Cygnus</h1>
</body>
</html>4. Run:
npm run devThat's it. A complete starter (vite.config.js, src/index.html, README) lives in the templates/ folder of the package copy it into your project and edit.
@name('My App', './favicon.ico')@using "#nav" from "./components/nav.html"@using CSS "dialog.css"*badge.create(<span class="badge">New</span>)
@using "#item1" from *badge
@using "#item2" from *badge<!-- card.html -->
*card.create(<div class="card"><h3>Hello</h3></div>)<!-- index.html -->
@using "#x" from *card in "card.html"<button onclick="toggle('dialog')">Open</button>The package exports two layers of helpers from @peakk/cygnus:
Vite plugin (high-level):
cygnusPlugin(opts)Vite plugin factory; the main thing you importprocessCygnusHtml(html, opts)run a single HTML string through the pipelinecopyDirWithHtml(src, dest, isBuild)recursively copy a folder, processing.htmlfilessafeResolve(base, request, root)path-traversal-safe resolverHAS_DECL_REregex detecting any Cygnus directive in HTML
Core pipeline (low-level):
extractCalls,extractCssLinks,extractName,strip(fromparse.js)extractVars,stripVars,interpolatePrimitives(fromvars.js)rebuild(frominject.js)buildErrorOverlay(fromerror-overlay.js)
If you want to embed Cygnus in a non-Vite pipeline, use the low-level helpers directly.
MIT LICENSE.md