Quick Start

1. Scaffold a Project

bash

weblisk new my-app && cd my-app

This creates:

code

my-app/
├── index.html             ← Home page (full standalone HTML)
├── about.html             ← About page
├── 404.html               ← Not found page
├── js/
│   └── islands/
│       └── shell.js   ← Shell bootstrapper
├── css/
│   └── styles.css     ← Global styles
├── images/                ← Image assets
├── sw.js                  ← Service Worker
└── .env                   ← Config

Every page is a full standalone HTML document — through . What you write is what ships. The framework loads via CDN import maps — no local files needed.

To vendor the framework locally instead, add --local: weblisk new my-app --local. This adds a lib/weblisk/ directory with all 52 modules.

Want to skip hand-coding? Use the starter template to describe your entire site as YAML declarations and generate it via AI: weblisk new my-site --template starter. See Project Standards.

2. Preview

Open index.html directly in a browser, or use any static file server:

bash

weblisk dev                # built-in dev server
python3 -m http.server     # Python

3. Add a Page

Create a new HTML file at the project root — every page is a full standalone document:

html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Contact</title>
  <link rel="stylesheet" href="/css/styles.css">
  <script type="importmap">
  { "imports": { "weblisk": "/lib/weblisk/weblisk.js", "weblisk/": "/lib/weblisk/" } }
  </script>
</head>
<body>
  <h1>Contact</h1>
  <script type="module" src="/js/islands/shell.js"></script>
</body>
</html>

Save it as contact.html — it maps directly to /contact.html.

4. Make It Interactive

Create an island — a piece of JavaScript that enhances a static HTML region:

Add the island to your page HTML:

html

<div data-island="/js/islands/counter.js" data-hydrate="idle">
  <button>Count: 0</button>
</div>

Edit js/islands/counter.js:

import { signal, effect } from 'weblisk';

export default function counter(el) {
  const [count, setCount] = signal(0);
  const btn = el.querySelector('button');

  btn.addEventListener('click', () => setCount(count() + 1));
  effect(() => { btn.textContent = `Count: ${count()}`; });
}

5. Build for Production

bash

weblisk build

The dist/ folder contains your static files — ready to deploy anywhere.

6. Preview the Build

bash

weblisk dev dist            # serve the build output

This serves the dist/ folder locally so you can verify everything before deploying.