Fjall Docs — deploy AWS infrastructure into your own account

Overview

The Custom application type scaffolds a blank canvas. Instead of a preset tier, you pick a network configuration and add every compute, database and storage resource yourself with fjall add.

fjall create app --type custom

Pick Custom when no preset tier fits, when you are learning how Fjall composes resources, or when you want full control over the architecture.

--type custom pre-selects Custom in the starting-point picker, it does not skip the wizard. Pass --non-interactive to run without prompts.

Prerequisites

Requirement	Detail
Fjall CLI	Installed and authenticated (`fjall login`)
Node.js	Version 22.3 or later
AWS account	Connected via `fjall connect`

Interactive flow

Custom is the only application type that asks for a network configuration, and the only one that asks no database, service or Dockerfile questions.

? Choose your starting point?
    Standard      Production-ready · Multi-AZ, Fargate ECS, RDS
    Lightweight   Streamlined · Single-AZ, Instance-backed ECS, RDS
    Resilient     High-availability · Multi-AZ, Encrypted, Fargate ECS, Aurora
    Enterprise    Maximum capability · All features enabled, Aurora
    Tinkerer      Free experimental · Single-AZ, Free tier ECS, RDS
  > Custom        Blank canvas · Build your way

? Name your application? api

? Network configuration?
  > Standard      Production ready · 2 AZs, 1 NAT Gateway, KMS
    Lightweight   Cost effective · 2 AZs, shared NAT
    Resilient     High availability · 3 AZs, 3 NAT Gateways, CMK Keys
    Tinkerer      Free tier · 2 AZs, no NAT Gateway
    No network    Standalone resources · S3, CDN, Lambda, EventBridge

The review confirms a blank canvas before anything is written:

Network:     Standard
Resources:   Blank canvas (add resources after creation)

? Create application with these settings?

Two prompts appear conditionally:

? Use suggested container '<dir>'? (Y/n) when a monorepo container is inferred and --container was not passed. Answering no asks ? Container directory (leave empty for repo-root scaffold):.
? Select a deployment target: when the organisation config yields more than one target. A single target auto-selects.

Non-interactive creation

fjall create app --non-interactive --name api --type custom --network standard

--network accepts none, tinkerer, lightweight, standard, resilient and enterprise. The interactive picker offers all of these except enterprise, which is flag-only. none scaffolds network: false, which suits standalone S3, CDN, Lambda and EventBridge resources.

What gets scaffolded

The Custom type returns an empty resource plan, so the generator adds no database, no storage and no compute. infrastructure.ts is written with the application shell plus the network preset you picked (or no network at all). Every resource comes afterwards from fjall add.

Adding resources

fjall add writes a factory call into the application’s infrastructure.ts. The <type> positional, --app and --name are all required, so bare fjall add exits with a missing-argument error rather than opening a wizard.

# ECS service
fjall add compute --app api --name Api --type ecs --needsConnection false

# Aurora database
fjall add database --app api --name UserDb --type Aurora --databaseName users

# S3 bucket
fjall add storage --app api --name Uploads

Resource names match [a-zA-Z][a-zA-Z0-9]*. PascalCase is the convention, not a validation rule.

Resource types

Type	Adds
`compute`	ECS service, Lambda function or EC2 auto-scaling group
`database`	Aurora, RDS Instance, Global Aurora or ClickHouse
`storage`	S3 bucket
`messaging`	SQS queue
`cdn`	CloudFront distribution
`network`	VPC configuration
`pattern`	Payload CMS or static-site pattern
`vpc-peer`	Requester side of a VPC peering connection
`vpc-peer-accepter`	Accepter side of a VPC peering connection
`cross-plan-connection`	Connection to a resource in another application’s plan
`organisation`	Organisation-tier infrastructure statement
`buildkite`	Buildkite agent stack

Required property flags

A first add must carry every required key for that type. The codemod names any that are missing.

Type	Required flags
`compute`	`--type ecs\|lambda\|ec2` and `--needsConnection true\|false`
`database`	`--type Aurora\|Instance\|GlobalAurora\|ClickHouse` and `--databaseName <name>`
`cdn`	`--defaultOriginRef <resourceName>`
`storage`	None beyond `--name`

DynamoDB is not a Fjall database variant. fjall add database --type DynamoDB is rejected at validation. The four accepted values are Aurora, Instance, GlobalAurora and ClickHouse.

How property flags parse

Each --flag consumes the next token as its value. A trailing flag, a flag followed immediately by another flag, and a duplicate flag are all rejected. The bare tokens true, false and null decode to JSON literals, and a value starting with { or [ must parse as JSON.

Preset selectors

Flag	Applies to	Values
`--preset <name>`	`storage`	`standard`, `assets`, `upload`, `website`
`--tier <tier>`	`database`, `network`	`tinkerer`, `lightweight`, `standard`, `resilient`, `enterprise`

--preset and --tier cannot be combined. On database, --tier also needs --type, because each tier describes each database type differently.

fjall add storage --app api --name Assets --preset assets
fjall add database --app api --name AppDb --tier standard --type Instance --databaseName app

Pass --no-verify on add or modify to skip the post-write typecheck of the edited infrastructure.ts.

Building custom architectures

Each fjall add writes a factory call. The examples below show the generated code for common architectures, so you can see what each combination produces.

Microservices

import {
  App,
  ComputeFactory,
  DatabaseFactory,
} from "@fjall/components-infrastructure";
import { Code, FunctionUrlAuthType } from "aws-cdk-lib/aws-lambda";

const app = App.getApp("microservices");

// API gateway
const apiGateway = app.addCompute(
  ComputeFactory.build("ApiGateway", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("lambda/api-gateway"),
    handler: "index.handler",
    functionUrl: { authType: FunctionUrlAuthType.NONE },
  }),
);

// User service
const userDb = app.addDatabase(
  DatabaseFactory.build("UserDb", {
    type: "Aurora",
    databaseName: "users",
  }),
);

const userService = app.addCompute(
  ComputeFactory.build("UserService", {
    type: "ecs",
    services: [
      {
        name: "user",
        capacityProvider: "FARGATE",
        containers: [{ port: 3001 }],
      },
    ],
  }),
);

// Order service
const orderDb = app.addDatabase(
  DatabaseFactory.build("OrderDb", {
    type: "Instance",
    databaseName: "orders",
  }),
);

const orderService = app.addCompute(
  ComputeFactory.build("OrderService", {
    type: "ecs",
    services: [
      {
        name: "order",
        capacityProvider: "FARGATE",
        containers: [{ port: 3002 }],
      },
    ],
  }),
);

Event-driven

// Event processor
const eventProcessor = app.addCompute(
  ComputeFactory.build("EventProcessor", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("lambda/processor"),
    handler: "index.handler",
    memorySize: 1024,
    timeout: 300,
  }),
);

// Event store
const eventStore = app.addDatabase(
  DatabaseFactory.build("EventStore", {
    type: "Aurora",
    databaseName: "events",
  }),
);

// API layer
const api = app.addCompute(
  ComputeFactory.build("Api", {
    type: "ecs",
    services: [
      {
        name: "api",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
      },
    ],
  }),
);

memorySize is in MB and timeout is in seconds.

Batch processing

// Job queue database
const jobDb = app.addDatabase(
  DatabaseFactory.build("JobDb", {
    type: "Instance",
    databaseName: "jobqueue",
    instanceType: "t4g.micro", // Free tier eligible
  }),
);

// Batch processor
const batchProcessor = app.addCompute(
  ComputeFactory.build("BatchProcessor", {
    type: "ecs",
    services: [
      {
        name: "batch",
        capacityProvider: "FARGATE_SPOT", // Cost-optimised
        cpu: 2048,
        memoryLimitMiB: 4096,
        containers: [{ port: 8080 }],
      },
    ],
  }),
);

// Scheduler
const scheduler = app.addCompute(
  ComputeFactory.build("Scheduler", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("lambda/scheduler"),
    handler: "index.handler",
  }),
);

Hybrid

// Legacy system connector
const legacyConnector = app.addCompute(
  ComputeFactory.build("LegacyConnector", {
    type: "ec2",
    instanceType: "t4g.large",
  }),
);

// Modern API
const modernApi = app.addCompute(
  ComputeFactory.build("ModernApi", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("lambda/api"),
    handler: "index.handler",
    environment: {
      LEGACY_ENDPOINT: "10.0.1.100",
    },
  }),
);

// Shared database
const sharedDb = app.addDatabase(
  DatabaseFactory.build("SharedDb", {
    type: "Instance",
    databaseName: "shared",
  }),
);

Mix and match

Custom takes any combination of compute and database types.

// Mix compute types
const lambda = app.addCompute(
  ComputeFactory.build("Fn", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("lambda/fn"),
    handler: "index.handler",
  }),
);
const ecs = app.addCompute(
  ComputeFactory.build("Web", {
    type: "ecs",
    services: [
      {
        name: "app",
        capacityProvider: "FARGATE",
        containers: [{ port: 3000 }],
      },
    ],
  }),
);
const ec2 = app.addCompute(
  ComputeFactory.build("Box", { type: "ec2", instanceType: "t4g.micro" }),
);

// Mix database types
const aurora = app.addDatabase(
  DatabaseFactory.build("AuroraDb", { type: "Aurora", databaseName: "app" }),
);
const instance = app.addDatabase(
  DatabaseFactory.build("InstanceDb", {
    type: "Instance",
    databaseName: "app",
  }),
);
const freeTier = app.addDatabase(
  DatabaseFactory.build("FreeTierDb", {
    type: "Instance",
    databaseName: "app",
    instanceType: "t4g.micro",
  }),
);

A deployment: "code" Lambda always needs a code source. handler defaults to index.handler and runtime defaults to the current Node.js runtime.

When to use Custom

Choose Custom for:

Unique architectural requirements
Proof of concepts
Learning how Fjall composes resources
Maximum control over every resource

Choose a preset tier for:

Standard architectures (Standard or Resilient)
Quick deployment with opinionated defaults
Free experimentation (Tinkerer)

Tips

Plan the architecture before adding resources.
Start with one compute resource and add more incrementally.
Use PascalCase names that describe each resource (Api, UserDb, Uploads).
Match resource types to cost targets (t4g.micro instances and FARGATE_SPOT for low-cost workloads).
Run fjall list --app <name> after each add to see what is in infrastructure.ts.
Run fjall validate --deep before deploying to typecheck the edited file.

Common custom architectures

Architecture	Resources to add
API + worker	`compute` Api (ECS Fargate), `compute` Worker (ECS Fargate Spot), `database` SharedDb (Aurora)
Static site + API	`compute` Web (Lambda with function URL), `compute` Api (ECS Fargate), `database` AppDb (Instance)
Data pipeline	`compute` Ingest (Lambda), `compute` Process (ECS Fargate Spot), `database` Store (Aurora)

Next Steps

Add Resources

Add compute, databases and storage to an existing application.

Compute Factory

ECS, Lambda and EC2 options for compute resources.

Database Factory

Aurora, Instance, Global Aurora and ClickHouse variants.

Deploy Application

Ship your custom architecture to AWS.

Factory Patterns

Application Patterns

Architecture Patterns

Custom Pattern

Overview

Prerequisites

Interactive flow

Non-interactive creation

What gets scaffolded

Adding resources

Resource types

Required property flags

How property flags parse

Preset selectors

Building custom architectures

Microservices

Event-driven

Batch processing

Hybrid

Mix and match

When to use Custom

Tips

Common custom architectures

Next Steps

Add Resources

Compute Factory

Database Factory

Deploy Application

​Overview

​Prerequisites

​Interactive flow

​Non-interactive creation

​What gets scaffolded

​Adding resources

​Resource types

​Required property flags

​How property flags parse

​Preset selectors

​Building custom architectures

​Microservices

​Event-driven

​Batch processing

​Hybrid

​Mix and match

​When to use Custom

​Tips

​Common custom architectures

​Next Steps

Add Resources

Compute Factory

Database Factory

Deploy Application

Overview

Prerequisites

Interactive flow

Non-interactive creation

What gets scaffolded

Adding resources

Resource types

Required property flags

How property flags parse

Preset selectors

Building custom architectures

Microservices

Event-driven

Batch processing

Hybrid

Mix and match

When to use Custom

Tips

Common custom architectures

Next Steps