create-faas-app 8.0.0-beta.3 → 8.0.0-beta.30

package/README.md

@@ -1,20 +1,77 @@
 # create-faas-app
 
-[![License: MIT](https://img.shields.io/npm/l/create-faas-app.svg)](https://github.com/faasjs/faasjs/blob/main/packages/create-faas-app/LICENSE)
-[![NPM Version](https://img.shields.io/npm/v/create-faas-app.svg)](https://www.npmjs.com/package/create-faas-app)
+Create a new FaasJS app from a curated starter template.
 
-Quick way to create a FaasJS project.
+FaasJS is optimized for database-driven React business applications. `create-faas-app` gives new projects a working starting point for the official path instead of asking every team to assemble React, API, database, testing, and UI conventions from scratch.
 
-## Usage
+## Quick Start
 
 ```bash
-# use npm
-npx create-faas-app --name faasjs
+npx create-faas-app --name my-faas-app
+cd my-faas-app
+npm run dev
+```
+
+The default template is `admin`, which demonstrates the curated React + Ant Design + PostgreSQL path.
+
+## Templates
+
+### `admin`
+
+Use `admin` for the golden-path FaasJS starter.
+
+```bash
+npx create-faas-app --name my-admin --template admin
+```
+
+It includes:
+
+- React app structure powered by Vite Plus
+- `@faasjs/ant-design` and Ant Design for business UI
+- `defineApi` endpoints for typed backend APIs
+- a copyable users slice with create, list, detail, update, migration, table types, and API tests
+- `@faasjs/pg` for PostgreSQL access and migrations
+- `@faasjs/pg-dev` for pg-dev-powered tests
+- `.env.example` for local database configuration
+- type declarations for PostgreSQL table inference
+
+This is the best starting point for admin panels, internal tools, SaaS dashboards, and other database-driven business applications.
+
+### `minimal`
 
-# use bun
-bunx create-faas-app --name faasjs
+Use `minimal` when you want a smaller React starter without the database and Ant Design stack.
+
+```bash
+npx create-faas-app --name my-minimal-app --template minimal
 ```
 
-## Functions
+It is useful for learning the core FaasJS runtime, building API-only or BFF-style projects, or adding a custom UI/database path intentionally.
+
+## Recommended Path
+
+Start with `admin` unless you have a specific reason not to. It shows how FaasJS expects complete application slices to fit together:
+
+- UI pages call typed APIs
+- APIs validate inputs at system boundaries
+- APIs use PostgreSQL through the shared database workflow
+- migrations and table types keep data contracts explicit
+- tests cover the API and database behavior
+
+FaasJS allows teams to replace parts of the stack, but the templates, docs, and examples optimize this curated path first.
+
+## Auth And Permissions
+
+Authentication and permissions are intentionally not built into FaasJS core because production auth requirements vary by product.
+
+The admin starter includes a small auth plugin demo. Treat it as a plugin pattern that shows how to inject current-user context, protect APIs, and model project-specific permissions. It is not a mandatory framework auth system.
+
+## Next Steps
+
+- Read the FaasJS guide at <https://faasjs.com/guide/>.
+- Review the root README for the project direction and package overview.
+- Explore runnable templates in <https://github.com/faasjs/faasjs/tree/main/templates>.
+- Use the admin starter users slice as the reference for complete UI/API/database/test examples.
+
+## API Docs
 
 - [main](functions/main.md)

package/dist/index.d.ts

@@ -1,24 +1,19 @@
-import { Command } from 'commander';
+import { Command } from "commander";
 
+//#region src/index.d.ts
 /**
- * [![License: MIT](https://img.shields.io/npm/l/create-faas-app.svg)](https://github.com/faasjs/faasjs/blob/main/packages/create-faas-app/LICENSE)
- * [![NPM Version](https://img.shields.io/npm/v/create-faas-app.svg)](https://www.npmjs.com/package/create-faas-app)
+ * Run the `create-faas-app` CLI with a provided argv array.
  *
- * Quick way to create a FaasJS project.
+ * @param {string[]} argv - CLI arguments forwarded to Commander.
+ * @returns {Promise<Command>} Commander program instance after parsing.
  *
- * ## Usage
+ * @example
+ * ```ts
+ * import { main } from 'create-faas-app'
  *
- * ```bash
- * # use npm
- * npx create-faas-app --name faasjs
- *
- * # use bun
- * bunx create-faas-app --name faasjs
+ * await main(['node', 'create-faas-app', '--help'])
  * ```
- *
- * @packageDocumentation
  */
-
 declare function main(argv: string[]): Promise<Command>;
-
-export { main };
+//#endregion
+export { main };

package/dist/index.mjs

@@ -1,162 +1,156 @@
-import { Command } from 'commander';
-import { execSync } from 'child_process';
-import { mkdirSync, writeFileSync, existsSync } from 'fs';
-import { join } from 'path';
-import { prompt } from 'enquirer';
-
-// src/index.ts
-
-// package.json
-var package_default = {
-  version: "v8.0.0-beta.2"};
-var Validator = {
-  name(input) {
-    const match = /^[a-z0-9-_]+$/i.test(input) ? true : "Must be a-z, 0-9 or -_";
-    if (match !== true) return match;
-    if (existsSync(input))
-      return `${input} folder exists, please try another name`;
-    return true;
-  }
-};
-async function action(options = {}) {
-  const answers = Object.assign(options, {});
-  if (!options.name || Validator.name(options.name) !== true)
-    answers.name = await prompt({
-      type: "input",
-      name: "value",
-      message: "Project name",
-      initial: "faasjs",
-      validate: Validator.name
-    }).then((res) => res.value);
-  if (!answers.name) return;
-  mkdirSync(answers.name);
-  const runtime = process.versions.bun ? "bun" : "npm";
-  writeFileSync(
-    join(answers.name, "faas.yaml"),
-    `defaults:
-  plugins:
-development:
-testing:
-staging:
-production:
-`
-  );
-  writeFileSync(
-    join(answers.name, "package.json"),
-    `{
-  "name": "${answers.name}",
-  "version": "1.0.0",
-  "private": true,
-  "scripts": {
-    "serve": "faas server",
-    "test": "vitest run"
-  },
-  "dependencies": {
-    "faasjs": "*"
-  },
-  "devDependencies": {
-    "vitest": "*"
-  }
-}`
-  );
-  writeFileSync(
-    join(answers.name, "tsconfig.json"),
-    `{
-  "compilerOptions": {
-    "downlevelIteration": true,
-    "esModuleInterop": true,
-    "target": "ES2019",
-    "module": "ESNext",
-    "moduleResolution": "node",
-    "baseUrl": "."
-  }
+import { Command } from "commander";
+import { execSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import enquirer from "enquirer";
+//#region package.json
+var version = "8.0.0-beta.29";
+//#endregion
+//#region src/action/index.ts
+const prompt = enquirer.prompt;
+const validateName = (input) => Validator.name(input);
+const templateRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "template");
+const ignoredTemplateEntries = new Set(["node_modules"]);
+const Validator = { name(input) {
+	const match = /^[a-z0-9-_]+$/i.test(input) ? true : "Must be a-z, 0-9 or -_";
+	if (match !== true) return match;
+	if (existsSync(input)) return `${input} folder exists, please try another name`;
+	return true;
+} };
+function getTemplateNames() {
+	return readdirSync(templateRoot, { withFileTypes: true }).filter((entry) => entry.isDirectory()).map((entry) => entry.name).sort();
 }
-`
-  );
-  writeFileSync(
-    join(answers.name, ".gitignore"),
-    `node_modules/
-tmp/
-coverage/
-*.tmp.js
-`
-  );
-  mkdirSync(join(answers.name, ".vscode"));
-  writeFileSync(
-    join(answers.name, ".vscode", "settings.json"),
-    `{
-  "editor.detectIndentation": true,
-  "editor.insertSpaces": true,
-  "editor.tabSize": 2,
-  "editor.codeActionsOnSave": {
-    "source.fixAll": true
-  },
-  "editor.wordWrap": "on",
-  "files.insertFinalNewline": true,
-  "files.trimFinalNewlines": true,
-  "files.trimTrailingWhitespace": true
+function resolveTemplateName(template = "admin") {
+	const templates = getTemplateNames();
+	if (templates.includes(template)) return template;
+	throw new Error(`Unknown template "${template}". Available templates: ${templates.join(", ")}`);
 }
-`
-  );
-  writeFileSync(
-    join(answers.name, ".vscode", "extensions.json"),
-    `{
-  "recommendations": [
-    "faasjs.faasjs-snippets"
-  ]
+function renderTemplate(content, replacements) {
+	return Object.entries(replacements).reduce((result, [key, value]) => result.replaceAll(`{{${key}}}`, value), content);
 }
-`
-  );
-  execSync(`cd ${answers.name} && ${runtime} install`, { stdio: "inherit" });
-  writeFileSync(
-    join(answers.name, "index.func.ts"),
-    `import { useFunc } from '@faasjs/func'
-import { useHttp } from '@faasjs/http'
-
-export const func = useFunc(() => {
-  const http = useHttp<{ name: string }>()
-
-  return async () => \`Hello, \${http.params.name}\`
-})
-`
-  );
-  mkdirSync(join(answers.name, "__tests__"));
-  writeFileSync(
-    join(answers.name, "__tests__", "index.test.ts"),
-    `import { test } from '@faasjs/test'
-import { func } from '../index.func'
-
-describe('hello', () => {
-  it('should work', async () => {
-    const testFunc = test(func)
-
-    const { statusCode, data } = await testFunc.JSONhandler<string>({ name: 'world' })
-
-    expect(statusCode).toEqual(200)
-    expect(data).toEqual('Hello, world')
-  })
-})
-`
-  );
-  if (runtime === "bun") {
-    execSync(`cd ${answers.name} && bun test`, { stdio: "inherit" });
-  } else execSync(`cd ${answers.name} && npm run test`, { stdio: "inherit" });
+function generateSessionSecret() {
+	return randomBytes(32).toString("hex");
+}
+function copyTemplateDirectory(sourcePath, targetPath, replacements) {
+	mkdirSync(targetPath, { recursive: true });
+	for (const entry of readdirSync(sourcePath, { withFileTypes: true })) {
+		if (ignoredTemplateEntries.has(entry.name)) continue;
+		const nextSourcePath = join(sourcePath, entry.name);
+		const nextTargetPath = join(targetPath, entry.name === "gitignore" ? ".gitignore" : entry.name);
+		if (entry.isDirectory()) {
+			copyTemplateDirectory(nextSourcePath, nextTargetPath, replacements);
+			continue;
+		}
+		writeFileSync(nextTargetPath, renderTemplate(readFileSync(nextSourcePath, "utf8"), replacements));
+	}
 }
-function action_default(program) {
-  program.description("Create a new faas app").on("--help", () => console.log("Examples:\nnpx create-faas-app")).option("--name <name>", "Project name").action(action);
+function scaffold(rootPath, replacements, templateName) {
+	mkdirSync(rootPath);
+	copyTemplateDirectory(join(templateRoot, templateName), rootPath, replacements);
+}
+/**
+* Scaffold a new FaasJS app from a bundled template and install its dependencies.
+*
+* @param {object} [options] - Optional CLI arguments used to choose the project name and template.
+* @param {string} [options.name] - Target folder name for the generated app.
+* @param {string} [options.template] - Template name such as `admin` or `minimal`.
+* @returns {Promise<void>} Resolves after the project is generated and its test command finishes.
+* @throws {Error} When the selected template is unknown.
+* @example
+* ```ts
+* await action({
+*   name: 'faasjs-demo',
+*   template: 'admin',
+* })
+* ```
+*/
+async function action(options = {}) {
+	const templateName = resolveTemplateName(options.template);
+	const answers = Object.assign(options, {});
+	if (!options.name || Validator.name(options.name) !== true) answers.name = await prompt({
+		type: "input",
+		name: "value",
+		message: "Project name",
+		initial: "faasjs",
+		validate: validateName
+	}).then((res) => res.value);
+	if (!answers.name) return;
+	scaffold(answers.name, {
+		name: answers.name,
+		secret: generateSessionSecret()
+	}, templateName);
+	execSync(`cd ${answers.name} && npm install`, { stdio: "inherit" });
+	execSync(`cd ${answers.name} && npm run test`, { stdio: "inherit" });
 }
+/**
+* Register the `create-faas-app` command on a Commander program.
+*
+* @param {Command} program - Commander program instance extended with the generator command.
+* @returns {void} No return value.
+* @example
+* ```ts
+* const program = new Command()
+*
+* registerCreateFaasApp(program)
+* ```
+*/
+function registerCreateFaasApp(program) {
+	program.description("Create a new FaasJS app").on("--help", () => console.log(`Examples:
+npx create-faas-app --name faasjs
+npx create-faas-app --name faasjs-admin --template admin
+npx create-faas-app --name faasjs-minimal --template minimal
 
-// src/index.ts
-var commander = new Command();
-commander.storeOptionsAsProperties(false).allowUnknownOption(true).version(package_default.version).name("create-faas-app").exitOverride();
-action_default(commander);
+Templates:
+admin: recommended React + Ant Design + PostgreSQL starter
+minimal: lighter React starter
+
+Available:
+${getTemplateNames().join(", ")}`)).option("--name <name>", "Project name").option("--template <template>", "Template name", "admin").action(action);
+}
+//#endregion
+//#region src/index.ts
+/**
+* # create-faas-app
+*
+* [![License: MIT](https://img.shields.io/npm/l/create-faas-app.svg)](https://github.com/faasjs/faasjs/blob/main/packages/create-faas-app/LICENSE)
+* [![NPM Version](https://img.shields.io/npm/v/create-faas-app.svg)](https://www.npmjs.com/package/create-faas-app)
+*
+* Quick way to create a FaasJS project.
+*
+* ## Usage
+*
+* ```bash
+* npx create-faas-app --name faasjs
+* npx create-faas-app --name faasjs-admin --template admin
+* npx create-faas-app --name faasjs-minimal --template minimal
+* ```
+*/
+const commander = new Command();
+commander.storeOptionsAsProperties(false).allowUnknownOption(true).version(version).name("create-faas-app").exitOverride();
+registerCreateFaasApp(commander);
+/**
+* Run the `create-faas-app` CLI with a provided argv array.
+*
+* @param {string[]} argv - CLI arguments forwarded to Commander.
+* @returns {Promise<Command>} Commander program instance after parsing.
+*
+* @example
+* ```ts
+* import { main } from 'create-faas-app'
+*
+* await main(['node', 'create-faas-app', '--help'])
+* ```
+*/
 async function main(argv) {
-  try {
-    await commander.parseAsync(argv);
-  } catch (error) {
-    console.error(error);
-  }
-  return commander;
+	try {
+		await commander.parseAsync(argv);
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && error.code === "commander.helpDisplayed") return commander;
+		console.error(error);
+	}
+	return commander;
 }
-
+//#endregion
 export { main };

package/index.mjs

@@ -2,4 +2,4 @@
 
 import { main } from './dist/index.mjs'
 
-main(process.argv)
+await main(process.argv)

package/package.json

@@ -1,44 +1,41 @@
 {
   "name": "create-faas-app",
-  "version": "v8.0.0-beta.3",
-  "license": "MIT",
-  "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "bin": {
-    "create-faas-app": "index.mjs"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
-    }
-  },
+  "version": "8.0.0-beta.30",
   "homepage": "https://faasjs.com/doc/create-faas-app",
+  "bugs": {
+    "url": "https://github.com/faasjs/faasjs/issues"
+  },
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/faasjs/faasjs.git",
     "directory": "packages/create-faas-app"
   },
-  "bugs": {
-    "url": "https://github.com/faasjs/faasjs/issues"
-  },
   "funding": "https://github.com/sponsors/faasjs",
-  "scripts": {
-    "build": "tsup-node src/index.ts --config ../../tsup.config.ts"
+  "bin": {
+    "create-faas-app": "index.mjs"
   },
   "files": [
     "dist",
-    "index.js"
+    "index.mjs",
+    "template"
   ],
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.mjs"
+    }
+  },
   "dependencies": {
     "commander": ">=14.0.0",
     "enquirer": "*"
   },
   "engines": {
-    "node": ">=24.0.0",
+    "node": ">=26.0.0",
     "npm": ">=11.0.0"
   }
 }

package/template/admin/.env.example

@@ -0,0 +1 @@
+DATABASE_URL=postgres://postgres:postgres@127.0.0.1:5432/{{name}}

package/template/admin/gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+coverage/
+.env

package/template/admin/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>FaasJS Ant Design App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/admin/migrations/20250101000000_create_users.ts

@@ -0,0 +1,12 @@
+import type { SchemaBuilder } from '@faasjs/pg'
+
+export function up(builder: SchemaBuilder) {
+  builder.createTable('users', (table) => {
+    table.specificType('id', 'serial').primary()
+    table.string('name')
+  })
+}
+
+export function down(builder: SchemaBuilder) {
+  builder.dropTable('users')
+}

package/template/admin/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "{{name}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vp dev",
+    "build": "vp build",
+    "start": "node --import @faasjs/node-utils/register-hooks server.ts",
+    "test": "vp test",
+    "db:new": "faasjs-pg new",
+    "db:status": "faasjs-pg status",
+    "db:migrate": "faasjs-pg migrate",
+    "db:up": "faasjs-pg up",
+    "db:down": "faasjs-pg down"
+  },
+  "devDependencies": {
+    "@faasjs/dev": "*",
+    "@faasjs/pg-dev": "*"
+  },
+  "peerDependencies": {
+    "@faasjs/ant-design": "*",
+    "@faasjs/core": "*",
+    "@faasjs/pg": "*"
+  },
+  "overrides": {
+    "vite": "npm:@voidzero-dev/vite-plus-core",
+    "vitest": "npm:@voidzero-dev/vite-plus-test"
+  },
+  "engines": {
+    "node": ">=26.0.0",
+    "npm": ">=11.0.0"
+  }
+}

package/template/admin/server.ts

@@ -0,0 +1,33 @@
+import { dirname, join } from 'node:path'
+import { loadEnvFile } from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+import { Server, staticHandler } from '@faasjs/core'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+try {
+  loadEnvFile()
+} catch (error) {
+  console.warn('[faasjs] Failed to load env file', error)
+}
+
+const publicHandler = staticHandler({
+  root: join(__dirname, 'public'),
+  notFound: false,
+})
+
+const distHandler = staticHandler({
+  root: join(__dirname, 'dist'),
+  notFound: 'index.html',
+})
+
+new Server(join(__dirname, 'src'), {
+  beforeHandle: async (req, res, ctx) => {
+    if (!req.url || req.method !== 'GET') return
+
+    await publicHandler(req, res, ctx)
+    await distHandler(req, res, ctx)
+  },
+}).listen()

package/template/admin/src/faas.yaml

@@ -0,0 +1,11 @@
+defaults:
+  server:
+    root: .
+    base: /
+  plugins:
+    http:
+      config:
+        cookie:
+          secure: false
+          session:
+            secret: '{{secret}}'

package/template/admin/src/main.tsx

@@ -0,0 +1,25 @@
+import { App } from '@faasjs/ant-design'
+import { createRoot } from 'react-dom/client'
+
+import HomePage from './pages/home'
+
+createRoot(document.getElementById('root') as HTMLElement).render(
+  <App
+    browserRouterProps={false}
+    configProviderProps={{
+      theme: {
+        token: {
+          borderRadius: 16,
+          colorPrimary: '#1677ff',
+        },
+      },
+    }}
+    faasConfigProviderProps={{
+      faasClientOptions: {
+        baseUrl: '/',
+      },
+    }}
+  >
+    <HomePage />
+  </App>,
+)