create-softeneers-app 0.1.0 → 0.2.0

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

@@ -0,0 +1,92 @@
+import type { Car, NewCar } from "./types.js";
+
+// The data layer behind the CRUD routes. With the `db` toggle on this is backed
+// by MySQL (Sequelize via @softeneers/db); with it off it's an in-memory Map so
+// the API runs with zero infrastructure. Both satisfy the same CarStore.
+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>;
+}
+
+// #if db
+import { 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 });
+
+export const carStore: CarStore = {
+  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;
+  },
+};
+// #endif
+// #if !db
+let nextId = 1;
+const cars = new Map<number, Car>();
+
+export const carStore: CarStore = {
+  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);
+  },
+};
+// #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,44 @@
+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 db
+import { assertConnection } from "@softeneers/db";
+
+import { sequelize } from "./db.js";
+import "./cars/store.js"; // registers the Car model on the connection
+// #endif
+// #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
+
+async function start(): Promise<void> {
+  // #if db
+  await assertConnection(sequelize);
+  await sequelize.sync();
+  console.log("Database connected.");
+  // #endif
+  serve({ fetch: app.fetch, port: env.PORT }, (info) => {
+    console.log(`API running on http://localhost:${info.port}`);
+  });
+}
+
+start().catch((error) => {
+  console.error("Failed to start:", error);
+  process.exit(1);
+});

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,25 @@
+import "dotenv/config";
+
+import { assertConnection } from "@softeneers/db";
+
+import { carStore } from "../cars/store.js";
+import { sequelize } from "../db.js";
+
+await assertConnection(sequelize);
+await sequelize.sync();
+
+const existing = await carStore.list();
+if (existing.length > 0) {
+  console.log(`Skipped seeding — ${existing.length} cars already present.`);
+} else {
+  for (const car of [
+    { brand: "Toyota", model: "Corolla", year: 2021 },
+    { brand: "Tesla", model: "Model 3", year: 2023 },
+    { brand: "Ford", model: "Mustang", year: 1969 },
+  ]) {
+    await carStore.create(car);
+  }
+  console.log("Seeded 3 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,73 @@
+# {{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)).
+Set `DB_*` in `.env`, then:
+
+```bash
+# #if docker
+docker compose up -d   # start MySQL
+# #endif
+npm run db:migrate && npm run db:seed
+```
+
+Generate with `--no-db` to use a dependency-free in-memory store instead.
+# #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
+# #if docker
+docker compose up -d
+# #endif
+# #if db
+npm run db:migrate && npm run db:seed
+# #endif
+npm run dev
+```

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:

package/templates/tanstack-start/softeneers.template.json

@@ -0,0 +1,17 @@
+{
+  "toggles": { "db": true, "auth": false, "docker": true },
+  "fragments": {
+    "db": {
+      "removePaths": ["src/server/db.ts", "src/server/scripts", "docker-compose.yml"],
+      "removeDeps": ["@softeneers/db", "mysql2"],
+      "removeScripts": ["db:migrate", "db:seed", "db:reset"]
+    },
+    "auth": {
+      "removePaths": ["src/server/auth.ts", "src/routes/api"],
+      "removeDeps": ["@softeneers/auth"]
+    },
+    "docker": {
+      "removePaths": ["docker-compose.yml"]
+    }
+  }
+}

package/templates/tanstack-start/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/tanstack-start/src/cars/validate.ts

@@ -0,0 +1,16 @@
+import type { NewCar } from './types'
+
+/** Thrown when a submitted car is invalid. */
+export class ValidationError extends Error {}
+
+/** Validate and normalize untrusted input into a NewCar. Runs on the server. */
+export function parseNewCar(input: unknown): NewCar {
+  const b = (input ?? {}) 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/tanstack-start/src/router.tsx

@@ -0,0 +1,19 @@
+import { createRouter as createTanStackRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+export function getRouter() {
+  const router = createTanStackRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: 'intent',
+    defaultPreloadStaleTime: 0,
+  })
+
+  return router
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>
+  }
+}