create-faas-app 8.0.0-beta.35 → 8.0.0-beta.37

package/README.md

@@ -1,77 +1,23 @@
 # create-faas-app
 
-Create a new FaasJS app from a curated starter template.
-
-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.
-
-## Quick Start
-
-```bash
-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
+# create-faas-app
 
-This is the best starting point for admin panels, internal tools, SaaS dashboards, and other database-driven business applications.
+[![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)
 
-### `minimal`
+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.
 
-Use `minimal` when you want a smaller React starter without the database and Ant Design stack.
+## Usage
 
 ```bash
-npx create-faas-app --name my-minimal-app --template minimal
+npx create-faas-app --name faasjs
+npx create-faas-app --name faasjs-admin --template admin
+npx create-faas-app --name faasjs-minimal --template minimal
 ```
 
-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
+## Functions
 
 - [main](functions/main.md)

package/dist/index.d.ts

@@ -4,6 +4,12 @@ import { Command } from "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.
  *

package/dist/index.mjs

@@ -6,7 +6,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import enquirer from "enquirer";
 //#region package.json
-var version = "8.0.0-beta.34";
+var version = "8.0.0-beta.36";
 //#endregion
 //#region src/action/index.ts
 const prompt = enquirer.prompt;
@@ -56,7 +56,7 @@ function scaffold(rootPath, replacements, templateName) {
 * @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, and tests pass.
+* @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
@@ -82,6 +82,7 @@ async function action(options = {}) {
 		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" });
 }
 /**
@@ -116,7 +117,10 @@ ${getTemplateNames().join(", ")}`)).option("--name <name>", "Project name").opti
 * [![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
 *
@@ -125,6 +129,8 @@ ${getTemplateNames().join(", ")}`)).option("--name <name>", "Project name").opti
 * 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();
@@ -132,6 +138,12 @@ 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.
 *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-faas-app",
-  "version": "8.0.0-beta.35",
+  "version": "8.0.0-beta.37",
   "homepage": "https://faasjs.com/doc/create-faas-app",
   "bugs": {
     "url": "https://github.com/faasjs/faasjs/issues"

package/template/admin/package.json

@@ -7,6 +7,7 @@
     "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",

package/template/admin/src/.faasjs/types.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Generated by @faasjs/dev.
+ *
+ * Do not edit this file manually.
+ */
+import type { InferFaasAction } from '@faasjs/types'
+
+declare module '@faasjs/types' {
+  interface FaasActions {
+    "features/auth/api/me": InferFaasAction<typeof import("../features/auth/api/me.api")>
+    "features/users/api/create": InferFaasAction<typeof import("../features/users/api/create.api")>
+    "features/users/api/detail": InferFaasAction<typeof import("../features/users/api/detail.api")>
+    "features/users/api/list": InferFaasAction<typeof import("../features/users/api/list.api")>
+    "features/users/api/update": InferFaasAction<typeof import("../features/users/api/update.api")>
+  }
+}

package/template/admin/src/{pages/home/api/auth → features/auth/api}/__tests__/me.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, it } from 'vitest'
 
 import api from '../me.api'
 
-describe('pages/home/api/auth/me', () => {
+describe('features/auth/api/me', () => {
   it('returns the current user from the auth plugin demo', async () => {
     const handler = testApi(api)
 

package/template/admin/src/{pages/home/api/auth → features/auth/api}/me.api.ts

@@ -1,7 +1,7 @@
 import { defineApi, HttpError } from '@faasjs/core'
 import { z } from '@faasjs/utils'
 
-import { AuthPlugin } from '../../../../plugins/auth'
+import { AuthPlugin } from '../../../plugins/auth'
 
 const api = defineApi({
   schema: z.object({}).strict(),

package/template/admin/src/{pages/home/api/users → features/users/api}/__tests__/create.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from 'vitest'
 
 import api from '../create.api'
 
-describe('pages/home/api/users/create', () => {
+describe('features/users/api/create', () => {
   it('creates a user with the shared pg bootstrap', async () => {
     const handler = testApi(api)
 

package/template/admin/src/{pages/home/api/users → features/users/api}/__tests__/detail.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from 'vitest'
 
 import api from '../detail.api'
 
-describe('pages/home/api/users/detail', () => {
+describe('features/users/api/detail', () => {
   it('returns one user', async () => {
     const client = await getClient()
     const [created] = await client.query('users').insert(

package/template/admin/src/{pages/home/api/users → features/users/api}/__tests__/list.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from 'vitest'
 
 import api from '../list.api'
 
-describe('pages/home/api/users/list', () => {
+describe('features/users/api/list', () => {
   it('lists users with total count', async () => {
     const client = await getClient()
 

package/template/admin/src/{pages/home/api/users → features/users/api}/__tests__/update.test.ts

@@ -4,7 +4,7 @@ import { describe, expect, it } from 'vitest'
 
 import api from '../update.api'
 
-describe('pages/home/api/users/update', () => {
+describe('features/users/api/update', () => {
   it('updates one user', async () => {
     const client = await getClient()
     const [created] = await client.query('users').insert(

package/template/admin/src/{pages/home → features/users}/index.tsx

@@ -1,35 +1,10 @@
-declare module '@faasjs/types' {
-  interface FaasActions {
-    '/pages/home/api/users/list': {
-      Params: { limit: number }
-      Data: { total?: number; rows?: { id: number; name: string }[] }
-    }
-    '/pages/home/api/users/create': {
-      Params: { name?: string | undefined }
-      Data: { message?: string; total?: number; user?: { id: number; name: string } }
-    }
-    '/pages/home/api/users/update': {
-      Params: { id: number; name: string }
-      Data: { message?: string; user?: { id: number; name: string } }
-    }
-    '/pages/home/api/users/detail': {
-      Params: { id: number }
-      Data: { user?: { id: number; name: string } }
-    }
-    '/pages/home/api/auth/me': {
-      Params: Record<string, never>
-      Data: { current_user?: { id: number; name: string; role: string } }
-    }
-  }
-}
-
 import { faas, useApp } from '@faasjs/ant-design'
 import { useFaas } from '@faasjs/react'
 import { toErrorMessage } from '@faasjs/utils'
 import { Button, Card, Input, Space, Table, Typography } from 'antd'
 import { useState } from 'react'
 
-export default function HomePage() {
+export default function UsersPage() {
   const app = useApp()
   const [name, setName] = useState('FaasJS')
   const [messageText, setMessageText] = useState('Create your first user through the FaasJS API')
@@ -38,7 +13,7 @@ export default function HomePage() {
     data: listData,
     loading: listLoading,
     reload,
-  } = useFaas('/pages/home/api/users/list', { limit: 10 })
+  } = useFaas('features/users/api/list', { limit: 10 })
 
   const rows = listData?.rows || []
 
@@ -46,7 +21,7 @@ export default function HomePage() {
   const callApi = async () => {
     setCreating(true)
     try {
-      const response = await faas('/pages/home/api/users/create', {
+      const response = await faas('features/users/api/create', {
         name: name.trim() || undefined,
       })
       const result = response.data
@@ -75,7 +50,7 @@ export default function HomePage() {
     setAuthLoading(true)
     try {
       const response = await faas(
-        '/pages/home/api/auth/me',
+        'features/auth/api/me',
         {},
         {
           headers: { authorization: 'Bearer demo-admin' },
@@ -137,7 +112,7 @@ export default function HomePage() {
               Load users slice
             </Button>
             <Button type="primary" loading={creating} onClick={callApi}>
-              Create /pages/home/api/users/create
+              Create features/users/api/create
             </Button>
             <Button loading={authLoading} onClick={callAuthDemo}>
               Call auth plugin demo

package/template/admin/src/main.tsx

@@ -1,7 +1,7 @@
 import { App } from '@faasjs/ant-design'
 import { createRoot } from 'react-dom/client'
 
-import HomePage from './pages/home'
+import UsersPage from './features/users'
 
 createRoot(document.getElementById('root') as HTMLElement).render(
   <App
@@ -20,6 +20,6 @@ createRoot(document.getElementById('root') as HTMLElement).render(
       },
     }}
   >
-    <HomePage />
+    <UsersPage />
   </App>,
 )

package/template/admin/tsconfig.json

@@ -1,4 +1,4 @@
 {
   "extends": "@faasjs/types/tsconfig/build.json",
-  "include": ["src", "vite.config.ts", "server.ts"]
+  "include": ["src", "src/.faasjs/types.d.ts", "vite.config.ts", "server.ts"]
 }

package/template/minimal/package.json

@@ -7,6 +7,7 @@
     "dev": "vp dev",
     "build": "vp build",
     "start": "node --import @faasjs/node-utils/register-hooks server.ts",
+    "types": "faas types",
     "test": "vp test"
   },
   "devDependencies": {

package/template/minimal/src/.faasjs/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Generated by @faasjs/dev.
+ *
+ * Do not edit this file manually.
+ */
+import type { InferFaasAction } from '@faasjs/types'
+
+declare module '@faasjs/types' {
+  interface FaasActions {
+    "features/home/api/hello": InferFaasAction<typeof import("../features/home/api/hello.api")>
+  }
+}

package/template/minimal/src/{pages → features}/home/api/__tests__/hello.test.ts

@@ -3,7 +3,7 @@ import { describe, it, expect } from 'vitest'
 
 import api from '../hello.api'
 
-describe('pages/home/api/hello', () => {
+describe('features/home/api/hello', () => {
   it('should work', async () => {
     const handler = testApi(api)
 

package/template/minimal/src/{pages → features}/home/index.tsx

@@ -1,12 +1,3 @@
-declare module '@faasjs/types' {
-  interface FaasActions {
-    '/pages/home/api/hello': {
-      Params: { name?: string | undefined }
-      Data: { message?: string }
-    }
-  }
-}
-
 import { useState } from 'react'
 
 import { useFaas } from '../../react-client'
@@ -15,7 +6,7 @@ export default function HomePage() {
   const [name, setName] = useState('FaasJS')
 
   const { data, loading, reload } = useFaas(
-    '/pages/home/api/hello',
+    'features/home/api/hello',
     { name: name.trim() || undefined },
     { skip: true },
   )
@@ -39,7 +30,7 @@ export default function HomePage() {
         onClick={() => reload({ name: name.trim() || undefined })}
         disabled={loading}
       >
-        {loading ? 'Loading...' : 'Call /pages/home/api/hello'}
+        {loading ? 'Loading...' : 'Call features/home/api/hello'}
       </button>
     </main>
   )

package/template/minimal/src/main.tsx

@@ -1,5 +1,5 @@
 import { createRoot } from 'react-dom/client'
 
-import HomePage from './pages/home'
+import HomePage from './features/home'
 
 createRoot(document.getElementById('root') as HTMLElement).render(<HomePage />)

package/template/minimal/tsconfig.json

@@ -1,4 +1,4 @@
 {
   "extends": "@faasjs/types/tsconfig/build.json",
-  "include": ["src", "vite.config.ts", "server.ts"]
+  "include": ["src", "src/.faasjs/types.d.ts", "vite.config.ts", "server.ts"]
 }