create-apexjs 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andre Corugda
+
+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/dist/index.js

@@ -1,12 +1,22 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { cpSync, existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "fs";
+import { spawnSync } from "child_process";
+import { cpSync, existsSync, readFileSync, readdirSync, renameSync, writeFileSync } from "fs";
 import { basename, join, resolve } from "path";
 import { fileURLToPath } from "url";
-import { spawnSync } from "child_process";
 import { defineCommand, runMain } from "citty";
 var TEMPLATE_DIR = fileURLToPath(new URL("../templates/default", import.meta.url));
+function substituteName(dir, name) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) substituteName(p, name);
+    else {
+      const txt = readFileSync(p, "utf8");
+      if (txt.includes("{{name}}")) writeFileSync(p, txt.replaceAll("{{name}}", name));
+    }
+  }
+}
 function detectPackageManager() {
   const ua = process.env.npm_config_user_agent || "";
   if (ua.startsWith("pnpm")) return "pnpm";
@@ -35,9 +45,22 @@ var main = defineCommand({
     description: "Scaffold a new Apex JS app"
   },
   args: {
-    dir: { type: "positional", required: false, description: "Target directory", default: "apex-app" },
-    install: { type: "boolean", default: true, description: "Install dependencies (use --no-install to skip)" },
-    git: { type: "boolean", default: true, description: "Initialize a git repository (use --no-git to skip)" }
+    dir: {
+      type: "positional",
+      required: false,
+      description: "Target directory",
+      default: "apex-app"
+    },
+    install: {
+      type: "boolean",
+      default: true,
+      description: "Install dependencies (use --no-install to skip)"
+    },
+    git: {
+      type: "boolean",
+      default: true,
+      description: "Initialize a git repository (use --no-git to skip)"
+    }
   },
   run({ args }) {
     const target = resolve(process.cwd(), args.dir);
@@ -51,12 +74,7 @@ var main = defineCommand({
     cpSync(TEMPLATE_DIR, target, { recursive: true });
     const gitignore = join(target, "_gitignore");
     if (existsSync(gitignore)) renameSync(gitignore, join(target, ".gitignore"));
-    for (const rel of ["package.json", "README.md"]) {
-      const file = join(target, rel);
-      if (existsSync(file)) {
-        writeFileSync(file, readFileSync(file, "utf8").replaceAll("{{name}}", name));
-      }
-    }
+    substituteName(target, name);
     console.log(`
   ${c.cyan("Apex JS")} app created in ${args.dir}`);
     const pm = detectPackageManager();
@@ -71,27 +89,34 @@ var main = defineCommand({
     }
     let installed = false;
     if (args.install) {
-      console.log(`
+      console.log(
+        `
   Installing dependencies with ${c.cyan(pm)}\u2026 ${c.dim("(first install can take a minute)")}
-`);
+`
+      );
       const installArgs = pm === "npm" ? ["install", "--no-audit", "--no-fund"] : ["install"];
       installed = run(pm, installArgs, target);
       if (!installed) {
-        console.log(`
+        console.log(
+          `
   ${c.yellow("\u26A0")}  Dependency install failed \u2014 run it yourself after cd'ing in.
-`);
+`
+        );
       }
     }
     const runPrefix = pm === "npm" ? "npm run" : pm;
     const steps = [`cd ${args.dir}`];
     if (!installed) steps.push(pm === "yarn" ? "yarn" : `${pm} install`);
-    steps.push(`${runPrefix} dev          ${c.dim("# start the dev server \u2192 http://localhost:3000")}`);
+    steps.push(
+      `${runPrefix} dev          ${c.dim("# start the dev server \u2192 http://localhost:3000")}`
+    );
     console.log(`
   ${installed ? c.green("Ready.") : "Next steps:"}
 ${steps.map((s) => `    ${s}`).join("\n")}
 
-  ${c.yellow("Note:")} ${c.cyan("apex")} is a project command, not a global one \u2014 run it as
-        ${c.cyan(runPrefix + " dev")}  (or ${c.cyan("npx apex dev")}), never a bare "apex".
+  ${c.yellow("Run the CLI with:")} ${c.cyan(`${runPrefix} dev`)}   ${c.dim("(or npx apex dev)")}
+        A bare ${c.cyan("apex")} won't resolve \u2014 it's a local dependency, like ${c.cyan("next")} or ${c.cyan("vite")}.
+        ${c.dim("Prefer a global command? ")}${c.cyan("npm i -g @apex-stack/core")}${c.dim(" \u2192 then `apex dev` works anywhere.")}
   ${c.dim("Islands mode:")} ${runPrefix} dev:islands
   ${gitOk ? c.dim("Git repository initialized. ") : ""}Your server/api/*.ts routes are also MCP tools at /mcp.
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-apexjs",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Scaffold a new Apex JS app",
   "type": "module",
   "license": "MIT",
@@ -28,15 +28,15 @@
     "dist",
     "templates"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "citty": "^0.1.6"
   },
   "engines": {
     "node": ">=20.19"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/templates/default/README.md

@@ -1,33 +1,55 @@
 # {{name}}
 
-An [Apex JS](https://github.com/andrecorugda/apexjs) app — a meta-framework for
-Alpine.js that renders on the server and hydrates in the browser.
+An [Apex JS](https://apexjs.site) app — HTML-first, server-rendered, AI-native.
 
-## Getting started
+## Commands
 
 ```bash
-npm install
-npm run dev
+npm run dev          # dev server → http://localhost:3000
+npm run dev:islands  # static-first islands mode (ship ~zero JS)
+npm run build        # production build
+npm start            # run the production server build
+npm test             # run tests (Vitest)
+npm run typecheck    # strict type-check
 ```
 
-Then open [http://localhost:3000](http://localhost:3000).
+> `apex` is a project command — run it via `npm run dev`, or install it globally
+> (`npm i -g @apex-stack/core`) to use `apex dev` directly.
 
-## Islands mode
-
-Ship interactive JavaScript only where you need it:
+## Project structure
 
-```bash
-apex dev --islands
+```
+pages/         File-based routes (.alpine) — server-rendered, then hydrated.
+layouts/       Shared page shells; default.alpine wraps every page (<slot/>).
+components/    Reusable <PascalCase/> components with scoped styles.
+server/api/    Typed routes (defineApexRoute) — each is a REST endpoint AND an MCP tool.
+services/      Business logic as plain OO classes. Keep routes thin; delegate here.
+shared/        Types/interfaces shared by the backend and the frontend.
+stores/        Global, SSR-safe state — $store.x, reactive across pages/islands.
+composables/   Reusable client logic (useX) for <script client> blocks.
+tests/         Vitest tests. `npm test` runs them.
+db/            Optional: a database + resources. See db/README.md.
+public/        Static assets served as-is.
 ```
 
-## Project structure
+## Conventions (clean code)
+
+- **Thin routes → services.** A route/loader validates input and delegates to a service
+  class in `services/`. Business logic stays testable in isolation and reusable everywhere.
+- **Types live in `shared/`.** One source of truth; strict TypeScript enforces them across
+  backend and frontend — no drift.
+- **Tests by default.** `npm test` runs Vitest (see `tests/greeting.test.ts`).
 
-- `pages/*.alpine` — single-file components. The `<script server>` block runs on
-  the server; its `loader()` return value becomes the Alpine `x-data` scope.
-- `server/api/*.ts` — API routes defined with `defineApexRoute`.
+## Generators
 
-## AI-native API
+```bash
+apex make page about
+apex make component Card
+apex make api todos
+apex make service Billing     # → services/BillingService.ts (OO class)
+apex make store cart
+apex make layout marketing
+apex make test billing        # → tests/billing.test.ts
+```
 
-Every route in `server/api/*.ts` is a REST endpoint **and** an MCP tool at the
-same time. Set `mcp: true` on a route (see `server/api/hello.ts`) and it is
-automatically exposed to AI agents at the `/mcp` endpoint — no extra wiring.
+Full docs: https://apexjs.site

package/templates/default/components/Counter.alpine

@@ -0,0 +1,15 @@
+<template x-data="{ count: Number(start) }">
+  <button class="counter" @click="count++" x-text="label + ': ' + count"></button>
+</template>
+
+<style scoped>
+  .counter {
+    padding: 0.45rem 0.9rem;
+    border: 1px solid #6366f1;
+    border-radius: 0.5rem;
+    background: #eef2ff;
+    color: #3730a3;
+    cursor: pointer;
+    font: inherit;
+  }
+</style>

package/templates/default/composables/useToggle.ts

@@ -0,0 +1,14 @@
+/**
+ * Reusable client logic. Import it in a <script client> block and use it in x-data:
+ *
+ *   <script client> import { useToggle } from '../composables/useToggle' </script>
+ *   <template x-data="useToggle(true)"> <button @click="toggle()" x-text="on"></button> </template>
+ */
+export function useToggle(initial = false) {
+  return {
+    on: initial,
+    toggle() {
+      this.on = !this.on
+    },
+  }
+}

package/templates/default/db/README.md

@@ -0,0 +1,18 @@
+# db/
+
+Data is opt-in. To add a database with resources that are REST **and** MCP by default:
+
+```bash
+npm i @apex-stack/data @libsql/client   # install only the driver you use
+```
+
+Then add `db/schema.ts` (Drizzle tables), `db/index.ts` (`createDb` + `applyMigrations`),
+and a resource in `server/api/*.ts`:
+
+```ts
+import { defineResource } from '@apex-stack/data'
+export default defineResource('posts', { db, table: schema.posts, insert: { title: z.string() } })
+```
+
+That one line gives you `GET/POST/PATCH/DELETE /api/posts` plus the MCP tools
+`posts_list/get/create/update/delete`. See https://apexjs.site/data.html

package/templates/default/layouts/default.alpine

@@ -0,0 +1,16 @@
+<template>
+  <header class="site-header">
+    <a class="brand" href="/">{{name}}</a>
+  </header>
+  <main>
+    <slot></slot>
+  </main>
+  <footer class="site-footer">Built with Apex JS</footer>
+</template>
+
+<style scoped>
+  .site-header { padding: 1rem 1.5rem; border-bottom: 1px solid #e2e8f0; }
+  .brand { font-weight: 700; color: #2563eb; text-decoration: none; }
+  main { max-width: 44rem; margin: 0 auto; padding: 2.5rem 1.5rem; font-family: system-ui, -apple-system, "Segoe UI", sans-serif; line-height: 1.6; color: #1e293b; }
+  .site-footer { padding: 1.5rem; text-align: center; color: #64748b; font-size: 0.9rem; border-top: 1px solid #e2e8f0; }
+</style>

package/templates/default/package.json

@@ -4,11 +4,20 @@
   "type": "module",
   "scripts": {
     "dev": "apex dev",
-    "dev:islands": "apex dev --islands"
+    "dev:islands": "apex dev --islands",
+    "build": "apex build",
+    "start": "apex start",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "alpinejs": "^3.14.8",
     "@apex-stack/core": "latest",
+    "alpinejs": "^3.14.8",
     "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
   }
 }

package/templates/default/pages/index.alpine

@@ -1,107 +1,38 @@
 <script server lang="ts">
   export function loader() {
     return {
-      title: 'Welcome to Apex JS',
+      title: 'Welcome to {{name}}',
       tagline: 'The meta-framework for Alpine.js — server-rendered, then hydrated.',
     }
   }
 </script>
 
 <template x-data="{ open: false }">
-  <main>
-    <h1 x-text="title"></h1>
-    <p class="tagline" x-text="tagline"></p>
+  <h1 x-text="title"></h1>
+  <p class="tagline" x-text="tagline"></p>
 
-    <section class="card">
-      <p>
-        This page was rendered on the server from
-        <code>pages/index.alpine</code>, then hydrated by Alpine in the browser.
-        Edit it and save to see your changes live.
-      </p>
-
-      <button type="button" @click="open = !open" x-text="open ? 'Hide the details' : 'Show me how'"></button>
-
-      <div x-show="open" x-transition class="details">
-        <p>
-          The <code>loader()</code> in the server block runs on the server and
-          hands its data straight to Alpine's <code>x-data</code> scope — no
-          fetch, no boilerplate.
-        </p>
-        <p>
-          Next, open <code>server/api/hello.ts</code>: it's a REST endpoint
-          <em>and</em> an MCP tool at <code>/mcp</code> at the same time.
-        </p>
-      </div>
-    </section>
-
-    <p class="hint">
-      Run <code>apex dev --islands</code> to ship interactive islands only where
-      you need them.
+  <section class="card">
+    <p>
+      This was rendered on the server from <code>pages/index.alpine</code>, wrapped in
+      <code>layouts/default.alpine</code>, then hydrated by Alpine. Edit and save to see it live.
     </p>
-  </main>
+    <button type="button" @click="open = !open" x-text="open ? 'Hide' : 'Show me how'"></button>
+    <div x-show="open" x-transition class="details">
+      <p>The <code>loader()</code> runs on the server and hands its data to Alpine's <code>x-data</code>.</p>
+      <p>Open <code>server/api/hello.ts</code>: a thin route → <code>GreetingService</code>, exposed as REST <em>and</em> an MCP tool.</p>
+    </div>
+  </section>
+
+  <p class="hint">A reusable component that hydrates in the browser:</p>
+  <Counter start="0" label="Clicks" />
 </template>
 
 <style scoped>
-  main {
-    max-width: 40rem;
-    margin: 4rem auto;
-    padding: 0 1.5rem;
-    font-family: system-ui, -apple-system, 'Segoe UI', sans-serif;
-    line-height: 1.6;
-    color: #1e293b;
-  }
-
-  h1 {
-    color: #2563eb;
-    font-size: 2.5rem;
-    margin-bottom: 0.5rem;
-  }
-
-  .tagline {
-    font-size: 1.15rem;
-    color: #475569;
-    margin-top: 0;
-  }
-
-  .card {
-    margin-top: 2rem;
-    padding: 1.5rem;
-    border: 1px solid #e2e8f0;
-    border-radius: 0.75rem;
-    background: #f8fafc;
-  }
-
-  button {
-    margin-top: 0.5rem;
-    padding: 0.6rem 1.1rem;
-    font-size: 1rem;
-    font-weight: 600;
-    color: #fff;
-    background: #2563eb;
-    border: none;
-    border-radius: 0.5rem;
-    cursor: pointer;
-    transition: background 0.15s ease;
-  }
-
-  button:hover {
-    background: #1d4ed8;
-  }
-
-  .details {
-    margin-top: 1rem;
-  }
-
-  code {
-    padding: 0.1rem 0.35rem;
-    font-size: 0.9em;
-    background: #e2e8f0;
-    border-radius: 0.35rem;
-  }
-
-  .hint {
-    margin-top: 2rem;
-    font-size: 0.95rem;
-    color: #64748b;
-  }
+  h1 { color: #2563eb; font-size: 2.25rem; margin-bottom: 0.25rem; }
+  .tagline { font-size: 1.1rem; color: #475569; margin-top: 0; }
+  .card { margin-top: 1.5rem; padding: 1.25rem; border: 1px solid #e2e8f0; border-radius: 0.75rem; background: #f8fafc; }
+  .card button { margin-top: 0.5rem; padding: 0.55rem 1rem; font-weight: 600; color: #fff; background: #2563eb; border: none; border-radius: 0.5rem; cursor: pointer; }
+  .details { margin-top: 1rem; }
+  code { padding: 0.1rem 0.35rem; background: #e2e8f0; border-radius: 0.35rem; font-size: 0.9em; }
+  .hint { margin-top: 1.5rem; color: #64748b; font-size: 0.95rem; }
 </style>

package/templates/default/server/api/hello.ts

@@ -1,10 +1,18 @@
 import { defineApexRoute } from '@apex-stack/core'
 import { z } from 'zod'
+import { GreetingService } from '../../services/GreetingService'
 
+const greetings = new GreetingService()
+
+/**
+ * A route is a thin adapter: validate input, delegate to a service, return the
+ * result. Because `mcp: true`, this is ALSO an MCP tool named "hello" at /mcp —
+ * one definition, REST + AI-callable.
+ */
 export default defineApexRoute({
   method: 'GET',
-  description: 'Say hello to someone by name',
+  description: 'Greet someone by name',
   input: { name: z.string() },
   mcp: true,
-  handler: ({ input }) => ({ message: `Hello, ${input.name}!` }),
+  handler: ({ input }) => greetings.greet(input.name),
 })

package/templates/default/services/GreetingService.ts

@@ -0,0 +1,12 @@
+import type { Greeting } from '../shared/types'
+
+/**
+ * A service holds business logic as a plain class — testable in isolation and
+ * reusable from routes, page loaders, and jobs. Keep routes/loaders thin: they
+ * validate input and delegate to a service. This is the clean-code backbone.
+ */
+export class GreetingService {
+  greet(name: string): Greeting {
+    return { message: `Hello, ${name}!`, at: new Date().toISOString() }
+  }
+}

package/templates/default/shared/types.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared types — the single source of truth for shapes used across the app,
+ * on the BACKEND (routes, services) and the FRONTEND. Import from '../shared/types'.
+ *
+ * Defining types here (instead of inline) is what keeps a growing codebase clean:
+ * one place to change a shape, and the compiler enforces it everywhere it's used.
+ */
+export interface Greeting {
+  message: string
+  at: string
+}

package/templates/default/stores/ui.ts

@@ -0,0 +1,9 @@
+import { defineStore } from '@apex-stack/core'
+
+// Global, SSR-safe state shared across pages, components, and islands: $store.ui
+export default defineStore('ui', () => ({
+  menuOpen: false,
+  toggleMenu() {
+    this.menuOpen = !this.menuOpen
+  },
+}))

package/templates/default/tests/greeting.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from 'vitest'
+import { GreetingService } from '../services/GreetingService'
+
+// Services are plain classes, so they test in isolation — no server needed.
+// Generate more with:  apex make test <name>
+describe('GreetingService', () => {
+  it('greets by name', () => {
+    const g = new GreetingService().greet('Apex')
+    expect(g.message).toBe('Hello, Apex!')
+    expect(typeof g.at).toBe('string')
+  })
+})

package/templates/default/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true
+  },
+  "include": ["server", "services", "shared", "stores", "composables", "tests", "db"]
+}

package/templates/default/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    include: ['tests/**/*.test.ts'],
+  },
+})