For agents

Use this page when generating or editing Forst (.ft) backend code. It is a usage cheat sheet, not a language spec. Fetch deeper pages only when you need one topic.

Mintlify AI endpoints

This site is Mintlify-hosted. Fetch these directly (no HTML):

Path	Use when
`/llms.txt`	Page index with descriptions. Regenerated on every deploy.
`/llms-full.txt`	Entire docs corpus in one Markdown file. Large. Prefer `/llms.txt` plus one topic page.
`/resources/llms.md`	Forst usage rules. Start here for coding tasks.
Any doc path + `.md`	One page as Markdown. Example: `/quickstart.md`.

Also available at /.well-known/llms.txt and /.well-known/llms-full.txt. Mintlify sends Link and X-Llms-Txt headers on every page so agents can discover the index. See Mintlify llms.txt docs.

What Forst is

Go-interoperable backend language. Source: .ft files. Output: Go you build with go build. Structural types carry validation constraints. TypeScript types come from the same tree via forst generate.

Install and run

Minimal install and compile commands:

npm install -D @forst/cli
npx forst version
npx forst run path/to/file.ft
npx forst build path/to/file.ft -root ./my-service
npx forst generate ./my-service
npx forst test ./...

CI: set FORST_BINARY to a preinstalled compiler path.

Typical layout

Common project tree for a Forst backend:

my-service/
├── go.mod
├── handlers/orders.ft
├── internal/legacy.go
├── ftconfig.json          # optional: generate / dev discovery
└── generated/types.d.ts   # often gitignored

Same-package .ft files merge when you pass -root. Go files and Forst files can live in one module.

Syntax you must use

Topic	Rule
Packages	Go style: `package handlers`, `import "fmt"`, module paths from `go.mod`.
Types	`type Name = { field: String, count: Int }`. Use `String`, `Int`, `Float`, `Bool`, `Array(T)`, `*T`, not `string`/`int` in Forst type positions.
Parameters	Always annotated: `func f(x: OrderInput): Result(String, Error)`.
Records at call sites	`placeOrder({ stockKeepingUnit: "A", quantity: 2 })`.
Constraints on fields	`String.Min(1).Max(64)`, `Int.Min(1).Max(99)`, `Array(String).NotEmpty()`. Compiler emits boundary checks.
Runtime checks	`ensure speed is LessThan(100) or TooFast({ ... })`.
Optional / errors	`ensure err is Nil() or err`. No `try`/`catch`, no `panic`/`recover`.
Map lookup	Returns `Result(V, Error)`. No comma-ok. `ensure avail is Ok()` then use `avail`.
Nominal errors	`error InsufficientStock { stockKeepingUnit: String, ... }`. Use with `ensure ... or InsufficientStock({...})`.
Result returns	`func f(): Result(String, Error) { return Ok("done") }`. Narrow with `ensure x is Ok()`.
Providers	`use logger: Logger` inside body. Wire at entry with `with { Logger: prodLogger {} } { handler(input) }`. Params = request data. Providers = host services.

Constraints reference (common)

Type	Examples
`String`	`.Min(n)`, `.Max(n)`, `.NotEmpty()`, `.HasPrefix("x")`, `.Contains("x")`
`Int` / `Float`	`.Min(n)`, `.Max(n)`, `.LessThan(n)`, `.GreaterThan(n)`
`Array(T)`	`.Min(n)`, `.Max(n)`, `.NotEmpty()`
`*T`	`.Nil()`, `.Present()`
`Result`	`.Ok()`, `.Err()` in `ensure`

Chain with dots. Same names work on type fields and in ensure.

CLI quick reference

Command	Purpose
`forst run FILE.ft`	Transpile, build, run
`forst build FILE.ft [-root DIR]`	Transpile and build only
`forst generate [DIR\|FILE]`	Emit TypeScript from Forst types
`forst dev -root DIR -port N`	HTTP dev server + discovery
`forst test ./...`	Run Forst tests
`forst fmt FILE.ft`	Format source
`forst dump --file FILE.ft --phase typechecker`	Debug compiler

Flags: -root merges same-package .ft files; -export-struct-fields emits exported struct fields with json tags for wire serialization; -log-level trace|debug|info|warn|error.

When writing code

Put validation on types at the HTTP boundary. Avoid manual if len(s) < 1 when a constraint fits.
Keep business failures as nominal error types or Result, not string errors.
Thread request payloads through parameters. Use use / with for loggers, clocks, repos (not context.Context values).
Import real Go packages when needed (fmt, your module). Generated Go must compile with go build.
After edits, run npx forst run or npx forst test on the touched package.

Do not invent

Avoid	Use instead
Zod / class-validator patterns	Constraints on Forst shapes
`try` / `catch`, thrown exceptions	`ensure`, `Result`, nominal `error`
`v, ok := m[k]`	`Result` + `ensure v is Ok()`
User-defined generics `<T>`	Built-ins only: `Array(T)`, `*T`, `Result(S,F)` (generics roadmap item)
DI frameworks, globals, service locators	`use` / `with` at entry points
Providers in sidecar / TS emit	Wire providers in Go host; export data types only

Task	Page
First project	Quickstart
Shapes and constraints	Shapes and constraints
`ensure` and narrowing	Ensure and narrowing
Errors and Result	Errors and Result
Providers	Providers (DI)
Go interop	Go interop — subslices, variadic spread into Go calls, fields/methods on Go values, sibling Forst packages
TypeScript emit	Generate client types
Examples in repo	github.com/forst-lang/forst/tree/main/examples/in

Project

Mintlify AI endpoints

What Forst is

Install and run

Typical layout

Syntax you must use

Constraints reference (common)

CLI quick reference

When writing code

Do not invent

Read more (single topic)

​Mintlify AI endpoints

​What Forst is

​Install and run

​Typical layout

​Syntax you must use

​Constraints reference (common)

​CLI quick reference

​When writing code

​Do not invent

​Read more (single topic)

Mintlify AI endpoints

What Forst is

Install and run

Typical layout

Syntax you must use

Constraints reference (common)

CLI quick reference

When writing code

Do not invent

Read more (single topic)