faasjs-best-practices

Global Rules

Read
```
tsconfig.json
```
and any extended TypeScript config before choosing import paths.
Prefer FaasJS TypeScript loader support for direct Node execution, and keep local TypeScript imports extensionless instead of adding
```
.ts
```
or
```
.tsx
```
suffixes.
Prefer aliases already defined in TypeScript config over deep relative imports.
Keep short relative imports for nearby files in the same feature or directory.
Do not invent a new alias in code unless the corresponding
```
tsconfig.json
```
and runtime resolver are configured in the same change.
Keep changes minimal and task-scoped: no extra features, drive-by refactors, opportunistic cleanup, feature flags, transition shims, or speculative future-proofing.
Use zod for input validation at system boundaries (user input, external APIs, config files) where a schema defines the expected shape. Zod's
```
.safeParse()
```
provides type-safe validation with automatic type inference, eliminating handwritten validation functions and keeping types in sync.
Keep internal runtime type checks (
```
typeof
```
,
```
instanceof
```
,
```
=== null/undefined
```
) as-is. Replacing these with zod would increase code volume and add parsing overhead with no benefit—they are control-flow predicates, not input validation. The rule is: zod for external input contracts,
```
typeof
```
/
```
instanceof
```
for internal type interrogation.
Keep code direct: validate at system boundaries, fail fast on invalid internal data, and do not add silent fallbacks or impossible-case handling.
Avoid unnecessary intermediate variables: return or pass values directly instead of assigning to a single-use variable. An intermediate variable is justified when it documents a non-trivial condition, is referenced more than once, or breaks a long chain for readability.
Do not destructure function parameters; access them through the parameter object (e.g.,
```
input.xxx
```
or
```
props.xxx
```
) so the source of each value is immediately visible.
Do not create standalone type aliases or interfaces when TypeScript can infer the type from the expression, schema, or return statement; rely on inference first and add explicit types only at API boundaries, shared contracts, or where inference is ambiguous.
Extract helpers, hooks, components, or abstractions only when they are reused, create a real boundary, or simplify a large block; keep one-off code inline unless the body is over about 20 lines.
Document package public exports with JSDoc. Add JSDoc for shared app exports when the caller contract is not obvious. Do not add comments, docstrings, or type annotations to untouched code.
Delete confirmed-dead code directly instead of leaving temporary tricks such as
```
_unused
```
renames, type re-exports, or
```
// removed
```
markers.
Keep files under about 500 lines by splitting along real boundaries before they grow too large.
Treat
```
vp check --fix
```
and
```
vp test
```
as the default acceptance gates before handoff; if either cannot run, record the reason and the narrower validation that was completed.

Security And Boundary Checklist

Use this checklist whenever code handles users, tenants, permissions, secrets, external input, or persistent data.

Validate external input at the boundary with
```
defineApi
```
schemas, HTTP parsing, or the relevant integration adapter.
Check whether the API needs current-user, tenant, organization, project, role, or permission scoping before reading or mutating data.
Prefer project plugins for auth, tenant, request metadata, and other cross-cutting business context.
Return expected client errors with explicit HTTP status codes; reserve unexpected
```
500
```
failures for internal failures.
Do not log secrets, tokens, passwords, cookies, full sensitive payloads, or unredacted third-party responses.

Guidelines

Getting Started Guide: Covers the full setup, first feature walkthrough, project structure, key concepts, and daily workflow for new developers and new projects.
Curated Stack Guide: Covers the Rails-inspired default stack, official React/Ant Design/PostgreSQL path, plugin extension boundaries, auth/permission scope, and replacement rules.
Application Slices Guide: Covers vertical UI/API/database/test slices, recommended file layout, agent workflow, and why FaasJS avoids generator-heavy development.
Ant Design Guide: Covers
```
@faasjs/ant-design
```
page structure, routing, CRUD composition, feature-local APIs, and UI feedback patterns.
File Conventions: Covers where to place pages, components, hooks, and
```
.api.ts
```
files, plus when separate files are worth creating.
Code Comments Guide: Covers package public JSDoc expectations, caller contract conventions, when shared app exports need docs, and how to explain non-standard code without narrating it line by line.
Node Utils Guide: Covers Node-only helpers for env/config loading, function and plugin bootstrapping, module loading, and shared logging.
Project Config Guide: Covers how to keep
```
tsconfig.json
```
,
```
vite.config.ts
```
, and shared tooling config aligned with FaasJS defaults.
CLI and Tooling Guide: Covers the FaasJS CLI, Vite Plus commands, project scaffolding, migrations, type generation, testing, common errors, and environment variables.
Testing Guide: Covers shared testing principles such as choosing test level, keeping mock boundaries narrow, and avoiding unnecessary mocks.
React Guide: Covers React component and hook patterns in FaasJS, especially avoiding native
```
useEffect
```
and handling non-primitive dependencies safely.
React Data Fetching Guide: Covers when to use
```
useFaas
```
,
```
useFaasStream
```
,
```
faas
```
, or wrapper components, and how to handle loading, error, and retry states.
React Testing Guide: Covers request-related React testing with
```
setMock
```
, shared cleanup,
```
jsdom
```
, and common request-flow scenarios on top of the shared Testing Guide.
defineApi Guide: Covers building
```
.api.ts
```
endpoints with
```
defineApi
```
, inline schemas, typed
```
params
```
, error handling, and validation expectations.
Jobs Guide: Covers
```
.job.ts
```
files,
```
defineJob
```
,
```
enqueueJob
```
, workers, scheduler cron enqueueing, retries, idempotency, and testing.
Logger Guide: Covers when to reuse injected loggers versus creating
```
Logger
```
instances, how to choose log levels, and how to time slow operations.
Naming Convention Guide: Covers identifier naming (camelCase/PascalCase), file/directory naming, abbreviation rules, and cross-package naming consistency.
Plugins Guide: Covers the
```
Plugin
```
interface, lifecycle methods (
```
onMount
```
/
```
onInvoke
```
), injecting fields via
```
DefineApiInject
```
, config-driven loading through
```
faas.yaml
```
, manual registration in code, config merging precedence, and plugin testing.
CRUD Patterns Guide: Covers the complete CRUD vertical slice — shared items metadata, list/detail/create/update/delete patterns, testing, and agent efficiency tips for faster page generation.
Utils Guide: Covers portable helpers from
```
@faasjs/utils
```
for deep merging and converting text or JSON to and from streams.
PG Query Builder and Raw SQL Guide: Covers preferring
```
QueryBuilder
```
clauses, choosing raw SQL fallbacks deliberately, keeping client bootstrap consistent, and narrowing row shapes intentionally.
PG Table Types Guide: Covers declaration merging on
```
Tables
```
, concrete row shapes, and keeping query inference aligned with table definitions.
PG Schema and Migrations Guide: Covers timestamped migrations,
```
SchemaBuilder
```
,
```
TableBuilder
```
, and transactional schema changes.
PG Testing Guide: Covers
```
PgVitestPlugin()
```
, shared
```
DATABASE_URL
```
bootstrap, and pairing runtime assertions with
```
expectTypeOf(...)
```
.

faasjs-best-practices

NPX Install

Tags

SKILL.md Content

Global Rules

Security And Boundary Checklist

Guidelines