Packages

Overview of all Constela packages and their purposes

Overview

Constela is organized into several packages, each with a specific responsibility. This modular architecture allows you to use only what you need.

@constela/core

The foundational package containing type definitions, schema validation, and core utilities.

bash

npm install @constela/core

Key Exports

Export	Description
`Program`	TypeScript type for the root program structure
`ViewNode`	Union type for all view node types
`Expression`	Union type for all expression types
`ActionDefinition`	Type for action definitions
`ActionStep`	Union type for all step types
`validateProgram`	Function to validate a program against the schema
`ProgramSchema`	Zod schema for runtime validation

Usage

typescript

import { Program, validateProgram } from '@constela/core';

const program: Program = {
  version: "1.0",
  state: { count: { type: "number", initial: 0 } },
  actions: [],
  view: { kind: "text", content: { expr: "state", name: "count" } }
};

const result = validateProgram(program);
if (result.success) {
  console.log('Valid program!');
} else {
  console.error('Validation errors:', result.errors);
}

@constela/compiler

The AST transformation and code generation package.

bash

npm install @constela/compiler

Key Exports

Export	Description
`compile`	Main compilation function
`CompileOptions`	Configuration options for compilation
`CompileResult`	Result containing generated code
`transform`	AST transformation utilities

Usage

typescript

import { compile } from '@constela/compiler';
import type { Program } from '@constela/core';

const program: Program = { ... };

const result = compile(program, {
  target: 'esm',
  minify: true
});

console.log(result.code);

Compile Options

Option	Type	Default	Description
`target`	`"esm" \| "cjs" \| "iife"`	`"esm"`	Output module format
`minify`	`boolean`	`false`	Minify the output
`sourcemap`	`boolean`	`false`	Generate source maps

@constela/runtime

The browser runtime for rendering and reactivity.

bash

npm install @constela/runtime

Key Exports

Export	Description
`createApp`	Creates an application instance
`mount`	Mounts the app to a DOM element
`hydrate`	Hydrates server-rendered HTML

Usage

typescript

import { createApp, mount } from '@constela/runtime';
import type { Program } from '@constela/core';

const program: Program = { ... };

const app = createApp(program);
mount(app, document.getElementById('app')!);

Runtime Features

Fine-grained reactivity: Only updates what changed
Event delegation: Efficient event handling
Memory efficient: Minimal DOM node creation
SSR compatible: Works with server-rendered HTML
Markdown rendering: GFM support with DOMPurify sanitization
Code highlighting: VS Code-quality syntax highlighting via Shiki

@constela/router

Client-side routing for multi-page Constela applications.

bash

npm install @constela/router

Key Exports

Export	Description
`createRouter`	Creates a router instance
`Route`	Route configuration type
`RouterOptions`	Router configuration options

Usage

typescript

import { createRouter } from '@constela/router';
import { createApp, mount } from '@constela/runtime';

const router = createRouter({
  routes: [
    { path: '/', program: homeProgram },
    { path: '/about', program: aboutProgram },
    { path: '/users/:id', program: userProgram }
  ]
});

router.onNavigate((program) => {
  const app = createApp(program);
  mount(app, document.getElementById('app')!);
});

router.start();

Route Parameters

Route parameters are automatically extracted and available in your program:

json

{
  "kind": "text",
  "value": { "expr": "param", "name": "id" }
}

@constela/server

Server-Side Rendering (SSR) package for any JavaScript server environment.

bash

npm install @constela/server

Note

Requirements: @constela/compiler (peer dependency)

Key Exports

Export	Description
`renderToString`	Renders a CompiledProgram to HTML string for SSR (async)

Usage

typescript

import { compile } from '@constela/compiler';
import { renderToString } from '@constela/server';

const myProgram = { /* ... */ };

async function generateHtml() {
  const result = compile(myProgram);
  if (!result.ok) throw new Error('Compile failed');

  const content = await renderToString(result.program);

  return `
    <!DOCTYPE html>
    <html>
      <body>
        <div id="app">${content}</div>
        <script type="module">
          import { createApp } from '@constela/runtime';
          import program from './program.js';
          createApp(program, document.getElementById('app'));
        </script>
      </body>
    </html>
  `;
}

Features

Feature	Library	Description
Markdown parsing	marked	GFM-compatible Markdown parser
Syntax highlighting	shiki	VS Code-quality code highlighting at build time
XSS protection	DOMPurify	HTML sanitization for security

Tip

@constela/server is framework-agnostic. Use it with Express, Hono, Fastify, or any Node.js/Bun/Deno server.

Integration with Next.js

For Next.js projects, use @constela/server in Server Components:

typescript

// app/page.tsx (Server Component)
import { compile } from '@constela/compiler';
import { renderToString } from '@constela/server';
import { ConstelaClient } from './ConstelaClient';

const myProgram = { /* ... */ };

export default async function Page() {
  const result = compile(myProgram);
  if (!result.ok) throw new Error('Compile failed');

  const ssrHtml = await renderToString(result.program);

  return (
    <div>
      <h1>My App</h1>
      <ConstelaClient program={result.program} ssrHtml={ssrHtml} />
    </div>
  );
}

typescript

// ConstelaClient.tsx (Client Component)
'use client';
import { useEffect, useRef } from 'react';
import { createApp } from '@constela/runtime';
import type { CompiledProgram } from '@constela/compiler';

interface Props {
  program: CompiledProgram;
  ssrHtml: string;
}

export function ConstelaClient({ program, ssrHtml }: Props) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!ref.current) return;
    const app = createApp(program, ref.current);
    return () => app.destroy();
  }, [program]);

  return <div ref={ref} dangerouslySetInnerHTML={{ __html: ssrHtml }} />;
}

@constela/cli

Command-line tools for development and building.

bash

npm install -g @constela/cli
# or
npx constela

Commands

Command	Description
`constela build <file>`	Compile a program to JavaScript
`constela dev <file>`	Start development server with hot reload
`constela validate <file>`	Validate a program without building
`constela init`	Initialize a new Constela project

Build Command

bash

constela build app.json --output dist/app.js --minify

Options:

--output, -o: Output file path
--minify, -m: Minify output
--sourcemap, -s: Generate source map
--target, -t: Module format (esm, cjs, iife)

Dev Command

bash

constela dev app.json --port 3000

Options:

--port, -p: Dev server port (default: 3000)
--open, -o: Open browser automatically

Validate Command

bash

constela validate app.json

Validates the program and reports any errors without generating output.

@constela/start

Meta-framework for building full-stack Constela applications with file-based routing, SSR, SSG, and edge runtime support.

bash

npm install @constela/start

Note

@constela/start is to Constela what SolidStart is to SolidJS — a full-featured meta-framework for production applications.

Key Exports

Export	Description
`defineConfig`	Configuration function for `constela.config.ts`
`APIContext`	Type for API route handlers
`MiddlewareHandler`	Type for middleware functions
`GetStaticPaths`	Type for SSG path generation
`RouteParams`	Type for route parameter access

Usage

typescript

// src/routes/index.ts
import type { Program } from '@constela/core';

export default {
  version: '1.0',
  state: { count: { type: 'number', initial: 0 } },
  actions: [
    { name: 'increment', steps: [{ do: 'update', target: 'count', operation: 'increment' }] }
  ],
  view: {
    kind: 'element',
    tag: 'div',
    children: [
      { kind: 'text', value: { expr: 'state', name: 'count' } },
      {
        kind: 'element',
        tag: 'button',
        props: { onClick: { event: 'click', action: 'increment' } },
        children: [{ kind: 'text', value: { expr: 'lit', value: '+1' } }]
      }
    ]
  }
} satisfies Program;

CLI Commands

Command	Description
`constela-start dev`	Start development server with HMR
`constela-start build`	Build for production
`constela-start start`	Start production server

Features

Feature	Description
File-based routing	Routes generated from `src/routes/` directory
SSR	Server-side rendering with `@constela/server`
SSG	Static site generation with `getStaticPaths`
API Routes	GET/POST/PUT/DELETE/PATCH endpoints
Middleware	Koa/Hono-style `next()` pattern
Edge Runtime	Cloudflare Workers, Vercel Edge, Deno

Tip

See the full @constela/start documentation for detailed usage and examples.

Package Dependencies

text

@constela/cli
  ├── @constela/core
  ├── @constela/compiler
  └── @constela/runtime

@constela/start
  ├── @constela/core
  ├── @constela/compiler
  ├── @constela/runtime
  └── @constela/server

@constela/server
  └── @constela/compiler (peer)

@constela/router
  └── @constela/runtime
      └── @constela/core

@constela/compiler
  └── @constela/core

Tip

For most projects, installing @constela/cli provides everything you need. The CLI includes all other packages as dependencies.

Version Compatibility

All packages follow semantic versioning and are released together. Always use the same version across all Constela packages in your project.

json

{
  "dependencies": {
    "@constela/core": "^1.0.0",
    "@constela/compiler": "^1.0.0",
    "@constela/runtime": "^1.0.0"
  }
}