Foal bundles CLI, ORM, auth and GraphQL so you stop assembling npm packages

The pitch is integration, not a new programming model

Foal, also called FoalTS, is a Node.js framework for creating web applications, and the README frames its value almost entirely in terms of what you no longer have to do. The list runs from the CLI and testing tools through frontend utilities, scripts, advanced authentication, an ORM, deployment environments, GraphQL, a Swagger API and AWS utilities. The stated reason to care is that you no longer get lost on npm searching for packages and making them work together.

That is an unusual pitch for a web framework and it is the whole proposition. Most frameworks compete on routing, middleware composition or performance. Foal is arguing that the integration risk between a dozen half-maintained packages is the larger cost.

The counterweight in the README is a claim about syntax. The framework says complexity and unnecessary abstractions are put aside to keep the syntax intuitive and expressive, and that concise code is easier to maintain later. Whether that holds depends on how much of the bundled surface you actually use.

The language choice does real work here. The framework is written entirely in TypeScript, which brings optional static type checking plus recent ECMAScript features and can detect most simple errors during compilation. The README also points out the practical payoff, autocompletion and a documented API surface.

The topic list confirms the shape: dependency-injection, orm, typeorm, jwt, auth, rest, graphql, sdk, aws, express, security, cli.

Three commands to a running server

The first-run path is deliberately short. Install Node.js and npm, then scaffold:

npx @foal/cli createapp my-app
cd my-app
npm run dev

That starts the development server. The README says to open `http://localhost:3001` and look for the welcoming page, so port 3001 is the convention for a Foal development server rather than something you configure.

The `createapp` verb is worth noting because it implies the CLI covers more than scaffolding. The framework's own documentation site at foalts.org/docs is where the tutorial continues, and the repository ships a `demo-app` under `examples/` that shows a fuller application than the generated stub.

There is also a `docker-compose.yml` at the repository root for local dependencies, with four services. MySQL runs as `mysql:5.7.30` mapped to host port 3308 rather than 3306, with root password `admin` and a `test` user and database. PostgreSQL runs as `postgres:9.6.18` on 5432, MongoDB as `mongo:4.0.18` on 27017, and Redis as `redis:4.0.14` mapped to host port 6380 rather than 6379. The MySQL and Redis port offsets exist so the containers do not collide with a database already running on the host, and there is a commented `platform: linux/amd64` line for Apple silicon Macs.

The Compose file provides MySQL, PostgreSQL, MongoDB and Redis services for local use.

A monorepo with an explicit end-of-life schedule

The repository is a Lerna workspace. The root manifest is named `foal-srcs` rather than the framework itself, its workspaces globs are `packages/*`, `tests/*` and `examples/*`, and there is a `lerna.json` alongside. So the published package and the source tree are separate things, which is the normal arrangement for a project shipping many npm packages from one repository.

Top level entries map onto that: `packages/` holds the published packages, `tests/` the test suites, `examples/` the samples, `docs/` the documentation site sources with static assets under `docs/static/`, and `typings/` for type declarations. Two scripts exist at the root and both are lint: `lint` runs tslint against the tsconfig project, and `lint:fix` adds `--fix`. Development dependencies pin mocha, typescript around 5.9, tslint and lerna 9.

The most useful thing in the README for an adopter is the long-term support table, because it tells you what committing to a major line means:

| Release | Status | Active Start | Maintenance Start | End-of-life | Node versions | TS min version | | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | 5.x | Active | 2025-05-27 | | | 22, 24 | 5.5 | | 4.x | Maintenance | 2023-09-06 | 2025-05-27 | 2025-11-27 | 18, 20 | 4.9 | | 3.x | End-of-Life | 2022-10-28 | 2023-09-06 | 2024-03-06 | 16, 18 | 4.7 |

The definitions matter as much as the dates. Active means new features and bug fixes; maintenance means only critical fixes and security patches. So 4.x, which only got critical fixes after 2025-05-27, has been closed to features since then and went end-of-life on 2025-11-27.

The current release is v5.3.0 from 2026-07-09, and the last push was on 2026-07-29. The licence is MIT.

Testing is a stated priority, with a dated number

The development policy section says testing is put on a very high priority and that providing a reliable product is really important. The supporting figure is more than 2100 tests, and the README dates it: as of December 2020.

The staleness of that date is worth noticing rather than repeating. The claim is directionally useful, since a framework with a test suite that size is being maintained rather than demoed, but the number itself describes a state from years ago and should not be read as the current count. The test suites are still visible in the tree under `tests/`, and there is an `e2e_test.sh` script at the root for end to end runs, so the infrastructure is present even if the README has not been refreshed.

The second policy statement is about documentation: new features are described as useless if they are not well documented, and the framework asks you to open an issue if something looks missing or unclear. Documentation lives in `docs/` in this repository and at foalts.org as the published site.

Together those two policies are the framework's answer to the trust problem with a large bundled surface. A framework that ships its own ORM and auth is only acceptable if those pieces are tested and documented, and the repository is structured so you can check both claims yourself.

Where Foal is the wrong choice

The clearest case against is an existing application whose dependencies are already integrated. Adoption may require migration work, while the benefit is integration you may already have solved.

The Node requirement is a hard constraint on current versions. The 5.x line targets Node 22 and 24 with TypeScript 5.5 minimum, so a deployment platform still on Node 18 cannot run the active line at all, and the line that supports Node 18 went end-of-life on 2025-11-27. Teams pinned to older runtimes are effectively choosing 4.x with no further fixes.

The bundled surface is also a maintenance question. Every component the framework owns is a component that must track upstream changes, whether that is TypeORM, the JWT handling or the AWS utilities. A project using two of those features gains from the integration; a project using one of twenty gains mostly the weight.

Finally, TypeScript throughout means compile-time coupling. The README presents the language as a benefit, and for most teams it is, but the optional typing means type errors that matter to you may still require explicit annotations. That is a workflow adjustment, not a blocker, and it is worth naming before you commit.

Editorial conclusion

Teams building a REST or GraphQL service in TypeScript who would otherwise spend their first week wiring an ORM, an auth layer and a Swagger document together should evaluate Foal, since the integration is the product. Projects with an already integrated ORM and auth library should account for migration costs before adopting Foal. Before adopting, read the long-term support table: the 5.x line requires Node 22 or 24 and TypeScript 5.5 or newer, while 4.x went end-of-life on 2025-11-27.

Frequently asked questions

Official sources

1. FoalTS/foal on GitHub
2. License: MIT
3. Project website
4. README
5. Releases