create-softeneers-app 0.1.0 → 0.2.1

package/templates/hono-api/src/cars/routes.ts

@@ -0,0 +1,43 @@
+import { Hono } from "hono";
+
+import { carStore } from "./store.js";
+import { parseNewCar, ValidationError } from "./validate.js";
+
+export const cars = new Hono();
+
+cars.get("/", async (c) => {
+  return c.json(await carStore.list());
+});
+
+cars.get("/:id", async (c) => {
+  const car = await carStore.get(Number(c.req.param("id")));
+  if (!car) return c.json({ message: "Car not found." }, 404);
+  return c.json(car);
+});
+
+cars.post("/", async (c) => {
+  try {
+    const car = await carStore.create(parseNewCar(await c.req.json()));
+    return c.json(car, 201);
+  } catch (error) {
+    if (error instanceof ValidationError) return c.json({ message: error.message }, 400);
+    throw error;
+  }
+});
+
+cars.put("/:id", async (c) => {
+  try {
+    const car = await carStore.update(Number(c.req.param("id")), parseNewCar(await c.req.json()));
+    if (!car) return c.json({ message: "Car not found." }, 404);
+    return c.json(car);
+  } catch (error) {
+    if (error instanceof ValidationError) return c.json({ message: error.message }, 400);
+    throw error;
+  }
+});
+
+cars.delete("/:id", async (c) => {
+  const removed = await carStore.remove(Number(c.req.param("id")));
+  if (!removed) return c.json({ message: "Car not found." }, 404);
+  return c.body(null, 204);
+});

package/templates/hono-api/src/cars/store.ts

@@ -0,0 +1,150 @@
+import { DEMO_CARS } from "./demo.js";
+import type { Car, NewCar } from "./types.js";
+
+// The data layer behind the CRUD routes. With the `db` toggle on it persists to
+// MySQL (Sequelize via @softeneers/db) and **falls back to an in-memory store if
+// the database is unreachable**, so `npm run dev` always yields a working,
+// pre-seeded demo. With `db` off it is always in-memory.
+export interface CarStore {
+  list(): Promise<Car[]>;
+  get(id: number): Promise<Car | null>;
+  create(input: NewCar): Promise<Car>;
+  update(id: number, input: NewCar): Promise<Car | null>;
+  remove(id: number): Promise<boolean>;
+}
+
+// In-memory backend (the default, and the fallback when no database is reachable).
+function createMemoryStore(seed = true): CarStore {
+  let nextId = 1;
+  const cars = new Map<number, Car>();
+  if (seed) {
+    for (const car of DEMO_CARS) {
+      const id = nextId++;
+      cars.set(id, { id, ...car });
+    }
+  }
+  return {
+    async list() {
+      return [...cars.values()].sort((a, b) => a.id - b.id);
+    },
+    async get(id) {
+      return cars.get(id) ?? null;
+    },
+    async create(input) {
+      const car: Car = { id: nextId++, ...input };
+      cars.set(car.id, car);
+      return car;
+    },
+    async update(id, input) {
+      const car = cars.get(id);
+      if (!car) return null;
+      const next: Car = { ...car, ...input };
+      cars.set(id, next);
+      return next;
+    },
+    async remove(id) {
+      return cars.delete(id);
+    },
+  };
+}
+
+// #if db
+import { assertConnection, DataTypes, Model } from "@softeneers/db";
+
+import { sequelize } from "../db.js";
+
+class CarModel extends Model {
+  declare id: number;
+  declare brand: string;
+  declare model: string;
+  declare year: number;
+}
+
+CarModel.init(
+  {
+    id: { type: DataTypes.INTEGER, autoIncrement: true, primaryKey: true },
+    brand: { type: DataTypes.STRING, allowNull: false },
+    model: { type: DataTypes.STRING, allowNull: false },
+    year: { type: DataTypes.INTEGER, allowNull: false },
+  },
+  { sequelize, modelName: "Car", tableName: "cars" },
+);
+
+export { CarModel };
+
+const toCar = (m: CarModel): Car => ({ id: m.id, brand: m.brand, model: m.model, year: m.year });
+
+function createDbStore(): CarStore {
+  return {
+    async list() {
+      return (await CarModel.findAll({ order: [["id", "ASC"]] })).map(toCar);
+    },
+    async get(id) {
+      const m = await CarModel.findByPk(id);
+      return m ? toCar(m) : null;
+    },
+    async create(input) {
+      return toCar(await CarModel.create(input));
+    },
+    async update(id, input) {
+      const m = await CarModel.findByPk(id);
+      if (!m) return null;
+      await m.update(input);
+      return toCar(m);
+    },
+    async remove(id) {
+      const m = await CarModel.findByPk(id);
+      if (!m) return false;
+      await m.destroy();
+      return true;
+    },
+  };
+}
+
+// Resolve the backend once, lazily, on first use: try MySQL (create tables +
+// seed if empty); on any connection error, fall back to the in-memory store.
+let backend: Promise<CarStore> | null = null;
+function resolveBackend(): Promise<CarStore> {
+  if (!backend) {
+    backend = (async () => {
+      try {
+        await assertConnection(sequelize);
+        await sequelize.sync();
+        const db = createDbStore();
+        if ((await db.list()).length === 0) {
+          for (const car of DEMO_CARS) await db.create(car);
+        }
+        console.log("Data store: MySQL");
+        return db;
+      } catch {
+        console.warn(
+          "Data store: in-memory — database unreachable. Run `docker compose up -d` (and `npm run db:migrate && npm run db:seed`) for MySQL.",
+        );
+        return createMemoryStore();
+      }
+    })();
+  }
+  return backend;
+}
+
+export const carStore: CarStore = {
+  async list() {
+    return (await resolveBackend()).list();
+  },
+  async get(id) {
+    return (await resolveBackend()).get(id);
+  },
+  async create(input) {
+    return (await resolveBackend()).create(input);
+  },
+  async update(id, input) {
+    return (await resolveBackend()).update(id, input);
+  },
+  async remove(id) {
+    return (await resolveBackend()).remove(id);
+  },
+};
+// #endif
+// #if !db
+export const carStore: CarStore = createMemoryStore();
+// #endif

package/templates/hono-api/src/cars/types.ts

@@ -0,0 +1,8 @@
+export interface Car {
+  id: number;
+  brand: string;
+  model: string;
+  year: number;
+}
+
+export type NewCar = Omit<Car, "id">;

package/templates/hono-api/src/cars/validate.ts

@@ -0,0 +1,16 @@
+import type { NewCar } from "./types.js";
+
+/** Thrown when a request body is not a valid car. Mapped to HTTP 400. */
+export class ValidationError extends Error {}
+
+/** Validate and normalize an untrusted request body into a NewCar. */
+export function parseNewCar(body: unknown): NewCar {
+  const b = (body ?? {}) as Record<string, unknown>;
+  const brand = typeof b.brand === "string" ? b.brand.trim() : "";
+  const model = typeof b.model === "string" ? b.model.trim() : "";
+  const year = Number(b.year);
+  if (!brand || !model || !Number.isInteger(year)) {
+    throw new ValidationError("brand (string), model (string) and year (integer) are required.");
+  }
+  return { brand, model, year };
+}

package/templates/hono-api/src/db.ts

@@ -0,0 +1,13 @@
+import { createDb } from "@softeneers/db";
+
+import { env } from "./env.js";
+
+// A configured (but not-yet-connected) Sequelize instance. Importing a model
+// registers it; `assertConnection`/`sync` open the connection on startup.
+export const sequelize = createDb({
+  host: env.DB_HOST,
+  port: env.DB_PORT,
+  database: env.DB_NAME,
+  username: env.DB_USER,
+  password: env.DB_PASSWORD,
+});

package/templates/hono-api/src/env.ts

@@ -0,0 +1,23 @@
+import "dotenv/config";
+
+import { createEnv, z } from "@softeneers/env";
+
+// Validated, typed environment. Boot fails fast with a readable message if the
+// .env is wrong. Variables for a feature exist only when that toggle is on.
+export const env = createEnv({
+  schema: {
+    PORT: z.coerce.number().default(4000),
+    CORS_ORIGIN: z.string().default("http://localhost:3000"),
+    // #if db
+    DB_HOST: z.string().default("127.0.0.1"),
+    DB_PORT: z.coerce.number().default(3306),
+    DB_NAME: z.string().default("app_dev"),
+    DB_USER: z.string().default("root"),
+    DB_PASSWORD: z.string().default(""),
+    // #endif
+    // #if auth
+    AUTH_SECRET: z.string().min(16).default("dev-secret-change-me-to-a-long-random-string"),
+    AUTH_BASE_URL: z.string().default("http://localhost:4000"),
+    // #endif
+  },
+});

package/templates/hono-api/src/index.ts

@@ -0,0 +1,26 @@
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+import { cors } from "hono/cors";
+
+import { cars } from "./cars/routes.js";
+import { env } from "./env.js";
+// #if auth
+import { auth } from "./auth/auth.js";
+// #endif
+
+const app = new Hono();
+
+app.use("*", cors({ origin: env.CORS_ORIGIN }));
+
+app.get("/health", (c) => c.json({ ok: true }));
+
+app.route("/api/cars", cars);
+
+// #if auth
+// better-auth speaks the Fetch API, so hand it the raw Request and return its Response.
+app.on(["GET", "POST"], "/api/auth/*", (c) => auth.handler(c.req.raw));
+// #endif
+
+serve({ fetch: app.fetch, port: env.PORT }, (info) => {
+  console.log(`API running on http://localhost:${info.port}`);
+});

package/templates/hono-api/src/scripts/migrate.ts

@@ -0,0 +1,13 @@
+import "dotenv/config";
+
+import { assertConnection } from "@softeneers/db";
+
+import { sequelize } from "../db.js";
+import "../cars/store.js"; // importing the store registers the Car model
+
+const reset = process.argv.includes("--reset");
+
+await assertConnection(sequelize);
+await sequelize.sync({ force: reset });
+console.log(reset ? "Database reset — tables recreated." : "Database synced — tables ensured.");
+await sequelize.close();

package/templates/hono-api/src/scripts/seed.ts

@@ -0,0 +1,20 @@
+import "dotenv/config";
+
+import { assertConnection } from "@softeneers/db";
+
+import { DEMO_CARS } from "../cars/demo.js";
+import { CarModel } from "../cars/store.js";
+import { sequelize } from "../db.js";
+
+await assertConnection(sequelize);
+await sequelize.sync();
+
+const count = await CarModel.count();
+if (count > 0) {
+  console.log(`Skipped seeding — ${count} cars already present.`);
+} else {
+  await CarModel.bulkCreate([...DEMO_CARS]);
+  console.log(`Seeded ${DEMO_CARS.length} cars.`);
+}
+
+await sequelize.close();

package/templates/hono-api/test/validate.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { parseNewCar, ValidationError } from "../src/cars/validate.ts";
+
+test("parses a valid car body", () => {
+  assert.deepEqual(parseNewCar({ brand: "Tesla", model: "Model 3", year: 2023 }), {
+    brand: "Tesla",
+    model: "Model 3",
+    year: 2023,
+  });
+});
+
+test("trims strings and coerces a numeric year", () => {
+  assert.deepEqual(parseNewCar({ brand: " Ford ", model: " Mustang ", year: "1969" }), {
+    brand: "Ford",
+    model: "Mustang",
+    year: 1969,
+  });
+});
+
+test("rejects an incomplete body", () => {
+  assert.throws(() => parseNewCar({ brand: "Toyota" }), ValidationError);
+  assert.throws(() => parseNewCar({}), ValidationError);
+});

package/templates/hono-api/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/templates/minimal/.env.example

@@ -0,0 +1,2 @@
+# Copied to .env by create-softeneers-app. Real .env files are never committed.
+GREET_NAME=world

package/templates/minimal/README.md

@@ -0,0 +1,33 @@
+# {{PROJECT_NAME}}
+
+A zero-framework **Node + TypeScript** starter generated by
+[`create-softeneers-app`](https://www.npmjs.com/package/create-softeneers-app).
+A clean blank slate: typed source in `src/`, a `node:test` suite, and a `tsc`
+build — nothing else to unlearn.
+
+## Scripts
+
+```bash
+npm run dev        # run src/index.ts with watch (tsx)
+npm run build      # type-check + emit dist/ (tsc)
+npm start          # run the built dist/index.js
+npm run typecheck  # tsc --noEmit
+npm test           # node:test suite (via tsx)
+```
+
+## Layout
+
+```
+src/index.ts        your program (exports greet() as an example)
+test/greet.test.ts  the test suite
+tsconfig.json       strict TypeScript, NodeNext modules
+.env.example        copied to .env on generation (GREET_NAME)
+```
+
+## Try it
+
+```bash
+npm install
+npm test
+npm run dev -- Ada      # → "Hello, Ada!"
+```

package/templates/minimal/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "minimal",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Zero-framework Node + TypeScript starter generated by create-softeneers-app.",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  }
+}

package/templates/minimal/src/index.ts

@@ -0,0 +1,20 @@
+// Minimal Node + TypeScript starter. Replace this with your program — the
+// structure (typed source in src/, a node:test suite, tsc build) is the point.
+
+export interface GreetOptions {
+  /** Who to greet. Defaults to "world". */
+  name?: string;
+  /** Greeting word. Defaults to "Hello". */
+  greeting?: string;
+}
+
+export function greet({ name = "world", greeting = "Hello" }: GreetOptions = {}): string {
+  return `${greeting}, ${name}!`;
+}
+
+// Run directly (`npm run dev` / `npm start`) — but stay importable from tests.
+const invokedDirectly = process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+if (invokedDirectly) {
+  const name = process.argv[2] ?? process.env.GREET_NAME;
+  console.log(greet({ name }));
+}

package/templates/minimal/test/greet.test.ts

@@ -0,0 +1,12 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { greet } from "../src/index.ts";
+
+test("greets the world by default", () => {
+  assert.equal(greet(), "Hello, world!");
+});
+
+test("uses the provided name and greeting", () => {
+  assert.equal(greet({ name: "Ada", greeting: "Hi" }), "Hi, Ada!");
+});

package/templates/minimal/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "strict": true,
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/templates/tanstack-start/.env.example

@@ -0,0 +1,11 @@
+# #if db
+DB_HOST=127.0.0.1
+DB_PORT=3306
+DB_NAME=app_dev
+DB_USER=root
+DB_PASSWORD=
+# #endif
+# #if auth
+AUTH_SECRET=dev-secret-change-me-to-a-long-random-string
+AUTH_BASE_URL=http://localhost:3000
+# #endif

package/templates/tanstack-start/README.md

@@ -0,0 +1,74 @@
+# {{PROJECT_NAME}}
+
+A **TanStack Start** (fullstack React) app generated by
+[`create-softeneers-app`](https://www.npmjs.com/package/create-softeneers-app),
+with a full cars CRUD demo wired through type-safe **server functions**.
+
+## Scripts
+
+```bash
+npm run dev        # Vite dev server on http://localhost:3000
+npm run build      # production build (client + SSR)
+npm start          # preview the production build
+npm run typecheck  # generate routes + tsc --noEmit
+npm test           # vitest
+# #if db
+npm run db:migrate # create/sync tables
+npm run db:seed    # insert sample cars
+npm run db:reset   # drop, recreate, reseed
+# #endif
+```
+
+## Structure
+
+```
+src/routes/index.tsx        home page
+src/routes/cars.tsx         cars CRUD UI (loader + server functions)
+src/server/cars.ts          createServerFn RPCs (list / create / remove)
+src/server/store.ts         data layer (MySQL or in-memory)
+# #if auth
+src/routes/api/auth/$.ts    better-auth catch-all route (/api/auth/*)
+src/server/auth.ts          better-auth instance
+# #endif
+```
+
+The `/cars` page loads data with a route `loader` and mutates via server
+functions — no hand-written API client, end-to-end type safety.
+# #if db
+
+## Database
+
+Persistence is MySQL via Sequelize ([`@softeneers/db`](https://www.npmjs.com/package/@softeneers/db)).
+**`npm run dev` works immediately even without a database** — the server falls
+back to a pre-seeded in-memory store when MySQL is unreachable. To switch on real
+persistence, set `DB_*` in `.env` and start MySQL:
+
+```bash
+# #if docker
+docker compose up -d   # start MySQL
+# #endif
+# The server auto-creates and seeds tables on first connect; these scripts give
+# you explicit control:
+npm run db:migrate && npm run db:seed
+```
+# #endif
+# #if auth
+
+## Authentication
+
+Email + password auth via better-auth ([`@softeneers/auth`](https://www.npmjs.com/package/@softeneers/auth)),
+served at `/api/auth/*`. Set a strong `AUTH_SECRET` in `.env`, and add the
+`better-auth/react` client in your components to drive sign-in/up flows.
+# #endif
+
+## Getting started
+
+```bash
+npm install
+npm run dev          # a pre-seeded CRUD demo on http://localhost:3000 — no other setup
+```
+# #if db
+
+The app starts immediately on an in-memory demo and uses MySQL automatically once
+it's reachable — see **Database** above to enable persistence.
+# #endif

package/templates/tanstack-start/docker-compose.yml

@@ -0,0 +1,15 @@
+services:
+  db:
+    image: mysql:8
+    restart: unless-stopped
+    environment:
+      MYSQL_DATABASE: ${DB_NAME:-app_dev}
+      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD:-}
+      MYSQL_ALLOW_EMPTY_PASSWORD: "yes"
+    ports:
+      - "${DB_PORT:-3306}:3306"
+    volumes:
+      - db_data:/var/lib/mysql
+
+volumes:
+  db_data:

package/templates/tanstack-start/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "tanstack-start",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#/*": "./src/*"
+  },
+  "scripts": {
+    "dev": "vite dev --port 3000",
+    "generate-routes": "tsr generate",
+    "build": "vite build",
+    "start": "vite preview --port 3000",
+    "typecheck": "tsr generate && tsc --noEmit",
+    "db:migrate": "tsx src/server/scripts/migrate.ts",
+    "db:seed": "tsx src/server/scripts/seed.ts",
+    "db:reset": "tsx src/server/scripts/migrate.ts --reset && tsx src/server/scripts/seed.ts",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@softeneers/auth": "^0.1.0",
+    "@softeneers/db": "^0.1.0",
+    "@softeneers/env": "^0.1.0",
+    "@tailwindcss/vite": "^4.1.18",
+    "@tanstack/react-devtools": "latest",
+    "@tanstack/react-router": "latest",
+    "@tanstack/react-router-devtools": "latest",
+    "@tanstack/react-router-ssr-query": "latest",
+    "@tanstack/react-start": "latest",
+    "@tanstack/router-plugin": "^1.132.0",
+    "dotenv": "^16.4.5",
+    "lucide-react": "^0.545.0",
+    "mysql2": "^3.11.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwindcss": "^4.1.18"
+  },
+  "devDependencies": {
+    "@tailwindcss/typography": "^0.5.16",
+    "@tanstack/devtools-vite": "latest",
+    "@tanstack/router-cli": "^1.132.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "@vitejs/plugin-react": "^6.0.1",
+    "jsdom": "^28.1.0",
+    "tsx": "^4.19.0",
+    "typescript": "^6.0.2",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.5"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["esbuild", "lightningcss"]
+  }
+}

package/templates/tanstack-start/public/manifest.json

@@ -0,0 +1,25 @@
+{
+  "short_name": "TanStack App",
+  "name": "Create TanStack App Sample",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "logo192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "logo512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

package/templates/tanstack-start/public/robots.txt

@@ -0,0 +1,3 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *
+Disallow: