create-fluixi 0.1.0-alpha.5

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,63 @@
+<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 and a **mode**, or take 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)
+```
+
+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/>)` |
+
+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,141 @@
+#!/usr/bin/env node
+/**
+ * `npm create fluixi <dir>` — scaffold a new Fluixi app. Prompts for a name and a
+ * mode (SSR via @fluixi/start, or SPA via vite + @fluixi/vite-plugin), unless given on
+ * the command line: `create-fluixi my-app --spa` / `--ssr`. 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);
+            }
+            else if (k.name === 'return') {
+                finish();
+                done(choices[idx].value);
+            }
+            else if (k.name === 'c' && k.ctrl) {
+                finish();
+                output.write('\n');
+                exit(1);
+            }
+        };
+        const finish = () => {
+            input.off('keypress', onKey);
+            if (input.isTTY)
+                input.setRawMode(false);
+            // emitKeypressEvents() resumed stdin to read keys; pause it again or the
+            // live stdin handle keeps the event loop alive and the CLI never exits.
+            input.pause();
+            output.write(`${BAR}\n`);
+        };
+        input.on('keypress', onKey);
+    });
+}
+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;
+    const interactive = input.isTTY && (!dir || !mode);
+    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' },
+            ]));
+        }
+    }
+    dir = dir ?? 'fluixi-app';
+    mode = mode ?? 'ssr';
+    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);
+    }
+    cpSync(here(mode === 'spa' ? '../template-spa' : '../template-ssr'), 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;
+    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n');
+    // Outro + next steps. The leading gutter only makes sense after the intro/prompts.
+    const tag = mode === 'ssr' ? c.cyan('SSR') : c.cyan('SPA');
+    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,27 @@
+{
+  "name": "create-fluixi",
+  "version": "0.1.0-alpha.5",
+  "description": "Scaffold a new Fluixi app — `npm create fluixi <dir>`.",
+  "type": "module",
+  "bin": {
+    "create-fluixi": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template-ssr",
+    "template-spa",
+    "README.md"
+  ],
+  "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,21 @@
+{
+  "name": "fluixi-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@fluixi/core": "next",
+    "@fluixi/jsx": "next",
+    "@fluixi/dom": "next",
+    "@fluixi/reactive": "next"
+  },
+  "devDependencies": {
+    "@fluixi/vite-plugin": "next",
+    "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,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "jsxImportSource": "@fluixi/jsx",
+    "strict": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["vite/client"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/template-spa/vite.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from 'vite';
+import { fluixi } from '@fluixi/vite-plugin';
+
+export default defineConfig({
+  plugins: [fluixi()],
+});

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,5 @@
+import { defineConfig } from '@fluixi/start/config';
+
+export default defineConfig({
+  port: 3000,
+});

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,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": "next",
+    "@fluixi/start": "next",
+    "@fluixi/core": "next",
+    "@fluixi/jsx": "next",
+    "@fluixi/server": "next",
+    "@fluixi/reactive": "next",
+    "@fluixi/dom": "next"
+  },
+  "devDependencies": {
+    "@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 'virtual:fluixi-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 'virtual:fluixi-server-fns'; // registers every "use server" module (incl. lazy routes)
+export { isServerFnRequest, handleServerFn } from '@fluixi/start/server-fn';

package/template-ssr/src/fluixi-env.d.ts

@@ -0,0 +1,7 @@
+// Auto-generated by @fluixi/core fluixiRoutesPlugin — do not edit manually
+declare module 'virtual:fluixi-routes' {
+  import type { RouteDefinition } from '@fluixi/core/router-next';
+  export const routes: RouteDefinition[];
+}
+
+declare module 'virtual:fluixi-server-fns';

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,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2021",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "jsxImportSource": "@fluixi/jsx",
+    "strict": false,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src", "fluixi.config.ts"]
+}