Fjall Docs — deploy AWS infrastructure into your own account

Overview

StorageFactory creates S3 bucket resources with type-safe configurations. Every bucket comes from the single S3Bucket class. Different property combinations control the behaviour (private, website hosting, public read access).

For databases (Aurora, RDS, DynamoDB), use the DatabaseFactory instead.

Basic Usage

import { App, StorageFactory } from "@fjall/components-infrastructure";

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

const assets = app.addStorage(StorageFactory.build("Assets", {}));

Bucket Configurations

Private Bucket (Default)

Standard bucket with no public access. Best for application assets, uploads and caches:

const assets = app.addStorage(
  StorageFactory.build("Assets", {
    encryption: "AES256",
  }),
);

Versioning follows the application’s backup tier. A bucket in an application created with App.getApp(name, { backup: { tier: "resilient" } }) (or "enterprise") is versioned by default, with a 30-day noncurrent-version expiry rule. A standard application, or one with no backup tier, leaves versioning off. Set versioned to override the tier in either direction, or backupVaultTier to give one bucket a different tier from the application. Features:

Private by default (block public access set to BLOCK_ALL)
Versioning driven by the backup tier
Optional encryption (AES256 or KMS)

Website Hosting Bucket

Configure a bucket for static website hosting with the websiteHosting property:

const site = app.addStorage(
  StorageFactory.build("StaticSite", {
    websiteHosting: {
      indexDocument: "index.html",
      errorDocument: "404.html",
    },
  }),
);

const url = site.getWebsiteUrl();

Features:

Static website hosting enabled
Configurable index and error documents (errorDocument defaults to error.html)
CORS support

Setting websiteHosting makes the bucket publicly readable. The S3 website endpoint has no other access path, so the factory applies the same public-read policy it applies for publicReadAccess: true. For a private origin behind CloudFront, use the CDN Factory instead.

Public Read Access Bucket

Grant public read access to all objects with the publicReadAccess property:

const publicAssets = app.addStorage(
  StorageFactory.build("PublicAssets", {
    publicReadAccess: true,
  }),
);

Features:

All objects publicly readable through a bucket policy
Best for CDN origin buckets
Optional versioning and encryption

Removal Policy

removalPolicy decides whether a bucket survives stack teardown. It is the highest-consequence property on the factory.

Setting	Behaviour
Unset (default)	Resolved from the deploy’s environment: `production` retains, every other stage destroys
`removalPolicy: "RETAIN"`	Bucket survives stack deletion in every environment
`removalPolicy: "DESTROY"`	Bucket is deleted with the stack in every environment
`retain: true` (legacy)	Same as `"RETAIN"`. Kept for imported buckets. `removalPolicy` wins when both are set

const scratch = app.addStorage(
  StorageFactory.build("Scratch", {
    removalPolicy: "DESTROY",
  }),
);

A DESTROY bucket carries the fjall:sdk-pre-empty tag, so fjall destroy empties it before CloudFormation deletes the stack. Without that tag, a non-empty bucket blocks the delete.

Configuration Parameters

Parameter	Type	Description	Default
`bucketName`	`string`	Explicit physical bucket name	CloudFormation-generated
`versioned`	`boolean`	Enable versioning	Follows the effective backup tier: on for `resilient` / `enterprise`, off otherwise
`versioningExemption`	`"build-output" \| "isr-cache" \| "cold-tier"`	Why the bucket stays unversioned by design; stamped as the `fjall:s3:versioning-exempt` tag while `versioned` resolves to `false`	-
`encryption`	`"AES256" \| "KMS"`	Encryption type	Unset, so AWS applies SSE-S3
`kmsKeyArn`	`string`	KMS key ARN (with `encryption: "KMS"`)	AWS-managed key
`bucketKeyEnabled`	`boolean`	S3 Bucket Keys, which cut per-object KMS request charges. Ignored without KMS	`true` under KMS
`publicReadAccess`	`boolean`	Allow public read access	`false`
`websiteHosting`	`object`	Website hosting configuration	-
`websiteHosting.indexDocument`	`string`	Index document name. Required when `websiteHosting` is set	-
`websiteHosting.errorDocument`	`string`	Error document name	`"error.html"`
`cors`	`CorsRule[]`	CORS rules	-
`resourcePolicyStatements`	`ResourcePolicyStatement[]`	Bucket-policy statements appended to the bucket’s resource policy	-
`removalPolicy`	`"DESTROY" \| "RETAIN"`	Teardown behaviour. Overrides the environment default and `retain`	Environment-aware
`retain`	`boolean`	Legacy RETAIN flag for imported buckets	`false`
`stackPlacement`	`"storage" \| "cdn" \| "compute"`	Which CDK stack to place the bucket in	`"storage"`
`backupVaultTier`	`BackupTier`	Per-bucket AWS Backup tier override (`standard`, `resilient`, `enterprise`). Wins over the application tier	App backup tier
`deployment`	`S3DeploymentConfig`	Auto-deploy files from a local path	-

Common Patterns

Media Uploads

Store user-uploaded media. A resilient or enterprise application versions the bucket through its tier. versioned: true pins versioning on whatever the application tier is:

const media = app.addStorage(
  StorageFactory.build("Media", {
    versioned: true,
    encryption: "AES256",
  }),
);

Static Assets with Deployment

Upload static assets during CDK deployment:

const assets = app.addStorage(
  StorageFactory.build("Assets", {
    deployment: {
      source: "./public/assets",
      prune: true,
      cacheControl: {
        maxAge: 31536000, // 1 year
        immutable: true,
      },
    },
  }),
);

ISR Cache Bucket

Cache bucket for Next.js ISR:

const cache = app.addStorage(StorageFactory.build("Cache", {}));

Website with CORS

Website bucket with CORS for API requests:

const site = app.addStorage(
  StorageFactory.build("Website", {
    websiteHosting: {
      indexDocument: "index.html",
      errorDocument: "error.html",
    },
    cors: [
      {
        allowedOrigins: ["https://api.example.com"],
        allowedMethods: ["GET", "HEAD"],
      },
    ],
  }),
);

allowedMethods accepts GET, PUT, POST, DELETE and HEAD. Any other value fails synth.

CDN Origin Bucket

Place a bucket in the CDN stack to avoid circular dependencies:

const cdnAssets = app.addStorage(
  StorageFactory.build("CDNAssets", {
    stackPlacement: "cdn",
    encryption: "AES256",
  }),
);

KMS Encryption

const encrypted = app.addStorage(
  StorageFactory.build("Secure", {
    encryption: "KMS",
    kmsKeyArn: "arn:aws:kms:ap-southeast-2:123456789012:key/abc-123",
  }),
);

KMS buckets turn on S3 Bucket Keys by default, which cuts per-object KMS request charges. Pass bucketKeyEnabled: false to opt out. Omitting kmsKeyArn falls back to the AWS-managed key and raises a synth warning.

Bucket Policy Statements

Append statements to the bucket’s resource policy. Principals are either "*" or an IAM ARN:

const shared = app.addStorage(
  StorageFactory.build("Shared", {
    resourcePolicyStatements: [
      {
        sid: "AuditReadOnly",
        effect: "Allow",
        principals: ["arn:aws:iam::123456789012:role/AuditReader"],
        actions: ["s3:GetObject", "s3:ListBucket"],
      },
    ],
  }),
);

The TLS-only deny statement is applied separately on every bucket. Do not add it here.

Deploying Assets After Construction

The constructor deployment property uploads assets but cannot invalidate a CloudFront cache, because the distribution does not exist yet when the bucket is built. Call deployAssets(config, distribution?) after the CDN to get both:

const site = app.addStorage(
  StorageFactory.build("Site", { stackPlacement: "cdn" }),
);

const cdn = app.addCdn(
  CdnFactory.build("SiteCdn", {
    originType: "s3",
    bucket: site,
    defaultRootObject: "index.html",
  }),
);

site.deployAssets(
  {
    source: "./dist",
    prune: true,
    cacheControl: { maxAge: 31536000, immutable: true },
  },
  cdn.getDistribution(),
);

Passing the distribution invalidates /* after upload, so new assets serve immediately instead of waiting out the cache TTL. A bucket deploys one asset set. Calling deployAssets when a deployment already exists (from the constructor deployment property or a prior call) throws rather than stacking a second BucketDeployment whose prune semantics would fight the first.

Accessing Bucket Information

const storage = app.addStorage(StorageFactory.build("Assets", {}));

const name = storage.getBucketName();
const arn = storage.getBucketArn();
const domainName = storage.getBucketDomainName();
const regionalDomainName = storage.getBucketRegionalDomainName();

// Website URL, undefined unless websiteHosting is set
const websiteUrl = storage.getWebsiteUrl();

// The BucketDeployment, undefined until one is created
const deployment = storage.getDeployment();

// The concrete S3Bucket, for escape hatches such as addLifecycleRule
const bucket = storage.getBucket();

The bucket ARN and name are also emitted as CloudFormation outputs, exported as <stackName><id>BucketArn and <stackName><id>BucketName.

Connecting to Compute Resources

Pass the storage construct in a compute resource’s connections array. Fjall grants the IAM policy. Storage connections default to readWrite:

import { Code } from "aws-cdk-lib/aws-lambda";

const assets = app.addStorage(StorageFactory.build("Assets", {}));

// Lambda with read-only S3 access
const api = app.addCompute(
  ComputeFactory.build("Api", {
    type: "lambda",
    deployment: "code",
    code: Code.fromAsset("./api"),
    handler: "index.handler",
    connections: [{ resource: assets, access: "read" }],
  }),
);

// ECS with read/write S3 access plus the bucket name in the environment
const service = app.addCompute(
  ComputeFactory.build("Service", {
    type: "ecs",
    services: [
      {
        name: "web",
        capacityProvider: "FARGATE",
        connections: [assets],
        containers: [
          {
            port: 3000,
            environment: {
              ASSETS_BUCKET: assets.getBucketName(),
            },
          },
        ],
      },
    ],
  }),
);

On ECS, connections sits on the service, not on the compute props. On Lambda it sits at the top level. connections handles IAM only. Pass the bucket name through environment when the application code needs it at runtime.

Granting Access

Grant access directly to any IAM grantable when connections is not the right fit:

const storage = app.addStorage(StorageFactory.build("Assets", {}));

storage.grantRead(lambdaFunction);
storage.grantWrite(lambdaFunction);
storage.grantReadWrite(lambdaFunction);
storage.grantPut(lambdaFunction);
storage.grantDelete(lambdaFunction);

// Grant anonymous read access to a specific prefix
storage.grantPublicAccess("public/*");

grantPublicAccess writes a bucket policy, so it works only on a bucket created with publicReadAccess: true or websiteHosting. A private bucket blocks public policies.

Event Notifications

import { EventType } from "aws-cdk-lib/aws-s3";

const storage = app.addStorage(StorageFactory.build("Uploads", {}));

// Notify Lambda when objects are created
storage.addObjectCreatedNotification(lambdaDestination, {
  prefix: "uploads/",
  suffix: ".jpg",
});

// Notify a queue when objects are removed
storage.addObjectRemovedNotification(sqsDestination, {
  prefix: "temp/",
});

// Any other event type
storage.addEventNotification(
  EventType.OBJECT_RESTORE_COMPLETED,
  sqsDestination,
  {
    prefix: "archive/",
  },
);

Security

Every bucket gets these without configuration:

TLS-only access: a deny statement rejects non-HTTPS requests
Encryption: SSE-S3 applies by default. Set encryption to pin AES256 or KMS
Multipart hygiene: incomplete multipart uploads abort after 7 days, so abandoned parts stop accruing storage cost
IAM policies: least-privilege grants from connections and the grant* methods

Block Public Access

A private bucket asserts BLOCK_ALL in the template rather than relying on the account default, so a manually loosened bucket is healed on the next deploy. Setting publicReadAccess: true or websiteHosting opens the two policy halves (blockPublicPolicy and restrictPublicBuckets off) and keeps the two ACL halves closed (blockPublicAcls and ignorePublicAcls on). Public access is bucket-policy-based, because ACLs are disabled on modern buckets.

Best Practices

Keep buckets private by default - Set publicReadAccess or websiteHosting only when a public endpoint is the requirement
Choose a backup tier that matches the data’s recovery needs - Override versioned or backupVaultTier only for a single-bucket exception
Set removalPolicy: "RETAIN" on any non-production bucket holding data you cannot re-create
Use KMS encryption for regulated or customer-sensitive data, and leave bucketKeyEnabled on
Use deployment or deployAssets for static assets instead of a manual S3 sync
Set stackPlacement to "cdn" when the bucket is a CloudFront origin

Next Steps

CDN Factory

Front a bucket with CloudFront

Compute Factory

Deploy Lambda and ECS compute resources

Database Factory

Create Aurora, RDS and DynamoDB databases

Static Site Pattern

Deploy a static site with bucket, CDN and DNS

Factory Patterns

Application Patterns

Architecture Patterns

Storage Factory

Overview

Basic Usage

Bucket Configurations

Private Bucket (Default)

Website Hosting Bucket

Public Read Access Bucket

Removal Policy

Configuration Parameters

Common Patterns

Media Uploads

Static Assets with Deployment

ISR Cache Bucket

Website with CORS

CDN Origin Bucket

KMS Encryption

Bucket Policy Statements

Deploying Assets After Construction

Accessing Bucket Information

Connecting to Compute Resources

Granting Access

Event Notifications

Security

Block Public Access

Best Practices

Next Steps

CDN Factory

Compute Factory

Database Factory

Static Site Pattern

​Overview

​Basic Usage

​Bucket Configurations

​Private Bucket (Default)

​Website Hosting Bucket

​Public Read Access Bucket

​Removal Policy

​Configuration Parameters

​Common Patterns

​Media Uploads

​Static Assets with Deployment

​ISR Cache Bucket

​Website with CORS

​CDN Origin Bucket

​KMS Encryption

​Bucket Policy Statements

​Deploying Assets After Construction

​Accessing Bucket Information

​Connecting to Compute Resources

​Granting Access

​Event Notifications

​Security

​Block Public Access

​Best Practices

​Next Steps

CDN Factory

Compute Factory

Database Factory

Static Site Pattern

Overview

Basic Usage

Bucket Configurations

Private Bucket (Default)

Website Hosting Bucket

Public Read Access Bucket

Removal Policy

Configuration Parameters

Common Patterns

Media Uploads

Static Assets with Deployment

ISR Cache Bucket

Website with CORS

CDN Origin Bucket

KMS Encryption

Bucket Policy Statements

Deploying Assets After Construction

Accessing Bucket Information

Connecting to Compute Resources

Granting Access

Event Notifications

Security

Block Public Access

Best Practices

Next Steps