create-fluixi 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluixi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/fluixi/assets/main/logos/128x128.png" alt="Fluixi" width="120" height="120" />
+</p>
+
+# create-fluixi
+
+**Scaffold a new Fluixi app — `npm create fluixi <dir>`.**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-22c55e.svg)](./LICENSE)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)
+![npm](https://img.shields.io/npm/v/create-fluixi?logo=npm)
+
+---
+
+## ✨ Overview
+
+Run via your package manager's `create` shortcut — no install needed:
+
+```bash
+npm create fluixi my-app
+# or
+pnpm create fluixi my-app
+# or
+yarn create fluixi my-app
+```
+
+It prompts for a project name, a **mode** and an **authoring format**, or takes them on the
+command line:
+
+```bash
+create-fluixi my-app --ssr           # SSR app (@fluixi/start: file routing + SSR + hydration)
+create-fluixi my-app --spa           # SPA (vite + @fluixi/vite-plugin)
+
+create-fluixi my-app --spa --html    # same app, html`` templates instead of JSX
+```
+
+`--jsx` (default) or `--html` picks how you write components. The html`` variant is
+JSX-free — plain `.ts` files, no `jsxImportSource`, and [`@fluixi/ts-plugin`](../ts-plugin)
+wired up so the editor still understands the templates. Both compile to the same thing.
+
+Then:
+
+```bash
+cd my-app
+pnpm install
+pnpm dev
+```
+
+## 🗂️ Templates
+
+| Mode | Stack | Entry |
+| --- | --- | --- |
+| **SSR** | [`@fluixi/start`](../start) + [`@fluixi/cli`](../cli) | `src/entry-{server,client}`, `src/routes/`, `fluixi.config.ts` |
+| **SPA** | `vite` + [`@fluixi/vite-plugin`](../vite-plugin) | `src/main.tsx` → `render(() => <App/>)` |
+
+Each comes in a JSX and an html`` variant (`template-ssr`, `template-ssr-html`, and the same
+two for SPA).
+
+Both pin `@fluixi/*` to the `next` dist-tag and set `jsxImportSource: "@fluixi/jsx"`.
+
+## 🧱 Scaffolding pieces
+
+To add components, routes, or middleware **inside** an existing app, use `fluixi generate`
+from [`@fluixi/cli`](../cli):
+
+```bash
+fluixi g component Button
+fluixi g route about
+```
+
+## 📄 License
+
+[MIT](./LICENSE) © [Fluixi](https://fluixi.dev)

package/dist/index.js

@@ -0,0 +1,308 @@
+#!/usr/bin/env node
+/**
+ * `npm create fluixi <dir>`: scaffold a new Fluixi app. Prompts for a name, a mode
+ * (SSR via @fluixi/start, or SPA via vite + @fluixi/vite-plugin), and a template syntax
+ * (JSX or html``), unless given on the command line: `create-fluixi my-app --spa --html`
+ * (`--ssr`/`--spa`, `--jsx`/`--html`). The html`` variant is JSX-free, plain `.ts`
+ * sources, no `jsx` in tsconfig. Zero runtime deps, the styled prompts (gradient
+ * wordmark, gutter, arrow-key select) are hand-rolled ANSI.
+ */
+import { cpSync, renameSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve, basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline/promises';
+import { emitKeypressEvents } from 'node:readline';
+import { stdin as input, stdout as output, argv, exit, env } from 'node:process';
+const here = (p) => fileURLToPath(new URL(p, import.meta.url));
+// ── tiny zero-dep ANSI styling ──────────────────────────────────────────────
+const COLOR = env.NO_COLOR || env.FORCE_COLOR === '0'
+    ? false
+    : (!!output.isTTY || !!env.FORCE_COLOR) && env.TERM !== 'dumb';
+const sgr = (o, x) => (s) => (COLOR ? `\x1b[${o}m${s}\x1b[${x}m` : `${s}`);
+const c = {
+    bold: sgr(1, 22), dim: sgr(2, 22), green: sgr(32, 39), yellow: sgr(33, 39),
+    cyan: sgr(36, 39), gray: sgr(90, 39), red: sgr(31, 39),
+};
+const rgb = (r, g, b) => (s) => (COLOR ? `\x1b[38;2;${r};${g};${b}m${s}\x1b[39m` : s);
+const BRAND = [
+    [34, 211, 238], [56, 189, 248], [129, 140, 248], [167, 139, 250], [192, 132, 252],
+];
+const gradient = (text) => {
+    if (!COLOR)
+        return text;
+    const ch = [...text];
+    return ch.map((x, i) => {
+        const [r, g, b] = BRAND[Math.min(BRAND.length - 1, Math.floor((i / Math.max(1, ch.length - 1)) * (BRAND.length - 1)))];
+        return rgb(r, g, b)(x);
+    }).join('');
+};
+const BAR = c.gray('│');
+// ── interactive prompt primitives (clack-style gutter) ──────────────────────
+async function askText(label, fallback) {
+    output.write(`${c.green('◇')}  ${c.bold(label)} ${c.gray(`(${fallback})`)}\n`);
+    const rl = createInterface({ input, output });
+    const answer = (await rl.question(`${BAR}  `)).trim();
+    rl.close();
+    output.write(`${BAR}\n`);
+    return answer || fallback;
+}
+function askSelect(label, choices) {
+    return new Promise((done) => {
+        let idx = 0;
+        output.write(`${c.green('◆')}  ${c.bold(label)}\n`);
+        const draw = (first) => {
+            if (!first)
+                output.write(`\x1b[${choices.length}A`);
+            for (let i = 0; i < choices.length; i++) {
+                const on = i === idx;
+                const dot = on ? c.green('●') : c.gray('○');
+                const name = on ? c.cyan(c.bold(choices[i].label)) : choices[i].label;
+                output.write(`\x1b[2K${BAR}  ${dot} ${name}  ${c.gray(choices[i].hint)}\n`);
+            }
+        };
+        draw(true);
+        emitKeypressEvents(input);
+        if (input.isTTY)
+            input.setRawMode(true);
+        const onKey = (_s, k) => {
+            if (k.name === 'up' || k.name === 'k') {
+                idx = (idx - 1 + choices.length) % choices.length;
+                draw(false);
+            }
+            else if (k.name === 'down' || k.name === 'j') {
+                idx = (idx + 1) % choices.length;
+                draw(false);
+            }
+            // Both names. A terminal sends `\r` and readline calls that `return`; a pty or a
+            // piped answer sends `\n`, which it calls `enter`. Accepting only the first left
+            // the prompt waiting for a key that never came.
+            else if (k.name === 'return' || k.name === 'enter') {
+                finish();
+                done(choices[idx].value);
+            }
+            else if (k.name === 'c' && k.ctrl) {
+                finish();
+                output.write('\n');
+                exit(1);
+            }
+        };
+        // Enter on a closed stream still means "take what is highlighted". Without this a
+        // piped answer (`printf 'app\n\n\n' | create-fluixi`) drew the list and stopped.
+        const onEnd = () => { finish(); done(choices[idx].value); };
+        const finish = () => {
+            input.off('keypress', onKey);
+            input.off('end', onEnd);
+            input.off('close', onEnd);
+            if (input.isTTY)
+                input.setRawMode(false);
+            // Pause it again or the live stdin handle keeps the event loop alive and the CLI
+            // never exits.
+            input.pause();
+            output.write(`${BAR}\n`);
+        };
+        // Already at EOF, so no event is coming: a fully buffered answer
+        // (`printf 'app\n\n\n' | create-fluixi`) is consumed by the name prompt and the
+        // stream ends before this one is set up. Take the highlighted value now.
+        if (input.readableEnded) {
+            finish();
+            done(choices[idx].value);
+            return;
+        }
+        input.on('keypress', onKey);
+        input.on('end', onEnd);
+        input.on('close', onEnd);
+        // The reason this prompt used to go nowhere. `askText` closes its readline
+        // interface, which leaves stdin paused, and `emitKeypressEvents` only wires the
+        // stream up the first time it is called. Attaching a listener to a paused stream
+        // reads nothing, so no key ever arrived: the list drew with the first option
+        // highlighted, the event loop drained, and the process exited 0 having created
+        // nothing.
+        input.resume();
+    });
+}
+/**
+ * What every @fluixi-ui app needs, and nothing more.
+ *
+ * The base layer: tokens and theme, the primitives and the behaviour they share, the
+ * layout and animation helpers. No component package is here on purpose, an app installs
+ * the ones it uses, and the resolver turns `<Button />` into an import from whichever it
+ * installed.
+ */
+const UI_DEPS = {
+    '@fluixi-ui/fx': 'alpha',
+    '@fluixi-ui/interactions': 'alpha',
+    '@fluixi-ui/kit': 'alpha',
+    '@fluixi-ui/layout': 'alpha',
+    '@fluixi-ui/polymorphic': 'alpha',
+    '@fluixi-ui/primitives': 'alpha',
+    '@fluixi-ui/theme': 'alpha',
+    '@fluixi-ui/tokens': 'alpha',
+};
+/** Build-time only: it runs in the config, not in the app. */
+const UI_DEV_DEPS = { '@fluixi-ui/resolver': 'alpha' };
+/** Add to a package.json section without dropping what the template already had. */
+function addDeps(pkg, section, deps) {
+    pkg[section] = Object.fromEntries(Object.entries({ ...(pkg[section] ?? {}), ...deps }).sort(([a], [b]) => a.localeCompare(b)));
+}
+/**
+ * The stylesheet the app imports, assembled from what was chosen.
+ *
+ * Tokens first: the kit's components read those custom properties, so a framework layer
+ * loaded before them would be overridden by nothing and a component would render unstyled.
+ */
+function styleSheet(ui, css) {
+    const lines = [];
+    if (ui === 'fluixi-ui')
+        lines.push(`@import '@fluixi-ui/tokens/css';`);
+    if (css === 'tailwind')
+        lines.push(`@import 'tailwindcss';`);
+    if (css === 'fluixi-css')
+        lines.push(`@import '@fluixi-css/core';`);
+    return lines.join('\n') + '\n';
+}
+/** Where the component resolver is configured, which differs by mode. */
+const configFor = (mode) => mode === 'ssr' ? 'fluixi.config.ts' : 'vite.config.ts';
+/**
+ * Let a capitalised tag resolve to a @fluixi-ui package.
+ *
+ * Added alongside the rule the template ships rather than replacing it, so a local
+ * `src/components/Card.tsx` still wins and only the names it does not define fall
+ * through to the kit.
+ */
+function addUiResolver(target, mode) {
+    const file = join(target, configFor(mode));
+    if (!existsSync(file))
+        return;
+    let src = readFileSync(file, 'utf8');
+    src = `import { uiComponents } from '@fluixi-ui/resolver';\n` + src;
+    src = src.replace("resolve: [{ match: /^([A-Z]\\w+)$/, module: '/src/components/$1.tsx' }]", "resolve: [{ match: /^([A-Z]\\w+)$/, module: '/src/components/$1.tsx' }, uiComponents()]");
+    writeFileSync(file, src);
+}
+/**
+ * Put a plugin in the app's vite config.
+ *
+ * An SSR app has none by default, because @fluixi/start owns the build. It still reads
+ * one when it is there, so a css engine that ships a vite plugin gets a file created for
+ * it rather than having nowhere to go.
+ */
+function addVitePlugin(target, mode, importLine, call) {
+    // A start app declares extra plugins in its own config; it has no vite config, and
+    // adding one just to hold a plugin would leave the project with two build configs
+    // that have to agree.
+    const file = join(target, configFor(mode));
+    if (!existsSync(file))
+        return;
+    let src = importLine + '\n' + readFileSync(file, 'utf8');
+    src =
+        mode === 'ssr'
+            ? src.replace('export default defineConfig({', `export default defineConfig({\n  plugins: [${call}],`)
+            : src.replace('plugins: [', `plugins: [\n    ${call},`);
+    writeFileSync(file, src);
+}
+/** Import the stylesheet from whichever file boots the client. */
+function importStyles(target, mode, format) {
+    const base = mode === 'ssr' ? 'entry-client' : 'main';
+    const file = ['tsx', 'ts']
+        .map((ext) => join(target, 'src', `${base}.${ext}`))
+        .find((p) => existsSync(p));
+    if (!file)
+        return;
+    writeFileSync(file, `import './styles.css';\n` + readFileSync(file, 'utf8'));
+}
+async function main() {
+    const args = argv.slice(2);
+    let dir = args.find((a) => !a.startsWith('-'));
+    let mode = args.includes('--spa') ? 'spa' : args.includes('--ssr') ? 'ssr' : undefined;
+    let format = args.includes('--html') ? 'html' : args.includes('--jsx') ? 'jsx' : undefined;
+    let ui = args.includes('--ui') ? 'fluixi-ui' : args.includes('--no-ui') ? 'none' : undefined;
+    let css = args.includes('--tailwind') ? 'tailwind'
+        : args.includes('--fluixi-css') ? 'fluixi-css'
+            : args.includes('--no-css') ? 'none'
+                : undefined;
+    const interactive = input.isTTY && (!dir || !mode || !format || !ui || !css);
+    if (interactive) {
+        output.write(`\n${c.gray('┌')}  ${gradient('◆')} ${c.bold(gradient('create-fluixi'))}\n${BAR}\n`);
+        if (!dir)
+            dir = await askText('Project name', 'fluixi-app');
+        if (!mode) {
+            mode = (await askSelect('App mode', [
+                { value: 'ssr', label: 'SSR', hint: 'server-rendered · @fluixi/start' },
+                { value: 'spa', label: 'SPA', hint: 'client-only · vite' },
+            ]));
+        }
+        if (!format) {
+            format = (await askSelect('Template syntax', [
+                { value: 'jsx', label: 'JSX', hint: 'default · .tsx · html`` works inline too' },
+                { value: 'html', label: 'html``', hint: 'no JSX · plain .ts · @fluixi/ts-plugin' },
+            ]));
+        }
+        if (!ui) {
+            ui = (await askSelect('Component library', [
+                { value: 'none', label: 'None', hint: 'bring your own components' },
+                { value: 'fluixi-ui', label: '@fluixi-ui', hint: 'kit + tokens · install components as you need them' },
+            ]));
+        }
+        if (!css) {
+            css = (await askSelect('Styling', [
+                { value: 'none', label: 'None', hint: 'plain css' },
+                { value: 'tailwind', label: 'Tailwind CSS', hint: 'v4 · via @tailwindcss/vite' },
+                { value: 'fluixi-css', label: '@fluixi-css', hint: 'the Fluixi stylesheet' },
+            ]));
+        }
+    }
+    dir = dir ?? 'fluixi-app';
+    mode = mode ?? 'ssr';
+    format = format ?? 'jsx';
+    ui = ui ?? 'none';
+    css = css ?? 'none';
+    const target = resolve(dir);
+    const name = basename(target);
+    if (existsSync(target)) {
+        output.write(`${c.gray('└')}  ${c.red('✗')} "${c.bold(name)}" already exists — pick another name or remove it.\n\n`);
+        exit(1);
+    }
+    const template = `../template-${mode}${format === 'html' ? '-html' : ''}`;
+    cpSync(here(template), target, { recursive: true });
+    // npm strips a real .gitignore from published packages → restore it from _gitignore.
+    const gi = join(target, '_gitignore');
+    if (existsSync(gi))
+        renameSync(gi, join(target, '.gitignore'));
+    const pkgPath = join(target, 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    pkg.name = name;
+    if (ui === 'fluixi-ui') {
+        addDeps(pkg, 'dependencies', UI_DEPS);
+        addDeps(pkg, 'devDependencies', UI_DEV_DEPS);
+        addUiResolver(target, mode);
+    }
+    if (css === 'tailwind') {
+        addDeps(pkg, 'devDependencies', { tailwindcss: '^4', '@tailwindcss/vite': '^4' });
+        addVitePlugin(target, mode, `import tailwindcss from '@tailwindcss/vite';`, 'tailwindcss()');
+    }
+    if (css === 'fluixi-css') {
+        addDeps(pkg, 'dependencies', { '@fluixi-css/core': 'next' });
+        addDeps(pkg, 'devDependencies', { '@fluixi-css/vite': 'next', lightningcss: '^1.29.3' });
+        addVitePlugin(target, mode, `import fluixiCss from '@fluixi-css/vite';`, 
+        // The bridge only matters with the component kit installed: it maps the theme
+        // scales onto the `--flx-ui-*` custom properties those components read.
+        `fluixiCss({ reset: true${ui === 'fluixi-ui' ? ', emitUiTokens: true' : ''} })`);
+        writeFileSync(join(target, 'fluixi.css.config.js'), `const config = {\n  purge: true,\n  content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],\n  mode: { dark: '[data-theme="dark"]' },\n  theme: { extend: {} },\n};\n\nexport default config;\n`);
+    }
+    if (ui === 'fluixi-ui' || css !== 'none') {
+        writeFileSync(join(target, 'src', 'styles.css'), styleSheet(ui, css));
+        importStyles(target, mode, format);
+    }
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    // Outro + next steps. The leading gutter only makes sense after the intro/prompts.
+    const tag = `${c.cyan(mode.toUpperCase())} ${c.gray('·')} ${c.cyan(format === 'html' ? 'html``' : 'JSX')}`;
+    if (interactive)
+        output.write(`${BAR}\n`);
+    else
+        output.write('\n');
+    output.write(`${c.green('◇')}  ${c.green('Created')} ${c.bold(name)} ${c.gray('·')} ${tag}\n${c.gray('└')}\n\n`);
+    output.write(`  ${c.bold('Next')}\n`);
+    output.write(`    ${c.gray('›')} cd ${dir}\n`);
+    output.write(`    ${c.gray('›')} ${c.cyan('pnpm install')} ${c.gray('# or npm / yarn')}\n`);
+    output.write(`    ${c.gray('›')} ${c.cyan('pnpm dev')}\n\n`);
+}
+main();

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "create-fluixi",
+  "version": "0.1.0-alpha.10",
+  "license": "MIT",
+  "author": "Ibrahima Touré",
+  "description": "Scaffold a new Fluixi app — `npm create fluixi <dir>`.",
+  "type": "module",
+  "bin": {
+    "create-fluixi": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template-ssr",
+    "template-spa",
+    "template-ssr-html",
+    "template-spa-html",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluixi/core.git",
+    "directory": "packages/create"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json"
+  }
+}

package/template-spa/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

package/template-spa/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Fluixi App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template-spa/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "fluixi-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@fluixi/core": "alpha",
+    "@fluixi/jsx": "alpha",
+    "@fluixi/dom": "alpha",
+    "@fluixi/reactive": "alpha"
+  },
+  "devDependencies": {
+    "@fluixi/ts-plugin": "alpha",
+    "@fluixi/vite-plugin": "alpha",
+    "vite": "^5.0.0"
+  }
+}

package/template-spa/src/app.tsx

@@ -0,0 +1,13 @@
+import { createSignal } from '@fluixi/core';
+
+export function App() {
+  const [count, setCount] = createSignal(0);
+  return (
+    <div class="app">
+      <h1>Fluixi</h1>
+      <button onClick={() => setCount(count() - 1)}>-</button>
+      <span>{count()}</span>
+      <button onClick={() => setCount(count() + 1)}>+</button>
+    </div>
+  );
+}

package/template-spa/src/main.tsx

@@ -0,0 +1,5 @@
+import { render } from '@fluixi/core';
+import { App } from './app';
+
+const root = document.getElementById('app');
+if (root) render(() => <App />, root);

package/template-spa/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "jsxImportSource": "@fluixi/jsx",
+    "strict": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"],
+    "plugins": [{ "name": "@fluixi/ts-plugin" }]
+  },
+  "include": ["src", "fluixi.d.ts", "vite.config.ts"]
+}

package/template-spa/vite.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vite';
+import { fluixi } from '@fluixi/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    fluixi({
+      // Where a capitalised tag with no import in scope comes from. One pattern covers
+      // the whole folder, so a new component needs no config, `fluixi g component Card`
+      // and `<Card />` just works. Delete this if you'd rather import every component.
+      resolve: [{ match: /^([A-Z]\w+)$/, module: '/src/components/$1.tsx' }],
+    }),
+  ],
+});

package/template-spa-html/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

package/template-spa-html/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Fluixi App</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/template-spa-html/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "fluixi-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@fluixi/core": "alpha",
+    "@fluixi/dom": "alpha",
+    "@fluixi/reactive": "alpha"
+  },
+  "devDependencies": {
+    "@fluixi/ts-plugin": "alpha",
+    "@fluixi/vite-plugin": "alpha",
+    "vite": "^5.0.0"
+  }
+}

package/template-spa-html/src/app.ts

@@ -0,0 +1,13 @@
+import { createSignal, html } from '@fluixi/core';
+
+export function App() {
+  const [count, setCount] = createSignal(0);
+  return html`
+    <div class="app">
+      <h1>Fluixi</h1>
+      <button @click=${() => setCount(count() - 1)}>-</button>
+      <span>${count()}</span>
+      <button @click=${() => setCount(count() + 1)}>+</button>
+    </div>
+  `;
+}

package/template-spa-html/src/main.ts

@@ -0,0 +1,5 @@
+import { render, html } from '@fluixi/core';
+import { App } from './app';
+
+const root = document.getElementById('app');
+if (root) render(() => html`<${App} />`, root);

package/template-spa-html/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"],
+    "plugins": [{ "name": "@fluixi/ts-plugin" }]
+  },
+  "include": ["src", "fluixi.d.ts", "vite.config.ts"]
+}

package/template-spa-html/vite.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vite';
+import { fluixi } from '@fluixi/vite-plugin';
+
+export default defineConfig({
+  plugins: [
+    fluixi({
+      // Where a capitalised tag with no import in scope comes from. One pattern covers
+      // the whole folder, so a new component needs no config, `fluixi g component Card`
+      // and `<Card />` just works. Delete this if you'd rather import every component.
+      resolve: [{ match: /^([A-Z]\w+)$/, module: '/src/components/$1.ts' }],
+    }),
+  ],
+});

package/template-ssr/README.md

@@ -0,0 +1,15 @@
+# Fluixi app
+
+Scaffolded with `npm create fluixi`. SSR + file-based routing + hydration via
+[`@fluixi/start`](https://www.npmjs.com/package/@fluixi/start).
+
+```bash
+pnpm install
+pnpm dev      # dev server (SSR + HMR)
+pnpm build    # production build
+pnpm start    # serve the production build
+```
+
+- Routes live in `src/routes/` (file-based).
+- `src/app.tsx` is the shell layout; `src/entry-{server,client}.{ts,tsx}` are the SSR/hydration entries.
+- Config in `fluixi.config.ts`.

package/template-ssr/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

package/template-ssr/fluixi.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from '@fluixi/start/config';
+import { nodeAdapter } from '@fluixi/start/adapter';
+
+export default defineConfig({
+  port: 3000,
+  // Where a capitalised tag with no import in scope comes from. One pattern covers
+  // the whole folder, so a new component needs no config, `fluixi g component Card`
+  // and `<Card />` just works. Delete this if you'd rather import every component.
+  resolve: [{ match: /^([A-Z]\w+)$/, module: '/src/components/$1.tsx' }],
+  // `pnpm start` runs a Node process from this directory, so the framework stays an
+  // import rather than being copied into dist/server. Swap in a deploy adapter , 
+  // cloudflare, netlify, vercel: to get the layout that platform expects.
+  adapter: nodeAdapter,
+});

package/template-ssr/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Fluixi Start Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/entry-client.tsx"></script>
+  </body>
+</html>

package/template-ssr/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "fluixi-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "fluixi dev",
+    "build": "fluixi build",
+    "start": "fluixi start"
+  },
+  "dependencies": {
+    "@fluixi/cli": "alpha",
+    "@fluixi/start": "alpha",
+    "@fluixi/core": "alpha",
+    "@fluixi/jsx": "alpha",
+    "@fluixi/server": "alpha",
+    "@fluixi/reactive": "alpha",
+    "@fluixi/dom": "alpha"
+  },
+  "devDependencies": {
+    "@fluixi/ts-plugin": "alpha",
+    "@types/node": "^20.0.0",
+    "vite": "^5.0.0"
+  }
+}

package/template-ssr/src/app.tsx

@@ -0,0 +1,36 @@
+import { Router, Outlet, createMemoryHistory } from '@fluixi/start/router';
+import { Suspense } from '@fluixi/core';
+import { routes } from '@fluixi/core/routes';
+
+// Shell layout around the routed page. File-routes (src/routes/*) are lazy, so the
+// <Outlet/> sits under <Suspense>: async SSR resolves their content server-side.
+function RootLayout() {
+  return (
+    <div class="app">
+      <nav>
+        <a href="/">home</a>
+        {' · '}
+        <a href="/about">about</a>
+      </nav>
+      <main>
+        <Suspense fallback={<p>loading…</p>}>
+          <Outlet />
+        </Suspense>
+      </main>
+    </div>
+  );
+}
+
+// Exported so entry-client can hand it to startClient, it preloads the current route's
+// lazy chunk before hydrating, so the server-rendered DOM is adopted in place (flash-free).
+export const appRoutes = [{ path: '/', component: RootLayout, children: routes as any }];
+
+export default function App(props?: { url?: string }) {
+  // On the server, match the request URL (memory history); on the client, default
+  // to browser history.
+  const history =
+    typeof window === 'undefined'
+      ? createMemoryHistory(props?.url ?? '/')
+      : undefined;
+  return <Router routes={appRoutes as any} history={history as any} />;
+}

package/template-ssr/src/entry-client.tsx

@@ -0,0 +1,10 @@
+// Client entry: hydrates the server-rendered markup. The app HTML is injected into
+// `#root` (the @fluixi/start mountId), so hydrate that container.
+import { startClient } from '@fluixi/core/client';
+import App, { appRoutes } from './app.js';
+
+// Passing the route tree lets startClient preload the matched route's lazy chunk before
+// hydrating: the lazy file-route then resolves synchronously and adopts the server DOM in
+// place (no first-paint flash, no duplicate). It also enables auto-hydration of the
+// server-rendered root.
+startClient(App, { root: '#root', routes: appRoutes });

package/template-ssr/src/entry-server.ts

@@ -0,0 +1,17 @@
+// SSR entry: @fluixi/start's dev/build/start load this. It calls `renderStream`
+// (streaming: head flushed first, body streamed) when present, else `render` (string).
+import App from './app.js';
+import { renderRequestAsync, renderToBodyStream } from '@fluixi/server';
+
+export function render(url: string): Promise<string> {
+  return renderRequestAsync(App, { url });
+}
+
+export function renderStream(url: string): ReadableStream<Uint8Array> {
+  return renderToBodyStream(App, { url });
+}
+
+// Server-function RPC dispatch: re-exported so the dispatcher shares the registry that
+// this app's `"use server"` modules populate. @fluixi/start routes RPC calls here.
+import '@fluixi/start/server-fns'; // registers every "use server" module (incl. lazy routes)
+export { isServerFnRequest, handleServerFn } from '@fluixi/start/server-fn';

package/template-ssr/src/routes/about.tsx

@@ -0,0 +1,8 @@
+export default function About() {
+  return (
+    <section class="about">
+      <h1>About</h1>
+      <p>A second file-route — proves URL-based SSR matching works.</p>
+    </section>
+  );
+}

package/template-ssr/src/routes/index.tsx

@@ -0,0 +1,25 @@
+import { createResource } from '@fluixi/reactive/signal';
+import { seo } from '@fluixi/start/head';
+
+const tick = <T,>(v: T, ms = 30) => new Promise<T>((r) => setTimeout(() => r(v), ms));
+
+// A data-gated route, like a real page: the resource is awaited during SSR so the
+// content (not the spinner) is server-rendered, then hydrated.
+export default function Home() {
+  const [data] = createResource(() => tick('Hello from Fluixi Start 👋'));
+
+  // Per-route document head: rendered into <head> on the server (great for crawlers/links)
+  // and kept reactive on the client. The head engine is always on; seo() is optional, call it
+  // only where you want page metadata. Drop in og/twitter/canonical/jsonLd as your app grows.
+  seo({
+    title: 'Fluixi Start',
+    description: 'A server-rendered Fluixi app, scaffolded by the fluixi CLI.',
+  });
+
+  return (
+    <section class="home">
+      <h1>{data()}</h1>
+      <p>Server-rendered through the fluixi CLI, then hydrated.</p>
+    </section>
+  );
+}

package/template-ssr/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "jsxImportSource": "@fluixi/jsx",
+    "strict": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node", "vite/client"],
+    "plugins": [{ "name": "@fluixi/ts-plugin" }]
+  },
+  "include": ["src", "fluixi.d.ts", "fluixi.config.ts"]
+}

package/template-ssr-html/README.md

@@ -0,0 +1,19 @@
+# Fluixi app
+
+Scaffolded with `npm create fluixi`. SSR + file-based routing + hydration via
+[`@fluixi/start`](https://www.npmjs.com/package/@fluixi/start).
+
+This variant is authored with `` html`` `` templates (no JSX), so the sources are plain
+`.ts` files and `tsconfig.json` doesn't configure `jsx`. `@fluixi/ts-plugin` gives the
+templates full TypeScript support (hover, completion, type-checking) in your editor.
+
+```bash
+pnpm install
+pnpm dev      # dev server (SSR + HMR)
+pnpm build    # production build
+pnpm start    # serve the production build
+```
+
+- Routes live in `src/routes/` (file-based).
+- `src/app.ts` is the shell layout; `src/entry-{server,client}.ts` are the SSR/hydration entries.
+- Config in `fluixi.config.ts`.

package/template-ssr-html/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.log
+.DS_Store

package/template-ssr-html/fluixi.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from '@fluixi/start/config';
+import { nodeAdapter } from '@fluixi/start/adapter';
+
+export default defineConfig({
+  port: 3000,
+  // Where a capitalised tag with no import in scope comes from. One pattern covers
+  // the whole folder, so a new component needs no config, `fluixi g component Card`
+  // and `<Card />` just works. Delete this if you'd rather import every component.
+  resolve: [{ match: /^([A-Z]\w+)$/, module: '/src/components/$1.ts' }],
+  // `pnpm start` runs a Node process from this directory, so the framework stays an
+  // import rather than being copied into dist/server. Swap in a deploy adapter , 
+  // cloudflare, netlify, vercel: to get the layout that platform expects.
+  adapter: nodeAdapter,
+});

package/template-ssr-html/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Fluixi Start Example</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/entry-client.ts"></script>
+  </body>
+</html>

package/template-ssr-html/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "fluixi-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "fluixi dev",
+    "build": "fluixi build",
+    "start": "fluixi start"
+  },
+  "dependencies": {
+    "@fluixi/cli": "alpha",
+    "@fluixi/start": "alpha",
+    "@fluixi/core": "alpha",
+    "@fluixi/server": "alpha",
+    "@fluixi/reactive": "alpha",
+    "@fluixi/dom": "alpha"
+  },
+  "devDependencies": {
+    "@fluixi/ts-plugin": "alpha",
+    "@types/node": "^20.0.0",
+    "vite": "^5.0.0"
+  }
+}

package/template-ssr-html/src/app.ts

@@ -0,0 +1,34 @@
+import { Router, Outlet, createMemoryHistory } from '@fluixi/start/router';
+import { Suspense } from '@fluixi/core';
+import { html } from '@fluixi/start';
+import { routes } from '@fluixi/core/routes';
+
+// Shell layout around the routed page. File-routes (src/routes/*) are lazy, so the
+// <Outlet/> sits under <Suspense>: async SSR resolves their content server-side.
+// Components are interpolated as `<${Comp}/>` so TypeScript sees them referenced.
+function RootLayout() {
+  return html`
+    <div class="app">
+      <nav>
+        <a href="/">home</a> · <a href="/about">about</a>
+      </nav>
+      <main>
+        <${Suspense} fallback=${html`<p>loading…</p>`}>
+          <${Outlet} />
+        </${Suspense}>
+      </main>
+    </div>
+  `;
+}
+
+// Exported so entry-client can hand it to startClient, it preloads the current route's
+// lazy chunk before hydrating, so the server-rendered DOM is adopted in place (flash-free).
+export const appRoutes = [{ path: '/', component: RootLayout, children: routes as any }];
+
+export default function App(props?: { url?: string }) {
+  // On the server, match the request URL (memory history); on the client, default
+  // to browser history.
+  const history =
+    typeof window === 'undefined' ? createMemoryHistory(props?.url ?? '/') : undefined;
+  return html`<${Router} routes=${appRoutes as any} history=${history as any} />`;
+}

package/template-ssr-html/src/entry-client.ts

@@ -0,0 +1,10 @@
+// Client entry: hydrates the server-rendered markup. The app HTML is injected into
+// `#root` (the @fluixi/start mountId), so hydrate that container.
+import { startClient } from '@fluixi/core/client';
+import App, { appRoutes } from './app.js';
+
+// Passing the route tree lets startClient preload the matched route's lazy chunk before
+// hydrating: the lazy file-route then resolves synchronously and adopts the server DOM in
+// place (no first-paint flash, no duplicate). It also enables auto-hydration of the
+// server-rendered root.
+startClient(App, { root: '#root', routes: appRoutes });

package/template-ssr-html/src/entry-server.ts

@@ -0,0 +1,17 @@
+// SSR entry: @fluixi/start's dev/build/start load this. It calls `renderStream`
+// (streaming: head flushed first, body streamed) when present, else `render` (string).
+import App from './app.js';
+import { renderRequestAsync, renderToBodyStream } from '@fluixi/server';
+
+export function render(url: string): Promise<string> {
+  return renderRequestAsync(App, { url });
+}
+
+export function renderStream(url: string): ReadableStream<Uint8Array> {
+  return renderToBodyStream(App, { url });
+}
+
+// Server-function RPC dispatch: re-exported so the dispatcher shares the registry that
+// this app's `"use server"` modules populate. @fluixi/start routes RPC calls here.
+import '@fluixi/start/server-fns'; // registers every "use server" module (incl. lazy routes)
+export { isServerFnRequest, handleServerFn } from '@fluixi/start/server-fn';

package/template-ssr-html/src/routes/about.ts

@@ -0,0 +1,10 @@
+import { html } from '@fluixi/start';
+
+export default function About() {
+  return html`
+    <section class="about">
+      <h1>About</h1>
+      <p>A second file-route — proves URL-based SSR matching works.</p>
+    </section>
+  `;
+}

package/template-ssr-html/src/routes/index.ts

@@ -0,0 +1,25 @@
+import { createResource } from '@fluixi/reactive/signal';
+import { seo } from '@fluixi/start/head';
+import { html } from '@fluixi/start';
+
+const tick = <T,>(v: T, ms = 30) => new Promise<T>((r) => setTimeout(() => r(v), ms));
+
+// A data-gated route, like a real page: the resource is awaited during SSR so the
+// content (not the spinner) is server-rendered, then hydrated.
+export default function Home() {
+  const [data] = createResource(() => tick('Hello from Fluixi Start 👋'));
+
+  // Per-route document head: rendered into <head> on the server (great for crawlers/links)
+  // and kept reactive on the client. seo() is optional; call it where you want metadata.
+  seo({
+    title: 'Fluixi Start',
+    description: 'A server-rendered Fluixi app, scaffolded by the fluixi CLI.',
+  });
+
+  return html`
+    <section class="home">
+      <h1>${data()}</h1>
+      <p>Server-rendered through the fluixi CLI, then hydrated.</p>
+    </section>
+  `;
+}

package/template-ssr-html/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "strict": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node", "vite/client"],
+    "plugins": [{ "name": "@fluixi/ts-plugin" }]
+  },
+  "include": ["src", "fluixi.d.ts", "fluixi.config.ts"]
+}