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
npm create ascua@latest my-site
cd my-site
npm install
npm run devThe same with other tools:
stil dlx create-ascua my-site
bun create ascua my-site
deno run -A npm:create-ascua my-siteIt 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 partNote: 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.
npm install ascua
npm install -D vite-plugin-ascua vite// 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
// 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
// src/main.ts
import { mount } from "ascua";
import { Counter } from "./counter.js";
mount(document.getElementById("app")!, () => Counter({ start: 0 }));<!-- 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:
npm install -D ascua-check
npx ascua-checkNext
- 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.