Best Practices

Use these guides and specifications as the current public guidance for building with FaasJS.

FaasJS is a Rails-inspired, curated full-stack TypeScript framework for database-driven React business applications. The main path is React, Ant Design, typed APIs, PostgreSQL, validation, testing, plugins, and stable project conventions.

Main Path

Read these guides in order when starting a new feature or asking an AI coding agent to build one:

  1. Curated Stack Guide
  2. Project Config Guide
  3. File Conventions
  4. defineApi Guide
  5. React Data Fetching Guide
  6. Ant Design Guide
  7. PG Query Builder and Raw SQL Guide
  8. PG Schema and Migrations Guide
  9. PG Testing Guide
  10. Application Slices Guide

FaasJS favors complete application slices over generator-heavy workflows. A slice should keep UI, API, validation, database changes, and tests easy to find, review, and modify together.

Guidelines

  • Curated Stack Guide: Use this guide when choosing defaults, reviewing architecture, or asking an AI coding agent to build a FaasJS feature.
  • Application Slices Guide: Use this guide when adding a business feature to a FaasJS app or asking an AI coding agent to build one.
  • Project Config Guide: Use for tsconfig.json, vite.config.ts, and shared workspace tooling config in FaasJS projects.
  • File Conventions: Use this guide when creating or reviewing feature folders, React components, hooks, FaasJS backend route files, background job files, or feature-owned CLI tools.
  • Code Comments Guide: Use for source JSDoc, helper comments, and short intent notes in FaasJS apps or packages. Docs pages and tutorials may use page-specific structure instead.
  • defineApi Guide: When implementing or reviewing a FaasJS HTTP endpoint, default to defineApi.
  • Jobs Guide: Use this guide when defining .job.ts background jobs, enqueueing asynchronous work, or running FaasJS workers and schedulers.
  • Testing Guide: Use this guide when writing or reviewing tests in FaasJS projects.
  • React Guide: Use for React feature UI, components, hooks, dependency handling, derived state, and @faasjs/react helpers in FaasJS projects.
  • React Data Fetching Guide: Use for FaasJS requests in React: useFaas, useFaasStream, faas, FaasDataWrapper, withFaasData, client setup, loading, error, retry, debounce, polling, and reload behavior.
  • React Testing Guide: Use this guide when writing or reviewing React tests that exercise FaasJS request flows in hooks or components.
  • Ant Design Guide: Use when building or reviewing @faasjs/ant-design feature UI, CRUD surfaces, routes, app feedback, modals, and drawers.
  • Node Utils Guide: Use this guide when you need Node.js-only helpers for FaasJS runtime bootstrapping, local tooling, config resolution, or logging.
  • Logger Guide: Use this guide when working with Logger instances, log levels, timing, and transport configuration in FaasJS apps.
  • Utils Guide: Use this guide when you need lightweight helper functions from @faasjs/utils in app code, tests, or runtime adapters.
  • PG Query Builder and Raw SQL Guide: Use this guide when building SQL queries with @faasjs/pg in FaasJS apps.
  • PG Table Types Guide: Use this guide when defining or updating table types with @faasjs/pg declaration merging.
  • PG Schema and Migrations Guide: Use this guide when creating or reviewing database schema changes, migrations, or table structures with @faasjs/pg.
  • PG Testing Guide: Use this guide when writing or reviewing tests that use @faasjs/pg or @faasjs/pg-dev in FaasJS projects.
  • CLI and Tooling Guide: Use this guide when running CLI commands, troubleshooting command errors, or choosing the right tool for the task. It is a quick-reference for the FaasJS toolchain to reduce command-execution mistakes.
  • CRUD Patterns Guide: Use this guide when implementing or reviewing a standard CRUD feature — list, detail, create, update, delete — in a FaasJS application. It covers the full vertical slice from API endpoints to feature UI.
  • faas.yaml Configuration Specification: faas.yaml is the runtime configuration entry used by FaasJS config loading, local dev server resolution, and type generation.
  • Getting Started Guide: Use this guide when starting a new FaasJS project or onboarding a new developer to an existing FaasJS codebase. It walks through the full setup, first feature, and daily workflow so both humans and AI coding agents can get productive quickly.
  • HTTP Plugin Guide: Use this guide when working with cookies, sessions, response helpers, or HTTP plugin configuration in FaasJS APIs.
  • HTTP Protocol Specification: FaasJS request/response guidance is spread across multiple locations. This spec defines a single internal baseline for transport behavior.
  • JSON Guide: Use this guide when you need to parse, serialize, or normalize JSON data in FaasJS projects using the helpers from @faasjs/utils.
  • Middleware Guide: Use this guide when you need to serve static files in a FaasJS application.
  • Naming Convention: Use this guide when naming identifiers — functions, variables, types, files, and directories.
  • Plugin Specification: FaasJS supports plugins in two complementary layers:
  • Plugins Guide: Use this guide when adding cross-cutting behavior that should run before or after every request — such as auth, tenant resolution, request logging, rate limiting, or feature flags. Plugins hook into the FaasJS request lifecycle and can inject typed fields into defineApi and defineJob handlers.
  • Routing Mapping Specification: Related references:
  • Validation Guide: Use this guide when you need to validate data in FaasJS projects — whether at system boundaries, in custom Node-side code, or in portable helpers.
  • YAML Guide: Use this guide when you need to parse YAML text directly in FaasJS projects using parseYaml from @faasjs/utils.

API Docs