Light is an engine for user interfaces on the web, in the terminal and on the desktop. A view is a standard custom element rendered into the light DOM, built from signals and a tagged-template renderer. Models hold data, controllers hold shared state, and a theme supplies tokens and utility classes. The same view code runs in a browser, under prerendering, and natively through scriptc, which compiles the terminal and desktop hosts to binaries with no JavaScript engine inside.
The idea is one engine across hosts, in small parts: the engine, then packages beside it for components, routing, serving, building. The engine has no runtime dependencies and no virtual DOM.
light new web my-app
cd my-app
pnpm dev| Kind | What it starts |
|---|---|
web |
A web app on @lightstart/app: views, a model, a controller and routes |
tui |
A terminal app on @lightstart/app, compiled by scriptc |
desktop |
A light page in a desktop shell, with a native backend |
package |
A light package, with modules, tests and a README |
The first script is pnpm dev for a web, tui or desktop project, and pnpm test for a package. Each project carries its own README.md and AGENTS.md.
Light's packages are not on npm yet, so light new links a light checkout: the one it runs from, or the one --light <path> names. To get light on PATH from a checkout, link its binary:
ln -s "$PWD/packages/cli/bin/light.js" ~/.local/bin/light--npm writes published version ranges instead, so a project can switch over once the packages are on npm.
A web or terminal project is an app on @lightstart/app. The project's folders are the app: src/app.ts names the few choices, src/models/, src/controllers/ and src/views/ hold the pieces, and src/routes.ts maps paths to view tags on the web. A view imports its controller, a controller imports its models, and one controller reaches another by name with sync:.
Light writes the wiring into .light/app.ts and .light/main.ts before serve, build, test and run. .light/ is generated: never edit it and never commit it. The host opens the store, names and starts the controllers, applies the theme, builds the routes and mounts the root view; a terminal app's host also carries the baked class table.
The engine is @lightstart/light: views, the html renderer, signals, controllers, models, the theme, and the native hosts for the terminal and desktop. It is the reference for everything below.
| Package | What it is |
|---|---|
@lightstart/app |
A project's folders as an app: defineApp, the generated wiring, and the web and terminal hosts |
@lightstart/components |
The lc-* component library, with its mixins, libs and stylesheets |
@lightstart/router |
A client router with route patterns, a navigation stack, locales and base paths |
@lightstart/markdown |
One Markdown parser, shared by the terminal renderer and <lc-markdown> |
@lightstart/highlight |
Syntax coloring for terminal views and <lc-code-block> |
@lightstart/server |
A small HTTP server over one Context and Reply, on node, Fetch hosts and Lambda |
@lightstart/sqlite |
One synchronous SQLite driver over node's engine or a native shim |
@lightstart/cli |
The command runner behind light, with commands, hooks, routes and extensions |
@lightstart/dev |
The dev server behind light serve, with the importmap, TypeScript stripping and live reload |
@lightstart/build |
The production build behind light build, bundling pages and stylesheets with esbuild |
@lightstart/create |
The generator behind light new |
| Command | Does |
|---|---|
light new <kind> <name> |
Starts a project of a kind |
light serve |
Runs the dev server, reloading on a change |
light build |
Bundles a page into a production build |
light test |
Runs the tests, in a browser for a web app |
light check |
Checks the sources against light's conventions |
light desktop dev, light desktop build |
Runs a desktop app on the dev server, or builds it |
Packages extend the command set by shipping commands in their own cli/ folders. See the CLI README.
The packages will be published to npm. Inside a project, there will be more generators, for a view, a model or a route, and the desktop host joins @lightstart/app's web and terminal hosts.
Read AGENTS.md for the rules of this repository, and each package's own AGENTS.md where it has one.
| Folder | Holds |
|---|---|
packages/light/ |
The engine |
packages/app/ |
The app layer: the folders, the generated wiring and the hosts |
packages/components/, packages/router/, packages/markdown/, packages/highlight/ |
UI packages |
packages/server/, packages/sqlite/ |
Server packages |
packages/cli/, packages/dev/, packages/build/, packages/create/ |
Tooling |
packages/native/, packages/tui/ |
Workspace packages that native apps share |
examples/ |
Two apps on @lightstart/app, the same tasks app in a page (tasks-web) and on a terminal (tasks-tui) |
benchmarks/ |
The engine, renderer and server under node, natively and in Chromium |
MIT