No native modules, pod installs, or Android linking steps are required. All packages are pure Node.js/TypeScript.

Project setup

1. Clone or copy the contents of source/ into a directory such as vendor/foal-packages/ within your project root, preserving subdirectory structure.

2. Configure tsconfig.json path aliases so local imports resolve correctly:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "moduleResolution": "node",
    "target": "ES2020",
    "module": "commonjs",
    "paths": {
      "@foal/aws-s3": ["./vendor/foal-packages/aws-s3/src/index.ts"],
      "@foal/cli": ["./vendor/foal-packages/cli/src/index.ts"],
      "@foal/core": ["./vendor/foal-packages/core/src/index.ts"]
    }
  }
}

3. emitDecoratorMetadata and experimentalDecorators are mandatory for FoalTS dependency injection and hooks to function.

4. Add the required environment variables for AWS S3 storage (if using aws-s3):

# .env
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_DEFAULT_REGION=us-east-1
SETTINGS_DISK_S3_BUCKET=your-bucket-name

5. Add import 'reflect-metadata'; as the very first line of your application entry point before any FoalTS imports.

6. Build each package from source if needed:

cd vendor/foal-packages/aws-s3 && npm install && npm run build

Public API

S3Disk

import { S3Disk } from './aws-s3/src/index';
// Also exported as:
import { S3Disk as ConcreteDisk } from './aws-s3/src/index';

S3Disk is a FoalTS Disk service implementation backed by AWS S3. Inject it wherever the abstract Disk token is expected to provide cloud file storage. The alias ConcreteDisk is used internally by the framework's dependency injection to bind the concrete implementation to the abstract Disk interface. Use S3Disk directly in tests or when you need an explicit S3 reference.

ConnectAngularCommandService

import { ConnectAngularCommandService } from './cli/src/commands/connectors';

A CLI command service that configures a FoalTS backend project to serve an Angular frontend by adjusting build output paths and static file serving. Instantiate and call its run method from a CLI entry point or custom script when integrating Angular into an existing FoalTS project.

CreateAppCommandService

import { CreateAppCommandService } from './cli/src/commands/generators';

Scaffolds a complete new FoalTS application directory with standard folder structure, default configuration files, and boilerplate source. Use this programmatically or via the CLI when bootstrapping a new project rather than manually copying templates.

RunScriptCommandService

import { RunScriptCommandService } from './cli/src/commands';

Resolves and executes a named FoalTS script from the project's src/scripts/ directory with full dependency injection context. Use it when you need to run database seeders, migration helpers, or maintenance tasks within the application container.

Working examples

Scenario - Scaffold a new FoalTS app programmatically

You want to create a new application directory from code rather than the CLI binary.

import 'reflect-metadata';
import { CreateAppCommandService } from './vendor/foal-packages/cli/src/commands/generators';

async function bootstrap() {
  const service = new CreateAppCommandService();
  await service.run({ name: 'my-api' });
  console.log('App scaffolded in ./my-api');
}

bootstrap().catch(console.error);

Scenario - Use S3Disk for file uploads in a controller

Wire S3Disk into a FoalTS controller to store uploaded files directly to S3.

import 'reflect-metadata';
import { S3Disk } from './vendor/foal-packages/aws-s3/src/index';

// Assuming @foal/core is installed from npm or built from source/core
import { dependency, HttpResponseOK, Post, Context } from '@foal/core';
import { ParseAndValidateFiles } from '@foal/storage';

export class UploadController {
  @dependency
  disk: S3Disk;

  @Post('/upload')
  @ParseAndValidateFiles({ file: { required: true, saveTo: 'avatars' } })
  async upload(ctx: Context) {
    const { path } = ctx.files.get('file')[0];
    return new HttpResponseOK({ path });
  }
}

// Register S3Disk as the concrete Disk in your app module:
// ConcreteClass bindings are resolved automatically when S3Disk
// is exported as ConcreteDisk from the aws-s3 package.

Scenario - Connect a React frontend to a FoalTS backend

Use ConnectReactCommandService to configure the project so the React build output is served by the FoalTS static file middleware.

import 'reflect-metadata';
import {
  ConnectReactCommandService,
  ConnectAngularCommandService,
  ConnectVueCommandService,
} from './vendor/foal-packages/cli/src/commands/connectors';

async function connectFrontend(framework: 'react' | 'angular' | 'vue') {
  const services = {
    react: new ConnectReactCommandService(),
    angular: new ConnectAngularCommandService(),
    vue: new ConnectVueCommandService(),
  };

  await services[framework].run({});
  console.log(`${framework} frontend connected to FoalTS.`);
}

connectFrontend('react').catch(console.error);

Scenario - Run a maintenance script within the app container

Execute a seeder script that has access to injected services and the database connection.

import 'reflect-metadata';
import { RunScriptCommandService } from './vendor/foal-packages/cli/src/commands';

async function seed() {
  const runner = new RunScriptCommandService();
  // Runs src/scripts/seed.ts with full DI context
  await runner.run({ name: 'seed' });
}

seed().catch(console.error);

File walkthrough

• aws-s3/ - Self-contained package exporting S3Disk; depends on @aws-sdk/client-s3 and the abstract Disk interface from @foal/storage.
• cli/ - CLI entry point (cli.ts) and all command services; templates/ holds file generation templates used by generator commands.
• core/ - Central package: HTTP pipeline, decorators, DI container, hooks API, session handling.
• graphiql/ - Mounts the GraphiQL browser IDE at a configurable route for development introspection.
• graphql/ - Resolves GraphQL operations within FoalTS request lifecycle using a schema and resolvers you provide.
• jwks-rsa/ - Fetches public keys from a JWKS endpoint; used as a key provider plugin for @foal/jwt.
• jwt/ - JWTRequired and JWTOptional hooks for route-level JWT authentication and payload extraction.
• mongodb/ - MongoDB-backed concrete implementations of FoalTS session and token stores.
• password/ - hashPassword and verifyPassword utilities wrapping bcrypt for safe credential storage.
• redis/ - Redis-backed session store and cache concrete implementations using ioredis.
• social/ - Abstract AbstractProvider and concrete Google/GitHub/Facebook/LinkedIn OAuth2 providers.
• socket.io/ - Wraps Socket.IO server into the FoalTS service container with hook and event-handler support.
• storage/ - Abstract Disk interface, LocalDisk implementation, and file-parsing middleware.
• swagger/ - Reads @ApiInfo, @ApiOperation, and related decorators to generate and serve an OpenAPI 3 spec.
• typeorm/ - TypeORMStore session backend, fetchUserWithPermissions authenticator, and entity utilities.
• typestack/ - @ValidateBody, @ValidateQuery hooks backed by class-validator and class-transformer.

Common pitfalls and fixes

• Missing emitDecoratorMetadata: FoalTS DI and hooks silently fail without it. Set "emitDecoratorMetadata": true and "experimentalDecorators": true in tsconfig.json.
• reflect-metadata imported too late: Must be the absolute first import in your entry file before any FoalTS module; ordering matters because side-effects register metadata globally.
• AWS credentials not found: S3Disk reads credentials from environment or ~/.aws/credentials; ensure AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and SETTINGS_DISK_S3_BUCKET are set before the process starts.
• Path alias not resolving in built output: tsconfig paths apply only to ts-node / IDE; add tsconfig-paths to production builds: node -r tsconfig-paths/register dist/index.js.
• CLI templates missing at runtime: The cli/templates/ directory must be present relative to the compiled cli/src/ output; copy it alongside the build or set FOAL_CLI_TEMPLATES_PATH if the framework supports it.
• ESM/CJS interop with jsonwebtoken or ioredis: These packages are CJS; ensure "module": "commonjs" in tsconfig.json or use a bundler interop shim to avoid ERR_REQUIRE_ESM.

Vibe-coding prompt template

I have the FoalTS framework monorepo source in `source/` and the integration
guide in `USAGE.md`. The upstream package name is `foal-srcs`.

Please help me integrate FoalTS into my existing Node.js/TypeScript project
step by step:

1. Read USAGE.md fully before writing any code.
2. Copy the relevant packages from `source/` (e.g., `source/core/`,
   `source/jwt/`, `source/typeorm/`) into `vendor/foal-packages/`.
3. Update my `tsconfig.json` with the path aliases shown in USAGE.md,
   ensuring `emitDecoratorMetadata` and `experimentalDecorators` are enabled.
4. Add `import 'reflect-metadata'` as the first line of my entry file.
5. Wire the packages I need (list them here: e.g., JWT auth, S3 storage,
   TypeORM session) using only the real exports documented in USAGE.md.
6. Show me a working controller example using `S3Disk` for file upload and
   `JWTRequired` for route protection, importing from the local `vendor/`
   paths.
7. Highlight any environment variables I must set before running.

Do not invent API names. Only use symbols visible in USAGE.md.

License and credit

FoalTS is released under the MIT License (see source/aws-s3/LICENSE and per-package LICENSE files). Copyright 2017-2025 Loïc Poullain.

Upstream repository and documentation: https://github.com/FoalTS/foal and https://foalts.org.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

NestJS Progressive Node.js Backend Framework

Automation, Utilities & Developer Tools

Free