create-smaoog 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aggelos Gesoulis
+
+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,44 @@
+# create-smaoog
+
+Create a new [smaoog](https://www.npmjs.com/package/smaoog) app ready to go.
+
+## Usage
+
+```bash
+npm create smaoog my-app
+```
+
+or equivalently:
+
+```bash
+npx create-smaoog my-app
+```
+
+Then:
+
+```bash
+cd my-app
+npm install
+npm run dev
+```
+
+## TypeScript and JavaScript
+
+A TypeScript app is generated by default. For a JavaScript app, pass `--js`:
+
+```bash
+npm create smaoog my-app -- --js
+```
+
+## What you get
+
+- a sample file route in `src/routes/`
+- a user-owned `src/document.tsx`
+- a hydration entry at `src/client-entry.ts`
+- Tailwind CSS wired up via `src/app.css`
+- `public/favicon.ico`
+- `dev` / `build` / `start` scripts
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "create-smaoog",
+  "version": "0.0.1",
+  "description": "Scaffold a new smaoog app.",
+  "license": "MIT",
+  "author": "Aggelos Gesoulis",
+  "type": "module",
+  "keywords": [
+    "smaoog",
+    "create",
+    "scaffold",
+    "starter",
+    "react",
+    "ssr"
+  ],
+  "homepage": "https://github.com/anges244/smaoog/tree/main/packages/create-smaoog#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/anges244/smaoog.git",
+    "directory": "packages/create-smaoog"
+  },
+  "bugs": {
+    "url": "https://github.com/anges244/smaoog/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "create-smaoog": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "template",
+    "!src/**/*.test.js"
+  ],
+  "scripts": {
+    "preview": "node src/preview.js"
+  }
+}

package/src/index.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { existsSync, readdirSync } from "node:fs";
+import { basename, resolve } from "node:path";
+import { scaffold } from "./scaffold.js";
+
+// Parse argv into { appName, js, help }. The first non-flag argument is the app
+// name; `--js` selects the JavaScript template (`--ts` is the default).
+function parseArgs(argv) {
+  let appName;
+  let js = false;
+  let help = false;
+  for (const arg of argv) {
+    if (arg === "--js") js = true;
+    else if (arg === "--ts") js = false;
+    else if (arg === "--help" || arg === "-h") help = true;
+    else if (!arg.startsWith("-") && appName === undefined) appName = arg;
+  }
+  return { appName, js, help };
+}
+
+const USAGE = `Usage: create-smaoog <app-name> [--js]
+
+  Creates a new smaoog app in ./<app-name>.
+
+  --js    Generate a JavaScript app (TypeScript is the default)
+  --help  Show this message`;
+
+// A new app must land in an empty (or absent) directory so nothing is clobbered.
+function isEmptyDir(dir) {
+  if (!existsSync(dir)) return true;
+  return readdirSync(dir).length === 0;
+}
+
+async function main() {
+  const { appName, js, help } = parseArgs(process.argv.slice(2));
+
+  if (help || !appName) {
+    console.log(USAGE);
+    process.exit(help ? 0 : 1);
+  }
+
+  const targetDir = resolve(process.cwd(), appName);
+  if (!isEmptyDir(targetDir)) {
+    console.error(`Cannot create app: "${appName}" already exists and is not empty.`);
+    process.exit(1);
+  }
+
+  // The package name is the destination folder name (the arg may be a path).
+  await scaffold({ targetDir, appName: basename(targetDir), js });
+
+  const lang = js ? "JavaScript" : "TypeScript";
+  console.log(`\nCreated a ${lang} smaoog app in ${targetDir}\n`);
+  console.log("Next steps:\n");
+  console.log(`  cd ${appName}`);
+  console.log("  npm install");
+  console.log("  npm run dev\n");
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/preview.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// Local preview of the create-smaoog template.
+//
+// Scaffolds the template into `examples/preview` (a workspace member, so the
+// generated `smaoog` dependency is rewritten from "latest" to "workspace:*" and
+// resolves to this repo's framework source instead of a published release),
+// installs, and starts the dev server. This is the fastest way to see what a
+// freshly scaffolded app looks like while iterating on the template or the
+// framework. The preview directory is gitignored and recreated on each run.
+//
+// Usage:
+//   node src/preview.js [--js] [--no-dev]
+//
+//   --js       Preview the JavaScript template (TypeScript is the default)
+//   --no-dev   Scaffold and install only; skip starting the dev server
+import { spawnSync } from "node:child_process";
+import { readFile, rm, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+import { scaffold } from "./scaffold.js";
+
+const REPO_ROOT = fileURLToPath(new URL("../../..", import.meta.url));
+const PREVIEW_DIR = join(REPO_ROOT, "examples", "preview");
+
+function parseArgs(argv) {
+  return {
+    js: argv.includes("--js"),
+    dev: !argv.includes("--no-dev"),
+  };
+}
+
+function run(command, args, opts = {}) {
+  const result = spawnSync(command, args, { stdio: "inherit", cwd: REPO_ROOT, ...opts });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`\`${command} ${args.join(" ")}\` exited with code ${result.status}`);
+  }
+}
+
+async function main() {
+  const { js, dev } = parseArgs(process.argv.slice(2));
+  const lang = js ? "JavaScript" : "TypeScript";
+
+  // Start from a clean directory so a previous run's files never linger.
+  await rm(PREVIEW_DIR, { recursive: true, force: true });
+  await scaffold({ targetDir: PREVIEW_DIR, appName: "preview", js });
+
+  // Point the generated app at this repo's framework source rather than the
+  // published "latest" release, so the preview reflects local changes.
+  const pkgPath = join(PREVIEW_DIR, "package.json");
+  const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+  pkg.name = "@smaoog-examples/preview";
+  pkg.dependencies.smaoog = "workspace:*";
+  await writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+
+  console.log(`\nScaffolded the ${lang} template into examples/preview\n`);
+
+  // Install at the workspace root so pnpm links the local `smaoog` package.
+  // Installing adds an importer entry for the (gitignored) preview app to the
+  // committed lockfile; snapshot and restore it so the working tree stays clean.
+  // node_modules is already linked at this point, so the dev server is
+  // unaffected by restoring the on-disk lockfile.
+  const lockPath = join(REPO_ROOT, "pnpm-lock.yaml");
+  const lockBefore = await readFile(lockPath, "utf8").catch(() => null);
+  run("pnpm", ["install"]);
+  if (lockBefore !== null) await writeFile(lockPath, lockBefore);
+
+  if (!dev) {
+    console.log("\nSkipping dev server (--no-dev). Start it with:\n");
+    console.log("  pnpm --filter @smaoog-examples/preview dev\n");
+    return;
+  }
+
+  console.log("\nStarting the preview dev server...\n");
+  run("pnpm", ["--filter", "@smaoog-examples/preview", "dev"]);
+}
+
+main().catch((err) => {
+  console.error(err?.message ?? err);
+  process.exit(1);
+});

package/src/scaffold.js

@@ -0,0 +1,178 @@
+import { cp, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TEMPLATE_DIR = fileURLToPath(new URL("../template", import.meta.url));
+
+// Pinned versions for the generated app. Kept here as the single source of truth
+// for what a new smaoog app depends on. `smaoog` itself tracks the "latest"
+// dist-tag so a freshly scaffolded app always pulls the newest framework release
+// during the alpha, without create-smaoog needing a version bump per release.
+const VERSIONS = {
+  react: "^19.2.0",
+  "react-dom": "^19.2.0",
+  smaoog: "latest",
+  "@tailwindcss/vite": "^4.3.1",
+  tailwindcss: "^4.3.1",
+  // Kept in sync with the repo's typescript devDependency, so the version a
+  // generated app pins is the same major the scaffold typecheck test validates
+  // smaoog's declarations against.
+  typescript: "^6.0.3",
+  "@types/react": "^19.2.0",
+  "@types/react-dom": "^19.2.0",
+};
+
+// Files that are binary and must be copied byte-for-byte (no text transform).
+const BINARY = new Set([".ico", ".png", ".jpg", ".jpeg", ".webp", ".woff", ".woff2"]);
+
+async function walk(dir) {
+  const out = [];
+  for (const entry of await readdir(dir, { withFileTypes: true })) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...(await walk(full)));
+    else out.push(full);
+  }
+  return out;
+}
+
+function isBinary(path) {
+  const dot = path.lastIndexOf(".");
+  return dot !== -1 && BINARY.has(path.slice(dot));
+}
+
+// The single TypeScript template is the source of truth; the JavaScript app is
+// derived from it (extensions renamed, no tsconfig). Deriving JS rewrites the few
+// extension-bearing references and erases the small amount of type-only syntax the
+// template carries (see toJsContent).
+function jsRename(rel) {
+  if (rel.endsWith(".tsx")) return rel.slice(0, -4) + ".jsx";
+  if (rel.endsWith(".ts")) return rel.slice(0, -3) + ".js";
+  return rel;
+}
+
+export function toJsContent(content) {
+  // The Document references the client entry by its real filename, which becomes
+  // .js in a JavaScript app. Type-only imports and the small amount of template
+  // annotation syntax are removed so the JS variant is still derived from the TS
+  // template without maintaining a second source tree. The template confines its
+  // types to these strippable forms on purpose, so a zero-dependency text pass
+  // (no TypeScript/esbuild) is enough to derive valid JavaScript.
+  return content
+    .replaceAll("client-entry.ts", "client-entry.js")
+    .replace(/^import\s+type\s+[^;]+;\n/gm, "")
+    .replace(/^type\s+\w+\s*=[^\n]*;\n/gm, "")
+    .replaceAll(": DocumentProps", "")
+    .replace(/: SmaoogRequest\b/g, "")
+    .replace(/: SmaoogResponse<[^>]*>/g, "")
+    .replaceAll(": Props", "");
+}
+
+// Turn a directory name into a valid npm package name: lowercase, only
+// url-safe characters, no leading dot/dash/underscore. Falls back to "app" if
+// nothing usable remains (e.g. a name that was all punctuation).
+function toPackageName(name) {
+  const slug = String(name)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^[._-]+/, "")
+    .slice(0, 214)
+    .replace(/[._-]+$/, "");
+  return slug || "app";
+}
+
+function packageJson(appName, js) {
+  const pick = (...names) => Object.fromEntries(names.map((n) => [n, VERSIONS[n]]));
+  return (
+    JSON.stringify(
+      {
+        name: toPackageName(appName),
+        version: "0.0.1",
+        private: true,
+        type: "module",
+        scripts: { dev: "smaoog dev", build: "smaoog build", start: "smaoog start" },
+        dependencies: pick("react", "react-dom", "smaoog"),
+        devDependencies: js
+          ? pick("@tailwindcss/vite", "tailwindcss")
+          : pick(
+              "@tailwindcss/vite",
+              "@types/react",
+              "@types/react-dom",
+              "tailwindcss",
+              "typescript",
+            ),
+      },
+      null,
+      2,
+    ) + "\n"
+  );
+}
+
+function readme(appName) {
+  return [
+    `# ${appName}`,
+    "",
+    "A new app built with [smaoog](https://github.com/anges244/smaoog).",
+    "",
+    "## Development",
+    "",
+    "```bash",
+    "npm install",
+    "npm run dev",
+    "```",
+    "",
+    "## Production",
+    "",
+    "```bash",
+    "npm run build",
+    "npm run start",
+    "```",
+    "",
+  ].join("\n");
+}
+
+// Generate a new smaoog app into `targetDir`. `js` selects the JavaScript variant
+// (derived from the TypeScript template). Returns the list of created
+// app-relative paths.
+export async function scaffold({ targetDir, appName, js = false }) {
+  await mkdir(targetDir, { recursive: true });
+  const created = [];
+
+  const write = async (rel, contents) => {
+    const dest = join(targetDir, rel);
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, contents);
+    created.push(rel);
+  };
+
+  for (const file of await walk(TEMPLATE_DIR)) {
+    let rel = relative(TEMPLATE_DIR, file).split("\\").join("/");
+
+    // tsconfig only belongs to the TypeScript app.
+    if (rel === "tsconfig.json" && js) continue;
+    // npm strips a literal .gitignore from a published package, so the template
+    // ships it as `gitignore`; restore the dot on scaffold.
+    if (rel === "gitignore") rel = ".gitignore";
+
+    if (isBinary(file)) {
+      const dest = join(targetDir, rel);
+      await mkdir(dirname(dest), { recursive: true });
+      await cp(file, dest);
+      created.push(rel);
+      continue;
+    }
+
+    let content = await readFile(file, "utf8");
+    if (js) {
+      rel = jsRename(rel);
+      content = toJsContent(content);
+    }
+    await write(rel, content);
+  }
+
+  await write("package.json", packageJson(appName, js));
+  await write("README.md", readme(appName));
+
+  created.sort();
+  return created;
+}

package/template/gitignore

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

package/template/src/app.css

@@ -0,0 +1 @@
+@import "tailwindcss";

package/template/src/client-entry.ts

@@ -0,0 +1,3 @@
+// The browser entry. Importing "smaoog/client" boots hydration, <Link>
+// navigation, and <Form> behavior. Add any browser-only setup below.
+import "smaoog/client";

package/template/src/document.tsx

@@ -0,0 +1,21 @@
+import { ClientEntry, ReactRefresh, Stylesheet } from "smaoog";
+import type { DocumentProps } from "smaoog";
+
+export default function Document({ children, head }: DocumentProps) {
+  return (
+    <html lang="en">
+      <head>
+        <meta charSet="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <link rel="icon" href="/favicon.ico" />
+        <Stylesheet href="src/app.css" />
+        {head}
+        <ReactRefresh />
+      </head>
+      <body>
+        <main id="root">{children}</main>
+        <ClientEntry src="src/client-entry.ts" />
+      </body>
+    </html>
+  );
+}

package/template/src/routes/index.tsx

@@ -0,0 +1,31 @@
+import type { SmaoogRequest, SmaoogResponse } from "smaoog";
+
+type Props = { renderedAt: string };
+
+// A route can export a handler per HTTP method. This GET runs on the server and
+// passes its result to the component below as props. So the HTML you receive is
+// already rendered (view source to confirm), no client fetch required.
+export function GET(req: SmaoogRequest, res: SmaoogResponse<Props>) {
+  return res.render({ renderedAt: new Date().toLocaleString() });
+}
+
+export const meta = {
+  title: "smaoog app",
+  description: "A new app built with smaoog.",
+};
+
+export default function Home({ renderedAt }: Props) {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-4 bg-slate-50 text-slate-900">
+      <h1 className="text-4xl font-bold">Welcome to smaoog</h1>
+      <p className="text-slate-600">Server-rendered at {renderedAt}.</p>
+      <p className="text-slate-600">
+        Edit{" "}
+        <code className="rounded bg-slate-200 px-1.5 py-0.5">
+          src/routes/index
+        </code>{" "}
+        and reload.
+      </p>
+    </main>
+  );
+}

package/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src"]
+}