create-faas-app 8.0.0-beta.4 → 8.0.0-beta.41

package/README.md

@@ -1,18 +1,21 @@
 # create-faas-app
 
+# 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.
+Curated scaffolder for FaasJS projects. The `admin` template is the default
+React + Ant Design + PostgreSQL starter, and `minimal` provides a smaller
+React starter. After scaffolding, the CLI runs `npm install`, `npm run types`,
+and `npm run test` in the new project.
 
 ## Usage
 
 ```bash
-# use npm
 npx create-faas-app --name faasjs
-
-# use bun
-bunx create-faas-app --name faasjs
+npx create-faas-app --name faasjs-admin --template admin
+npx create-faas-app --name faasjs-minimal --template minimal
 ```
 
 ## Functions

package/dist/index.d.ts

@@ -1,24 +1,25 @@
-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.
+ * The array should use the same shape as `process.argv`, including executable
+ * and script slots. Parsing may prompt for a project name, create files, install
+ * dependencies, generate FaasJS action types, and run template tests. Commander
+ * help exits are swallowed and return the shared program; unexpected errors are
+ * printed with `console.error` and also return the program.
  *
- * ## Usage
+ * @param {string[]} argv - CLI arguments forwarded to Commander.
+ * @returns {Promise<Command>} Commander program instance after parsing.
  *
- * ```bash
- * # use npm
- * npx create-faas-app --name faasjs
+ * @example
+ * ```ts
+ * import { main } from 'create-faas-app'
  *
- * # 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,316 +1,167 @@
-import { Command } from 'commander';
-import { execSync } from 'child_process';
-import { mkdirSync, writeFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { prompt } from 'enquirer';
-
-// src/index.ts
-
-// package.json
-var package_default = {
-  version: "v8.0.0-beta.3"};
-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;
-  }
-};
-function writeFile(path, content) {
-  mkdirSync(dirname(path), {
-    recursive: true
-  });
-  writeFileSync(path, content);
-}
-function buildPackageJSON(name) {
-  return `${JSON.stringify(
-    {
-      name,
-      private: true,
-      type: "module",
-      version: "1.0.0",
-      scripts: {
-        dev: "faas dev",
-        build: "faas build",
-        start: "faas start",
-        check: "faas check",
-        test: "vitest run"
-      },
-      dependencies: {
-        "@faasjs/http": "*",
-        faasjs: "*",
-        react: "*",
-        "react-dom": "*",
-        zod: "*"
-      },
-      devDependencies: {
-        "@biomejs/biome": "*",
-        "@faasjs/lint": "*",
-        "@faasjs/test": "*",
-        "@faasjs/vite": "*",
-        "@types/node": "*",
-        "@types/react": "*",
-        "@types/react-dom": "*",
-        "@vitejs/plugin-react": "*",
-        jsdom: "*",
-        typescript: "*",
-        vite: "*",
-        vitest: "*"
-      }
-    },
-    null,
-    2
-  )}
-`;
+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.40";
+//#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();
 }
-function scaffold(rootPath) {
-  writeFile(
-    join(rootPath, ".gitignore"),
-    `node_modules/
-dist/
-coverage/
-`
-  );
-  writeFile(
-    join(rootPath, "biome.json"),
-    `{
-  "extends": ["@faasjs/lint/biome"]
+function resolveTemplateName(template = "admin") {
+	const templates = getTemplateNames();
+	if (templates.includes(template)) return template;
+	throw new Error(`Unknown template "${template}". Available templates: ${templates.join(", ")}`);
 }
-`
-  );
-  writeFile(
-    join(rootPath, "tsconfig.json"),
-    `{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "jsx": "react-jsx",
-    "strict": true,
-    "types": ["vitest/globals"]
-  },
-  "include": ["src", "vite.config.ts", "server.ts"]
+function renderTemplate(content, replacements) {
+	return Object.entries(replacements).reduce((result, [key, value]) => result.replaceAll(`{{${key}}}`, value), content);
 }
-`
-  );
-  writeFile(
-    join(rootPath, "index.html"),
-    `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>FaasJS App</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>
-`
-  );
-  writeFile(
-    join(rootPath, "vite.config.ts"),
-    `import { viteFaasJsServer } from '@faasjs/vite'
-import react from '@vitejs/plugin-react'
-import { defineConfig } from 'vite'
-
-export default defineConfig({
-  server: {
-    host: '0.0.0.0',
-  },
-  plugins: [react(), viteFaasJsServer()],
-})
-`
-  );
-  writeFile(
-    join(rootPath, "server.ts"),
-    `import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { Server, staticHandler } from '@faasjs/server'
-
-const __filename = fileURLToPath(import.meta.url)
-const __dirname = dirname(__filename)
-
-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()
-`
-  );
-  writeFile(
-    join(rootPath, "src", "faas.yaml"),
-    `defaults:
-  plugins:
-    http:
-      config:
-        cookie:
-          secure: false
-          session:
-            secret: secret
-development:
-testing:
-production:
-`
-  );
-  writeFile(
-    join(rootPath, "src", "main.tsx"),
-    `import { createRoot } from 'react-dom/client'
-import HomePage from './pages/home'
-
-createRoot(document.getElementById('root') as HTMLElement).render(<HomePage />)
-`
-  );
-  writeFile(
-    join(rootPath, "src", "pages", "home", "index.tsx"),
-    `import { useState } from 'react'
-
-type ApiResponse = {
-  ok: boolean
-  data: string
-  error: null | {
-    code?: string
-    message: string
-  }
+function generateSessionSecret() {
+	return randomBytes(32).toString("hex");
 }
-
-export default function HomePage() {
-  const [message, setMessage] = useState('Click button to call API')
-  const [loading, setLoading] = useState(false)
-
-  const fetchMessage = async () => {
-    setLoading(true)
-
-    try {
-      const data = await fetch('/home/api/hello', {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({ name: 'world' }),
-      }).then(res => res.json() as Promise<ApiResponse>)
-
-      if (data.ok) setMessage(data.data)
-      else setMessage(data.error?.message || 'Unknown error')
-    } catch (error: any) {
-      setMessage(error?.message || 'Unknown error')
-    } finally {
-      setLoading(false)
-    }
-  }
-
-  return (
-    <main style={{ margin: '5rem auto', maxWidth: 420, padding: 24 }}>
-      <h1>FaasJS Starter</h1>
-      <p>{message}</p>
-      <button type="button" onClick={fetchMessage} disabled={loading}>
-        {loading ? 'Loading...' : 'Call /home/api/hello'}
-      </button>
-    </main>
-  )
+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));
+	}
 }
-`
-  );
-  writeFile(
-    join(rootPath, "src", "pages", "home", "api", "hello.func.ts"),
-    `import { useHttpFunc } from '@faasjs/http'
-import { z } from 'zod'
-
-const schema = z
-  .object({
-    name: z.string().optional(),
-  })
-  .required()
-
-export const func = useHttpFunc<z.infer<typeof schema>>(() => {
-  return async ({ params }) => {
-    const parsed = schema.parse(params || {})
-
-    return {
-      ok: true,
-      data: \`Hello, \${parsed.name || 'FaasJS'}\`,
-      error: null,
-    }
-  }
-})
-`
-  );
-  writeFile(
-    join(rootPath, "src", "pages", "home", "api", "__tests__", "hello.test.ts"),
-    `import { test } from '@faasjs/test'
-import { func } from '../hello.func'
-
-describe('home/api/hello', () => {
-  it('should work', async () => {
-    const testFunc = test(func)
-
-    const { statusCode, data } = await testFunc.JSONhandler({ name: 'world' })
-
-    expect(statusCode).toEqual(200)
-    expect(data).toEqual({
-      ok: true,
-      data: 'Hello, world',
-      error: null,
-    })
-  })
-})
-`
-  );
+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 scaffolded, dependencies are installed, action types are generated, and tests pass.
+* @throws {Error} When the selected template is unknown.
+* @example
+* ```ts
+* await action({
+*   name: 'faasjs-demo',
+*   template: 'admin',
+* })
+* ```
+*/
 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;
-  const runtime = process.versions.bun ? "bun" : "npm";
-  mkdirSync(answers.name);
-  writeFileSync(
-    join(answers.name, "package.json"),
-    buildPackageJSON(answers.name)
-  );
-  scaffold(answers.name);
-  execSync(`cd ${answers.name} && ${runtime} install`, { stdio: "inherit" });
-  if (runtime === "bun") {
-    execSync(`cd ${answers.name} && bun test`, { stdio: "inherit" });
-  } else execSync(`cd ${answers.name} && npm run test`, { stdio: "inherit" });
+	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 types`, { stdio: "inherit" });
+	execSync(`cd ${answers.name} && npm run test`, { stdio: "inherit" });
 }
-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);
+/**
+* Register the `create-faas-app` command on a Commander program.
+*
+* @param {Command} program - Commander program instance to register the command on.
+* @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
+
+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);
 }
-
-// src/index.ts
-var commander = new Command();
-commander.storeOptionsAsProperties(false).allowUnknownOption(true).version(package_default.version).name("create-faas-app").exitOverride();
-action_default(commander);
+//#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)
+*
+* Curated scaffolder for FaasJS projects. The `admin` template is the default
+* React + Ant Design + PostgreSQL starter, and `minimal` provides a smaller
+* React starter. After scaffolding, the CLI runs `npm install`, `npm run types`,
+* and `npm run test` in the new 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
+* ```
+*
+* @packageDocumentation
+*/
+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.
+*
+* The array should use the same shape as `process.argv`, including executable
+* and script slots. Parsing may prompt for a project name, create files, install
+* dependencies, generate FaasJS action types, and run template tests. Commander
+* help exits are swallowed and return the shared program; unexpected errors are
+* printed with `console.error` and also return the program.
+*
+* @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.4",
-  "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.41",
   "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/package.json

@@ -0,0 +1,35 @@
+{
+  "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",
+    "types": "faas types",
+    "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"
+  }
+}