create-utopia 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Hesketh
+
+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,61 @@
+# create-utopia
+
+Scaffold a new UtopiaJS project.
+
+## Usage
+
+```bash
+npx create-utopia my-app
+```
+
+Or with other package managers:
+
+```bash
+pnpm create utopia my-app
+yarn create utopia my-app
+bun create utopia my-app
+```
+
+## Features
+
+The interactive CLI prompts for:
+
+- **Project name** -- validates as a legal npm package name
+- **Language** -- TypeScript (default) or JavaScript
+- **Features** -- select any combination:
+  - Router (file-based routing)
+  - SSR (server-side rendering with Express)
+  - Email (template-based emails)
+  - AI (chat, streaming, adapters)
+  - CSS Preprocessor (Sass or Less)
+- **Git initialization** -- optional initial commit
+
+## What It Creates
+
+```
+my-app/
+  index.html
+  package.json
+  vite.config.ts
+  tsconfig.json        # TypeScript only
+  src/
+    main.ts
+    App.utopia
+    routes/            # if Router selected
+      +page.utopia
+      +layout.utopia
+  server.js            # if SSR selected
+  src/
+    entry-client.ts    # if SSR selected
+    entry-server.ts    # if SSR selected
+```
+
+When AI is selected, an example chat API route is scaffolded at `src/routes/api/chat/+server.ts` with a `.env.example` file.
+
+## Programmatic
+
+The CLI is the primary interface. The package exports no public API -- it runs directly via the `create-utopia` bin entry point.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/index.js

@@ -0,0 +1,436 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import prompts from "prompts";
+import { green, cyan, yellow, bold, red, dim } from "kolorist";
+function isValidPackageName(name) {
+  return /^(?:@[a-z0-9-*~][a-z0-9-*._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/.test(name);
+}
+function toValidPackageName(name) {
+  return name.trim().toLowerCase().replace(/\s+/g, "-").replace(/^[._]/, "").replace(/[^a-z0-9-~]+/g, "-");
+}
+function isEmptyDir(dirPath) {
+  if (!fs.existsSync(dirPath)) return true;
+  const files = fs.readdirSync(dirPath);
+  return files.length === 0 || files.length === 1 && files[0] === ".git";
+}
+function copyDir(src, dest, skip = /* @__PURE__ */ new Set(), _root) {
+  const root = _root ?? src;
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    const relativePath = path.relative(root, srcPath);
+    const shouldSkip = skip.has(relativePath) || [...skip].some(
+      (s) => relativePath.startsWith(s + path.sep)
+    );
+    if (shouldSkip) continue;
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath, skip, root);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+function removeDir(dirPath) {
+  if (!fs.existsSync(dirPath)) return;
+  fs.rmSync(dirPath, { recursive: true, force: true });
+}
+function replaceInFile(filePath, replacements) {
+  let content = fs.readFileSync(filePath, "utf-8");
+  for (const [search, replace] of Object.entries(replacements)) {
+    content = content.replaceAll(search, replace);
+  }
+  fs.writeFileSync(filePath, content, "utf-8");
+}
+function renameFile(dir, from, to) {
+  const srcPath = path.join(dir, from);
+  if (fs.existsSync(srcPath)) {
+    fs.renameSync(srcPath, path.join(dir, to));
+  }
+}
+function scaffoldProject(root, options) {
+  const { projectName, language, useRouter, useSSR, useEmail, useAI, cssPreprocessor } = options;
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const templateDir = path.resolve(__dirname, "..", "template");
+  const skip = /* @__PURE__ */ new Set();
+  if (!useRouter) {
+    skip.add(path.join("src", "routes"));
+  }
+  if (language === "javascript") {
+    skip.add("tsconfig.json");
+  }
+  if (!useSSR) {
+    skip.add(path.join("src", "entry-server.ts"));
+    skip.add(path.join("src", "entry-client.ts"));
+    skip.add("server.js");
+  }
+  copyDir(templateDir, root, skip);
+  const pkgJsonPath = path.join(root, "package.json");
+  const indexHtmlPath = path.join(root, "index.html");
+  replaceInFile(pkgJsonPath, { "{{projectName}}": projectName });
+  replaceInFile(indexHtmlPath, { "{{projectName}}": projectName });
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+  const deps = pkg["dependencies"];
+  const devDeps = pkg["devDependencies"];
+  if (!useRouter && deps) {
+    delete deps["@matthesketh/utopia-router"];
+  }
+  if (language === "javascript" && devDeps) {
+    delete devDeps["typescript"];
+  }
+  if (cssPreprocessor === "sass" && devDeps) {
+    devDeps["sass"] = "^1.80.0";
+  } else if (cssPreprocessor === "less" && devDeps) {
+    devDeps["less"] = "^4.2.0";
+  }
+  if (useEmail && deps) {
+    deps["@matthesketh/utopia-email"] = "^0.0.1";
+  }
+  if (useAI && deps) {
+    deps["@matthesketh/utopia-ai"] = "^0.0.1";
+  }
+  fs.writeFileSync(pkgJsonPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+  if (language === "javascript") {
+    renameFile(root, "vite.config.ts", "vite.config.js");
+    renameFile(path.join(root, "src"), "main.ts", "main.js");
+    replaceInFile(indexHtmlPath, { "/src/main.ts": "/src/main.js" });
+  }
+  if (useSSR) {
+    const ssrPkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    const ssrDeps = ssrPkg["dependencies"];
+    const ssrDevDeps = ssrPkg["devDependencies"];
+    ssrDeps["@matthesketh/utopia-server"] = "^0.0.1";
+    ssrDeps["express"] = "^4.21.0";
+    if (ssrDevDeps["vite"]) {
+      ssrDeps["vite"] = ssrDevDeps["vite"];
+    }
+    const scripts = ssrPkg["scripts"];
+    scripts["dev"] = "node server.js";
+    scripts["build"] = "npm run build:client && npm run build:server";
+    scripts["build:client"] = "vite build --outDir dist/client";
+    scripts["build:server"] = "vite build --outDir dist/server --ssr src/entry-server.ts";
+    scripts["preview"] = "NODE_ENV=production node server.js";
+    fs.writeFileSync(pkgJsonPath, JSON.stringify(ssrPkg, null, 2) + "\n", "utf-8");
+    const ssrIndexHtml = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${projectName}</title>
+  <!--ssr-head-->
+</head>
+<body>
+  <div id="app"><!--ssr-outlet--></div>
+  <script type="module" src="/src/entry-client.ts"></script>
+</body>
+</html>
+`;
+    fs.writeFileSync(indexHtmlPath, ssrIndexHtml, "utf-8");
+    const mainTsPath = path.join(root, "src", "main.ts");
+    if (fs.existsSync(mainTsPath)) {
+      fs.rmSync(mainTsPath);
+    }
+    if (language === "javascript") {
+      renameFile(path.join(root, "src"), "entry-client.ts", "entry-client.js");
+      renameFile(path.join(root, "src"), "entry-server.ts", "entry-server.js");
+      replaceInFile(indexHtmlPath, { "/src/entry-client.ts": "/src/entry-client.js" });
+      replaceInFile(
+        path.join(root, "server.js"),
+        { "entry-server.ts": "entry-server.js" }
+      );
+    }
+  }
+  if (!useRouter) {
+    const appPath = path.join(root, "src", "App.utopia");
+    const simpleApp = `<template>
+  <div id="app">
+    <h1>Welcome to UtopiaJS</h1>
+    <p>Edit <code>src/App.utopia</code> to get started.</p>
+  </div>
+</template>
+
+<style>
+#app {
+  font-family: system-ui, -apple-system, sans-serif;
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 20px;
+}
+
+h1 {
+  color: #333;
+}
+</style>
+`;
+    fs.writeFileSync(appPath, simpleApp, "utf-8");
+    const mainPath = path.join(root, "src", language === "typescript" ? "main.ts" : "main.js");
+    const simpleMain = `import { mount } from '@matthesketh/utopia-runtime'
+import App from './App.utopia'
+
+mount(App, '#app')
+`;
+    fs.writeFileSync(mainPath, simpleMain, "utf-8");
+  }
+  if (useAI) {
+    const ext = language === "typescript" ? "ts" : "js";
+    const apiChatDir = path.join(root, "src", "routes", "api", "chat");
+    fs.mkdirSync(apiChatDir, { recursive: true });
+    const serverFile = path.join(apiChatDir, `+server.${ext}`);
+    const serverContent = `import { createAI } from '@matthesketh/utopia-ai';
+import { openaiAdapter } from '@matthesketh/utopia-ai/openai';
+import { streamSSE } from '@matthesketh/utopia-ai';
+
+const ai = createAI(openaiAdapter({
+  apiKey: process.env.OPENAI_API_KEY!,
+}));
+
+export async function POST(req${language === "typescript" ? ": any" : ""}, res${language === "typescript" ? ": any" : ""}) {
+  // Parse request body
+  const body = await new Promise${language === "typescript" ? "<string>" : ""}((resolve) => {
+    let data = '';
+    req.on('data', (chunk${language === "typescript" ? ": Buffer" : ""}) => { data += chunk.toString(); });
+    req.on('end', () => resolve(data));
+  });
+
+  const { messages } = JSON.parse(body);
+  const stream = ai.stream({ messages, model: 'gpt-4o' });
+  await streamSSE(res, stream);
+}
+`;
+    fs.writeFileSync(serverFile, serverContent, "utf-8");
+    const envExamplePath = path.join(root, ".env.example");
+    fs.writeFileSync(envExamplePath, "OPENAI_API_KEY=sk-your-key-here\n", "utf-8");
+  }
+}
+function initGitRepo(root) {
+  try {
+    execSync("git init", { cwd: root, stdio: "ignore" });
+    execSync("git add -A", { cwd: root, stdio: "ignore" });
+    execSync('git commit -m "Initial commit (created with create-utopia)"', {
+      cwd: root,
+      stdio: "ignore"
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+function detectPackageManager() {
+  const userAgent = process.env["npm_config_user_agent"] ?? "";
+  if (userAgent.startsWith("yarn")) return "yarn";
+  if (userAgent.startsWith("pnpm")) return "pnpm";
+  if (userAgent.startsWith("bun")) return "bun";
+  return "npm";
+}
+function getPackageManagerCommands(pm) {
+  switch (pm) {
+    case "yarn":
+      return { install: "yarn", dev: "yarn dev" };
+    case "pnpm":
+      return { install: "pnpm install", dev: "pnpm dev" };
+    case "bun":
+      return { install: "bun install", dev: "bun dev" };
+    default:
+      return { install: "npm install", dev: "npm run dev" };
+  }
+}
+function printBanner() {
+  console.log();
+  console.log(bold(cyan("  create-utopia")) + dim(" v0.0.1"));
+  console.log();
+}
+function printSuccessBox(projectName, root) {
+  const pm = detectPackageManager();
+  const cmds = getPackageManagerCommands(pm);
+  const cwd = process.cwd();
+  const cdPath = path.relative(cwd, root);
+  const lines = [
+    "",
+    green("  UtopiaJS Project Ready!"),
+    ""
+  ];
+  const boxWidth = 35;
+  const top = `  \u256D${"\u2500".repeat(boxWidth)}\u256E`;
+  const bottom = `  \u2570${"\u2500".repeat(boxWidth)}\u256F`;
+  console.log();
+  console.log(top);
+  for (const line of lines) {
+    const padding = " ".repeat(Math.max(0, boxWidth - stripAnsi(line).length));
+    console.log(`  \u2502${line}${padding}\u2502`);
+  }
+  console.log(bottom);
+  console.log();
+  console.log("  Next steps:");
+  if (cdPath !== ".") {
+    console.log(cyan(`    cd ${cdPath}`));
+  }
+  console.log(cyan(`    ${cmds.install}`));
+  console.log(cyan(`    ${cmds.dev}`));
+  console.log();
+  console.log(`  Happy coding! \u{1F680}`);
+  console.log();
+}
+function stripAnsi(str) {
+  return str.replace(/\u001B\[[0-9;]*m/g, "");
+}
+async function main() {
+  printBanner();
+  const argProjectName = process.argv[2]?.trim();
+  const defaultProjectName = argProjectName ?? "utopia-app";
+  let response;
+  try {
+    response = await prompts(
+      [
+        {
+          type: argProjectName ? null : "text",
+          name: "projectName",
+          message: "Project name:",
+          initial: defaultProjectName,
+          validate: (value) => {
+            const name = toValidPackageName(value);
+            if (!isValidPackageName(name)) {
+              return "Invalid package name. Use lowercase letters, numbers, and hyphens.";
+            }
+            return true;
+          }
+        },
+        {
+          type: (_prev, values) => {
+            const name = values["projectName"] ?? defaultProjectName;
+            const targetDir = path.resolve(process.cwd(), name);
+            if (!isEmptyDir(targetDir)) return "confirm";
+            return null;
+          },
+          name: "overwrite",
+          message: (_prev, values) => {
+            const name = values["projectName"] ?? defaultProjectName;
+            return `Target directory "${name}" is not empty. Remove existing files and continue?`;
+          }
+        },
+        {
+          type: "select",
+          name: "language",
+          message: "Language:",
+          choices: [
+            { title: "TypeScript", value: "typescript" },
+            { title: "JavaScript", value: "javascript" }
+          ],
+          initial: 0
+        },
+        {
+          type: "multiselect",
+          name: "features",
+          message: "Features:",
+          choices: [
+            { title: "Router (file-based routing)", value: "router", selected: true },
+            { title: "SSR (server-side rendering)", value: "ssr", selected: false },
+            { title: "Email (template-based emails)", value: "email", selected: false },
+            { title: "AI (chat, streaming, adapters)", value: "ai", selected: false },
+            { title: "CSS Preprocessor", value: "css-preprocessor", selected: false }
+          ],
+          instructions: dim("  (use space to toggle, enter to confirm)")
+        },
+        {
+          type: (_prev, values) => {
+            const features2 = values["features"];
+            return features2?.includes("css-preprocessor") ? "select" : null;
+          },
+          name: "cssPreprocessor",
+          message: "CSS Preprocessor:",
+          choices: [
+            { title: "Sass", value: "sass" },
+            { title: "Less", value: "less" }
+          ],
+          initial: 0
+        },
+        {
+          type: "confirm",
+          name: "initGit",
+          message: "Initialize a git repository?",
+          initial: true
+        }
+      ],
+      {
+        onCancel: () => {
+          console.log();
+          console.log(red("  Operation cancelled."));
+          console.log();
+          process.exit(1);
+        }
+      }
+    );
+  } catch (err) {
+    console.error(err);
+    process.exit(1);
+  }
+  const projectName = toValidPackageName(response.projectName ?? defaultProjectName);
+  const overwrite = response.overwrite ?? true;
+  const language = response.language ?? "typescript";
+  const features = response.features ?? ["router"];
+  const cssPreprocessor = response.cssPreprocessor ?? "none";
+  const shouldInitGit = response.initGit ?? true;
+  const useRouter = features.includes("router");
+  const useSSR = features.includes("ssr");
+  const useEmail = features.includes("email");
+  const useAI = features.includes("ai");
+  const root = path.resolve(process.cwd(), projectName);
+  if (fs.existsSync(root) && !isEmptyDir(root)) {
+    if (!overwrite) {
+      console.log(red("  Aborting."));
+      process.exit(1);
+    }
+    console.log(yellow(`  Removing existing files in ${projectName}...`));
+    removeDir(root);
+  }
+  console.log();
+  console.log(`  Scaffolding project in ${cyan(root)}...`);
+  console.log();
+  const options = {
+    projectName,
+    language,
+    useRouter,
+    useSSR,
+    useEmail,
+    useAI,
+    cssPreprocessor,
+    initGit: shouldInitGit
+  };
+  scaffoldProject(root, options);
+  const createdFiles = listFiles(root, root);
+  for (const file of createdFiles) {
+    console.log(`  ${dim("+")} ${file}`);
+  }
+  console.log();
+  if (shouldInitGit) {
+    const gitSuccess = initGitRepo(root);
+    if (gitSuccess) {
+      console.log(green("  Initialized git repository."));
+    } else {
+      console.log(yellow("  Could not initialize git repository."));
+    }
+  }
+  printSuccessBox(projectName, root);
+}
+function listFiles(dir, base) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    const relativePath = path.relative(base, fullPath);
+    if (entry.isDirectory()) {
+      results.push(...listFiles(fullPath, base));
+    } else {
+      results.push(relativePath);
+    }
+  }
+  return results;
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "create-utopia",
+  "version": "0.0.1",
+  "description": "Scaffold a new UtopiaJS project",
+  "type": "module",
+  "license": "MIT",
+  "author": "Matt <matt@matthesketh.pro>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wrxck/utopiajs.git",
+    "directory": "packages/create-utopia"
+  },
+  "homepage": "https://matthesketh.pro",
+  "keywords": [
+    "create",
+    "scaffold",
+    "cli",
+    "generator",
+    "starter",
+    "utopiajs"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "create-utopia": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "dependencies": {
+    "prompts": "^2.4.2",
+    "kolorist": "^1.8.0"
+  },
+  "devDependencies": {
+    "@types/prompts": "^2.4.9",
+    "tsup": "^8.0.0",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch"
+  }
+}

package/template/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>{{projectName}}</title>
+</head>
+<body>
+  <div id="app"></div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>

package/template/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "{{projectName}}",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@matthesketh/utopia-core": "^0.0.1",
+    "@matthesketh/utopia-runtime": "^0.0.1",
+    "@matthesketh/utopia-router": "^0.0.1"
+  },
+  "devDependencies": {
+    "@matthesketh/utopia-vite-plugin": "^0.0.1",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}

package/template/server.js

@@ -0,0 +1,75 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import express from 'express'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const isProduction = process.env.NODE_ENV === 'production'
+
+async function createServer() {
+  const app = express()
+
+  let vite
+
+  if (!isProduction) {
+    // In development, use Vite's dev server as middleware
+    const { createServer: createViteServer } = await import('vite')
+    vite = await createViteServer({
+      server: { middlewareMode: true },
+      appType: 'custom',
+    })
+    app.use(vite.middlewares)
+  } else {
+    // In production, serve the built client assets
+    app.use(express.static(path.resolve(__dirname, 'dist/client')))
+  }
+
+  app.use('*', async (req, res) => {
+    const url = req.originalUrl
+
+    try {
+      let template
+      let render
+
+      if (!isProduction) {
+        // In dev, read index.html and transform it through Vite
+        template = fs.readFileSync(path.resolve(__dirname, 'index.html'), 'utf-8')
+        template = await vite.transformIndexHtml(url, template)
+
+        // Load the server entry through Vite so it gets HMR
+        const mod = await vite.ssrLoadModule('/src/entry-server.ts')
+        render = mod.render
+      } else {
+        // In production, use the pre-built files
+        template = fs.readFileSync(
+          path.resolve(__dirname, 'dist/client/index.html'),
+          'utf-8',
+        )
+        const mod = await import('./dist/server/entry-server.js')
+        render = mod.render
+      }
+
+      const { html: appHtml, css } = render(url)
+
+      // Inject the rendered HTML and CSS into the template
+      let page = template
+      page = page.replace('<!--ssr-head-->', css ? `<style>${css}</style>` : '')
+      page = page.replace('<!--ssr-outlet-->', appHtml)
+
+      res.status(200).set({ 'Content-Type': 'text/html' }).end(page)
+    } catch (e) {
+      if (!isProduction) {
+        vite.ssrFixStacktrace(e)
+      }
+      console.error(e)
+      res.status(500).end(e.message)
+    }
+  })
+
+  const port = process.env.PORT || 3000
+  app.listen(port, () => {
+    console.log(`Server running at http://localhost:${port}`)
+  })
+}
+
+createServer()

package/template/src/App.utopia

@@ -0,0 +1,40 @@
+<template>
+  <div id="app">
+    <nav>
+      <a href="/">Home</a>
+      <a href="/about">About</a>
+    </nav>
+    <RouterView />
+  </div>
+</template>
+
+<script>
+import { createRouterView as RouterView } from '@utopia/router'
+</script>
+
+<style>
+#app {
+  font-family: system-ui, -apple-system, sans-serif;
+  max-width: 800px;
+  margin: 0 auto;
+  padding: 20px;
+}
+
+nav {
+  display: flex;
+  gap: 16px;
+  padding: 16px 0;
+  border-bottom: 1px solid #eee;
+  margin-bottom: 24px;
+}
+
+nav a {
+  color: #4a9eff;
+  text-decoration: none;
+  font-weight: 500;
+}
+
+nav a:hover {
+  text-decoration: underline;
+}
+</style>

package/template/src/entry-client.ts

@@ -0,0 +1,4 @@
+import { hydrate } from '@matthesketh/utopia-runtime'
+import App from './App.utopia'
+
+hydrate(App, '#app')

package/template/src/entry-server.ts

@@ -0,0 +1,6 @@
+import { renderToString } from '@matthesketh/utopia-server'
+import App from './App.utopia'
+
+export function render(_url: string): { html: string; css: string } {
+  return renderToString(App)
+}

package/template/src/main.ts

@@ -0,0 +1,9 @@
+import { mount } from '@matthesketh/utopia-runtime'
+import { createRouter } from '@matthesketh/utopia-router'
+import App from './App.utopia'
+
+// File-based routes are auto-generated by the vite plugin
+import routes from 'virtual:utopia-routes'
+
+createRouter(routes)
+mount(App, '#app')

package/template/src/routes/+layout.utopia

@@ -0,0 +1,3 @@
+<template>
+  <slot />
+</template>

package/template/src/routes/+page.utopia

@@ -0,0 +1,62 @@
+<template>
+  <div>
+    <h1>Welcome to UtopiaJS</h1>
+    <p>A compiler-first, signal-based UI framework.</p>
+
+    <div class="counter">
+      <p>Count: {{ count() }}</p>
+      <p>Doubled: {{ doubled() }}</p>
+      <button @click="increment">Increment</button>
+      <button @click="decrement">Decrement</button>
+      <button @click="reset">Reset</button>
+    </div>
+  </div>
+</template>
+
+<script>
+import { signal, computed } from '@utopia/core'
+
+const count = signal(0)
+const doubled = computed(() => count() * 2)
+
+function increment() {
+  count.update(n => n + 1)
+}
+
+function decrement() {
+  count.update(n => n - 1)
+}
+
+function reset() {
+  count.set(0)
+}
+</script>
+
+<style scoped>
+h1 {
+  color: #333;
+}
+
+.counter {
+  margin-top: 24px;
+  padding: 20px;
+  border-radius: 8px;
+  background: #f8f9fa;
+}
+
+button {
+  margin-right: 8px;
+  padding: 8px 16px;
+  border: 1px solid #ddd;
+  border-radius: 4px;
+  background: white;
+  cursor: pointer;
+  font-size: 14px;
+}
+
+button:hover {
+  background: #4a9eff;
+  color: white;
+  border-color: #4a9eff;
+}
+</style>

package/template/src/routes/about/+page.utopia

@@ -0,0 +1,19 @@
+<template>
+  <div>
+    <h1>About</h1>
+    <p>UtopiaJS is a modern web framework featuring:</p>
+    <ul>
+      <li>Fine-grained reactivity with signals</li>
+      <li>Compiler-first approach — no virtual DOM</li>
+      <li>Single-file components (.utopia)</li>
+      <li>File-based routing</li>
+      <li>TypeScript-first</li>
+    </ul>
+  </div>
+</template>
+
+<style scoped>
+ul {
+  line-height: 1.8;
+}
+</style>

package/template/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": false,
+    "sourceMap": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "preserve",
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src/**/*.ts", "src/**/*.d.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/vite.config.ts

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