Roots documentation

One toolchain, written in Common Lisp, that builds apps for every surface: web, PWA, browser extensions, iOS, Android and the terminal. You write what you already know: Vue-style single-file components with HTML templates and <script setup lang="ts">. Those who want it can write <script setup lang="lisp"> too.

This is the documentation of Roots 0.4.0. It is built with Roots itself: every page is a compiled component, and the examples on these pages are the running code they show.

A first componentstatic previewdemos/counter.vue

0twice that is 0

counter.vue

<script setup lang="ts">
import { computed, ref } from "roots/runtime"

const count = ref(0)
const doubled = computed(() => count.value * 2)
</script>

<template>
  <Box class="counter flex-row items-center gap-3">
    <Button label="−" aria-label="One less" @click="count--" />
    <Text class="counter-value">{{ count }}</Text>
    <Button label="+" aria-label="One more" @click="count++" />
    <Text class="counter-note">twice that is {{ doubled }}</Text>
  </Box>
</template>

<style>
.counter { flex-wrap: wrap; }
.counter button { min-width: 44px; min-height: 44px; }
.counter-value {
  min-width: 2ch;
  text-align: center;
  font-size: 1.5rem;
  font-weight: 700;
  font-variant-numeric: tabular-nums;
}
.counter-note { color: var(--roots-muted); }
</style>

Start here #

If you want to	Read
install Roots and run a first app	Getting started
see components, forms and lists running	Components by example
add pages and navigation	Routing by example
set colours, light and dark mode	Theming

What is in the box #

A compiler for components. Templates and single-file components are compiled ahead of time to direct DOM operations: there is no virtual DOM.
A runtime. Reactivity, components and the router, the same on every target; the complete list of exports is in the reference.
A UI kit. roots/ui: 40 accessible components with a DOM skin and a terminal skin.
A data layer. roots/data: SQLite with migrations and live queries.
Six targets from one source. The targets, the native shells and the terminal renderer.
Its own tooling. The build, the bundler, tree shaker and minifier and the package manager. Nothing third-party runs during a build.

How it fits together #

            app authors write                          the toolchain (Common Lisp, SBCL)
  ┌──────────────────────────────────┐         ┌──────────────────────────────────────────┐
  │ .vue-style SFC                   │         │ CLI · dev server · package manager       │
  │   <template> HTML (Vue syntax)   │ ──────► │ SFC parser · HTML template compiler      │
  │   <script lang="ts">  (default)  │         │ TypeScript type stripper                 │
  │   <script lang="lisp"> (optional)│         │ Lisp → JS compiler (CL macros!)          │
  └──────────────────────────────────┘         │ bundler · build targets · SQLite         │
                                               └───────────────────┬──────────────────────┘
                                                                   │ emits plain ES modules
                                                                   ▼
                             web · PWA · extension · iOS · Android · terminal

Reference #

Generated from the sources of this version, so it is complete by construction: roots/runtime, roots/router, roots/ui, roots/platform, roots/data, the command line, the keys of roots.lisp and every error code.

About these pages #

Every version of Roots keeps its own documentation: the version menu under the header switches between them, and All versions lists them.
The pages are Markdown files in the repository's docs/ directory. To fix or add one, read Writing documentation; Publishing the site says how they get online.