Building on Forge
Forge provides the backend primitives most applications need, with Postgres backends by default. Initialize one client from forge.toml and use Forge's actual API rather than inferring behavior from similar libraries.
Use the Forge version resolved by the project. Check its installed declarations when an exact signature or behavior matters; when editing Forge itself, use the repository source.
Read the relevant sections of the language reference:
- Node.js/TypeScript: references/node.md
- Python: references/python.md
- Rust: references/rust.md
- Go: references/go.md
Read these only when they apply:
- references/runtime-contract.md for configuration, errors, deployment, queues, scheduling, rate limits, pub/sub, presigning, flags, or maintenance.
- references/application-design.md for a nontrivial service, storage decision, authentication workflow, cross-system side effects, lifecycle, or test strategy.
Do not preload unrelated language references.
Pick the primitive deliberately
| Need |
Forge primitive |
Core constraint |
| Direct-key values, TTL state, counters, CAS |
kv |
Single-key operations; weakly consistent prefix scans |
| Durable background work and retry |
queue |
Requires an owning consumer; at-least-once |
| Ephemeral live fan-out |
pubsub |
At-most-once, live subscribers only |
| Files and presigned transfer URLs |
blob |
Application must enforce its ownership policy |
| Passwords, sessions, API keys, one-time tokens |
auth |
Application owns user and authorization records |
| Request throttling |
ratelimit |
Fail mode is a security/availability choice; not a business counter |
| Cron or delayed enqueue |
schedule |
Application must run scheduler ticks |
| Runtime settings and rollout flags |
config |
Cached; secrets remain environment-backed |
Core contracts
- Queue delivery is concurrent and at-least-once. Settle with the delivery receipt or leased job, not its stable id. Ack only after the logical effect succeeds.
- Scope idempotency to the logical effect. A job id is a useful base for redelivery, but fan-out may require
job-id:recipient-id, and duplicate jobs may require a stable domain operation id.
- Use managed workers where practical. Retain their promise/task/future, signal shutdown, and await completion.
- Run scheduler and maintenance loops when the selected features require them.
- Keep connection strings server-side and keep Forge's internal tables private.
- Presigning requires a non-empty secret without an empty fallback. Authorize access and verify the issued method, key, expiry, maximum bytes, and signature exactly.
Before finishing
- Verify method names, sync/async use, option order, defaults, and error behavior against the project's installed Forge version.
- Confirm the chosen primitive supports the required behavior.
- Confirm every produced queue has an identified consumer in the deployed system; test redelivery at the logical side-effect boundary.
- Verify lifecycle behavior in the application's real process topology.
- Test the Forge boundary and the failure modes that matter to the change.
1---2name: forge-idiomatic-developer3description: Load this whenever you are about to write, edit, or review code that uses the forgelib library in any language.4---5
6# Building on Forge
7
8Forge provides the backend primitives most applications need, with Postgres backends by default. Initialize one client from `forge.toml` and use Forge's actual API rather than inferring behavior from similar libraries.
9
10Use the Forge version resolved by the project. Check its installed declarations when an exact signature or behavior matters; when editing Forge itself, use the repository source.
11
12Read the relevant sections of the language reference:
13
14- Node.js/TypeScript: [references/node.md](references/node.md)
15- Python: [references/python.md](references/python.md)
16- Rust: [references/rust.md](references/rust.md)
17- Go: [references/go.md](references/go.md)
18
19Read these only when they apply:
20
21- [references/runtime-contract.md](references/runtime-contract.md) for configuration, errors, deployment, queues, scheduling, rate limits, pub/sub, presigning, flags, or maintenance.
22- [references/application-design.md](references/application-design.md) for a nontrivial service, storage decision, authentication workflow, cross-system side effects, lifecycle, or test strategy.
23Do not preload unrelated language references.
24
25## Pick the primitive deliberately
26
27| Need | Forge primitive | Core constraint |
28| --- | --- | --- |
29| Direct-key values, TTL state, counters, CAS | `kv` | Single-key operations; weakly consistent prefix scans |
30| Durable background work and retry | `queue` | Requires an owning consumer; at-least-once |
31| Ephemeral live fan-out | `pubsub` | At-most-once, live subscribers only |
32| Files and presigned transfer URLs | `blob` | Application must enforce its ownership policy |
33| Passwords, sessions, API keys, one-time tokens | `auth` | Application owns user and authorization records |
34| Request throttling | `ratelimit` | Fail mode is a security/availability choice; not a business counter |
35| Cron or delayed enqueue | `schedule` | Application must run scheduler ticks |
36| Runtime settings and rollout flags | `config` | Cached; secrets remain environment-backed |
37
38## Core contracts
39
40- Queue delivery is concurrent and at-least-once. Settle with the delivery receipt or leased job, not its stable id. Ack only after the logical effect succeeds.
41- Scope idempotency to the logical effect. A job id is a useful base for redelivery, but fan-out may require `job-id:recipient-id`, and duplicate jobs may require a stable domain operation id.
42- Use managed workers where practical. Retain their promise/task/future, signal shutdown, and await completion.
43- Run scheduler and maintenance loops when the selected features require them.
44- Keep connection strings server-side and keep Forge's internal tables private.
45- Presigning requires a non-empty secret without an empty fallback. Authorize access and verify the issued method, key, expiry, maximum bytes, and signature exactly.
46
47## Before finishing
48
49- Verify method names, sync/async use, option order, defaults, and error behavior against the project's installed Forge version.
50- Confirm the chosen primitive supports the required behavior.
51- Confirm every produced queue has an identified consumer in the deployed system; test redelivery at the logical side-effect boundary.
52- Verify lifecycle behavior in the application's real process topology.
53- Test the Forge boundary and the failure modes that matter to the change.
isala404