Fjall Docs — deploy AWS infrastructure into your own account

Prerequisites

Complete these first:

Create Application
A created Fjall application, with commands run from the project root

Overview

fjall add edits an application’s infrastructure.ts through the codemod engine. It writes the CDK code, typechecks the edited file, and reports the lines changed. Nothing reaches AWS until you run fjall deploy. Adding resources before the first deploy is fine. Everything you add lands on the next fjall deploy. Every add follows one shape:

fjall add <type> --app <app> --name <Name> [--<property> <value> ...]

Part	Rule
`<type>`	Required positional. One of the twelve resource types.
`--app <app>`	Required. The application that owns `fjall/<app>/infrastructure.ts`.
`--name <Name>`	Required. Letters and digits, starting with a letter. PascalCase is convention.
`--<property>`	Resource properties, each consuming the next token as its value.

fjall add never prompts. A missing <type>, --app or --name exits with a validation error rather than opening a picker. The Ink resource wizard still exists, but its only route in is the “add your first resource” hand-off shown after fjall create app for a custom-tier application.

There is no colon syntax. fjall add database:Aurora is invalid. The database variant is a property: --type Aurora.

Property flags are schema keys

Property flag names are the resource schema’s own camelCase keys, used verbatim. --databaseName is correct, --database-name is not. Four parsing rules apply:

Each flag consumes the next token as its value. A trailing flag with no value is refused.
There are no value-less booleans. Pass an explicit value, such as --deletionProtection true.
Duplicate flags are refused, so a typo surfaces instead of silently overwriting.
A value starting with { or [ must parse as JSON.

A wrong key is refused with the nearest match and the full permitted list, so fjall add database --bogus x is a safe way to discover the vocabulary.

Options

Option	Description
`-a, --app <name>`	Application to edit. Required.
`-n, --name <name>`	Resource name. Required.
`--preset <name>`	Storage only. Expands `standard`, `assets`, `upload` or `website` into properties.
`--tier <tier>`	Database and network only. Expands `tinkerer`, `lightweight`, `standard`, `resilient` or `enterprise`.
`--no-verify`	Skip the post-write typecheck of the edited `infrastructure.ts`.
`-v, --verbose`	Verbose logging.
`--non-interactive`	Force plain output for CI logs.

--preset and --tier are selectors. They expand into the same explicit properties you could type by hand, and neither name reaches the emitted statement. The two cannot be combined, --tier on a database also needs --type, and explicit property flags win over the preset.

Required properties

The add contract keeps every non-optional schema key required. A missing key is refused before the file is touched, and the error names every absent key at once.

Type	Required on add
`database`	`--type`, `--databaseName`
`compute`	`--type`, `--needsConnection`
`cdn`	`--defaultOriginRef`
`pattern`	`--type`
`storage`, `messaging`, `network`	None

Run fjall add database --app api --name Analytics with neither and the refusal is explicit:

Invalid property type: required for a new database and not provided
(missing: type, databaseName). Nothing has been written.

--tier does not supply these. A tier preset carries tuning (instance class, reader count, backup schedule), not the identity of the resource. Full per-type contract, including vpc-peer, cross-plan-connection and buildkite: fjall add.

Add a database

Pick the engine and topology with --type, and name the logical database with --databaseName:

fjall add database --app api --name Analytics --type Aurora --databaseName analytics

`--type` value	Use case
`Aurora`	Aurora Serverless clusters
`Instance`	Standard RDS instances
`GlobalAurora`	Multi-region Aurora clusters
`ClickHouse`	Analytics database for high-volume telemetry

DynamoDB is not a database type. fjall add database --type DynamoDB is refused. DynamoDB tables come from the OpenNext pattern, not from fjall add database.

Multiple databases

An application can hold several databases. Give each a distinct name:

fjall add database --app api --name Primary --type Aurora --databaseName primary
fjall add database --app api --name Analytics --type Aurora --databaseName analytics
fjall add database --app api --name Sessions --type Instance --databaseName sessions

Start from a tier preset

--tier expands that tier’s preset for the chosen --type. Explicit flags override it:

fjall add database --app api --name Analytics --type Aurora \
  --databaseName analytics --tier resilient --backupRetention 30

Add storage

An S3 bucket needs nothing beyond a name:

fjall add storage --app api --name Assets

--preset expands a starting configuration:

# CORS rules for browser uploads
fjall add storage --app api --name Uploads --preset upload

# Public read plus index.html and error.html website hosting
fjall add storage --app web --name Site --preset website

Add compute

compute covers Lambda functions, ECS clusters and EC2 workloads. Both required properties must be present:

# Standalone Lambda function
fjall add compute --app api --name ImageProcessor --type lambda --needsConnection false

# ECS cluster with one Fargate service
fjall add compute --app api --name Worker --type ecs --needsConnection false \
  --services '[{"name": "worker", "capacityProvider": "FARGATE"}]'

`--type` value	Use case
`lambda`	Event processing, APIs, scheduled jobs
`ecs`	Long-running services behind a load balancer
`ec2`	Instance-backed workloads

--tier is refused on compute. A compute tier preset is keyed by compute type and carries scaffold placeholders that only fjall apps create --tier fills in.

Wire a new Lambda to a sibling resource

Connection keys resolve sibling resource names to their bindings and write the wiring the construct reads:

fjall add compute --app api --name Api --type lambda \
  --needsConnection true --connectedDatabase '["Analytics"]'

--connectedStorage and --connectedMessaging work the same way. Only database wiring is gated on --needsConnection true.

Connection keys apply to a new Lambda only. On an ECS cluster the codemod refuses, because ECS wires connections per service. On an existing compute fjall modify refuses, because the keys rebuild environment, secretsImport and connections wholesale. Both cases are authored in infrastructure.ts directly.

Add a CDN

A CloudFront distribution needs an origin that already exists in the same infrastructure.ts. Add the origin first:

fjall add storage --app web --name Site --preset website
fjall add cdn --app web --name WebCdn --defaultOriginRef Site

--defaultOriginRef names a storage bucket or an ECS compute declared in the same file.

What Fjall wires for you

The codemod writes the connection props. The CDK constructs turn them into real AWS wiring on the next deploy.

Written by `fjall add`	Created by `fjall deploy`
`environment` entries carrying host, port and name	Function and task environment variables
`secretsImport` entries for credentials	Secrets Manager imports on the execution role
`connections: [resource]`	Security-group rules on the required ports, IAM grants

Connection environment variables

Connected resource	Environment variables
Database	`DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_SSL`, plus `DATABASE_USERNAME` and `DATABASE_PASSWORD` from Secrets Manager
Storage	`BUCKET_NAME`
Messaging	`QUEUE_URL`, `QUEUE_ARN`

The first connection of a kind carries no suffix. The second gets _2, the third _3:

DATABASE_HOST=primary.cluster-abc123.eu-west-1.rds.amazonaws.com
DATABASE_PORT=5432
DATABASE_NAME=primary
DATABASE_SSL=true

DATABASE_HOST_2=analytics.cluster-def456.eu-west-1.rds.amazonaws.com
DATABASE_PORT_2=5432
DATABASE_NAME_2=analytics

Review and deploy

Adding a resource only edits a file. Check the edit, then provision it.

Confirm the resource landed

fjall list --app api

Resources in api: 3

  File: /Users/you/acme/fjall/api/infrastructure.ts

  Name                  Type        File
  Primary               database    /Users/you/acme/fjall/api/infrastructure.ts
  Assets                storage     /Users/you/acme/fjall/api/infrastructure.ts
  ImageProcessor        compute     /Users/you/acme/fjall/api/infrastructure.ts

Typecheck and synthesise

fjall validate --app api --deep --synth

--deep runs tsc --noEmit over the edited file. Adding --synth also builds the CloudFormation template locally, with no AWS lookups.

Deploy

fjall deploy api

At a terminal, fjall deploy prints a resource-level plan and asks for approval before anything changes:

Deployment plan for api

2 to create, 1 to update

+ create  AWS::RDS::DBCluster  ApiDatabase/Analytics
+ create  AWS::EC2::SecurityGroup  ApiDatabase/AnalyticsSg
~ update  AWS::ECS::TaskDefinition  ApiCompute/TaskDef

Approve this plan and deploy?

  Yes / No

The prompt defaults to No. A deploy with nothing to change stops before the gate:

Already up to date — no changes since last deploy

--skip-confirmation and --auto-approve drop the prompt for scripted runs. In CI, pass --plan to stop before any mutation (exit 0 for no changes, 2 for changes pending approval, 1 for an error). Wrong resource? fjall undo --app api restores the most recent .bak sidecar of infrastructure.ts.

Scripting `fjall add`

fjall add is already safe in a pipeline, because it never prompts. --non-interactive only forces plain output for CI logs. What makes a scripted add succeed is supplying every required property:

fjall add database --app api --name Analytics --type Aurora \
  --databaseName analytics --non-interactive

fjall add compute --app api --name Worker --type lambda \
  --needsConnection false --non-interactive

fjall add storage --app api --name Uploads --preset upload --non-interactive

Worked example

Build an API application with a bucket, a Lambda and a database, then deploy it:

fjall add storage --app api --name Assets

fjall add database --app api --name Primary --type Aurora --databaseName primary

fjall add compute --app api --name Api --type lambda \
  --needsConnection true --connectedDatabase '["Primary"]' \
  --connectedStorage '["Assets"]'

fjall validate --app api --deep
fjall deploy api

All resource types

<type> is one of these twelve exact values:

Type	Adds
`database`	Aurora, RDS instance, GlobalAurora or ClickHouse
`compute`	Lambda function, ECS cluster or EC2 workload
`storage`	S3 bucket
`cdn`	CloudFront distribution
`messaging`	SQS queue, standard or FIFO
`network`	An additional VPC
`pattern`	A pattern composition (Payload CMS or static site)
`vpc-peer`	VPC peering requester
`vpc-peer-accepter`	VPC peering accepter
`cross-plan-connection`	A connection to a resource in another application
`organisation`	Organisation-tier configuration inside an organisation scaffold
`buildkite`	A Buildkite agent fleet

fjall add messaging writes an SQS queue. SNS topics and EventBridge buses are authored through MessagingFactory in infrastructure.ts rather than through fjall add.

Next Steps

fjall add reference

Every flag, property and per-type add contract.

Deploy Application

Provision the updated infrastructure on AWS.

fjall modify

Change the properties of a resource you already added.

fjall remove

Remove a resource from infrastructure.ts.

fjall validate

Typecheck and synthesise before deploying.

Destructive Changes

What happens when a change replaces or destroys a resource.

Install & Setup

Application Deploy

Deployment Errors

Organisation Setup

Organisation Deploy

Add Resources

Overview

Property flags are schema keys

Options

Required properties

Add a database

Multiple databases

Start from a tier preset

Add storage

Add compute

Wire a new Lambda to a sibling resource

Add a CDN

What Fjall wires for you

Connection environment variables

Review and deploy

Scripting `fjall add`

Worked example

All resource types

Next Steps

fjall add reference

Deploy Application

fjall modify

fjall remove

fjall validate

Destructive Changes

​Overview

​Property flags are schema keys

​Options

​Required properties

​Add a database

​Multiple databases

​Start from a tier preset

​Add storage

​Add compute

​Wire a new Lambda to a sibling resource

​Add a CDN

​What Fjall wires for you

​Connection environment variables

​Review and deploy

​Scripting fjall add

​Worked example

​All resource types

​Next Steps

fjall add reference

Deploy Application

fjall modify

fjall remove

fjall validate

Destructive Changes

Overview

Property flags are schema keys

Options

Required properties

Add a database

Multiple databases

Start from a tier preset

Add storage

Add compute

Wire a new Lambda to a sibling resource

Add a CDN

What Fjall wires for you

Connection environment variables

Review and deploy

Scripting `fjall add`

Worked example

All resource types

Next Steps