Introduction

Getting started

A new site with create-ascua, with npm, stil, Bun or Deno. Or the runtime by hand, from an empty folder to a component in the browser.

A new site

sh
npm create ascua@latest my-site
cd my-site
npm install
npm run dev

The same with other tools:

sh
stil dlx create-ascua my-site
bun create ascua my-site
deno run -A npm:create-ascua my-site

It leaves a site of the kit: routes, a layout, an island and a 404 page. With --template server it also adds a form with an action, a middleware, and a server that runs on Node, Bun, Deno or Workers.

src/routes/_layout.ts     wraps every page
src/routes/index.ts       /, with an island
src/routes/about.ts       /about, no JavaScript
src/routes/404.ts
src/islands/counter.ts    the interactive part

Note: stil and Deno do not install versions published very recently —seven days and one day— as a defense against compromised packages. In the first days of a new version, stil dlx create-ascua --min-age 0 -- my-site and stil install --min-age 0, or deno install --minimum-dependency-age 0.

The runtime by hand

Ascua is a runtime library and a Vite plugin. The compiler comes inside the plugin as WebAssembly: no binary to download, no postinstall to run.

sh
npm install ascua
npm install -D vite-plugin-ascua vite
ts
// vite.config.ts
import ascua from "vite-plugin-ascua";

export default {
  plugins: [ascua()],
};

The plugin does two things: run every file that has a template through the compiler, and hand Vite the CSS that comes out of their <style> tags. Everything else —TypeScript, modules, the build— is still Vite.

The first component

ts
// src/counter.ts
import { signal } from "ascua";

export function Counter(props: { start: number }) {
  const count = signal(props.start);

  return view`
    <div class="counter">
      <button onclick=${() => count.update((c) => c - 1)}>−</button>
      <output>${() => count()}</output>
      <button onclick=${() => count.update((c) => c + 1)}>+</button>
      <style>
        .counter { display: flex; gap: .5rem; align-items: center; }
        output { min-width: 3ch; text-align: center; }
      </style>
    </div>`;
}

A component is a function that returns a node. It runs once: what changes later are the nodes that depend on a signal, not the function.

Mounting it

ts
// src/main.ts
import { mount } from "ascua";

import { Counter } from "./counter.js";

mount(document.getElementById("app")!, () => Counter({ start: 0 }));
html
<!-- index.html -->
<div id="app"></div>
<script type="module" src="/src/main.ts"></script>

mount builds the tree inside a reactive root and returns a way to unmount it: it removes the nodes and releases every effect and listener that fed them.

TypeScript

view and html are declared as globals by ascua, so the editor knows them without importing. If your tsconfig.json does not pick up the package's types some other way, add "types": ["ascua"] or import something from it in any file.

For TypeScript, what goes inside a template is text: a prop of the wrong type is not an error. ascua-check checks it with the project's tsc and points each error to its line:

sh
npm install -D ascua-check
npx ascua-check

Next

  • Reactivity and Templates: the two ideas everything else is built on.
  • Sites: one page per file, islands, data, forms and servers.
  • From Fresh: if that is where you come from.
  • Components, styles, the router and the API reference are in Spanish for now.