Quick Start

Prefer a runnable example?

The getting-started example teaches chant in levels — clone it, run npm run build / npm run lint / npm run list, and read up from pure synthesis. This page is the from-scratch walkthrough.

Step 1: Install chant

Install a lexicon for your target platform (this also installs chant):

npm install --save-dev @intentius/chant-lexicon-aws  # or another lexicon

Verify it works:

chant --version

See Installation for details.

Step 2: Initialize a Project

chant init my-infra --lexicon aws
cd my-infra

This scaffolds a project with a chant.config.ts and starter resources in src/.

Step 3: Write Resources

Here’s a typical chant project. Shared defaults are regular exports that other files import directly:

src/defaults.ts

import {
  ServerSideEncryptionByDefault,
  ServerSideEncryptionRule,
  BucketEncryption,
  PublicAccessBlockConfiguration,
  VersioningConfiguration,
} from "@intentius/chant-lexicon-aws";

export const encryptionDefault = new ServerSideEncryptionByDefault({
  SSEAlgorithm: "AES256",
});

export const encryptionRule = new ServerSideEncryptionRule({
  ServerSideEncryptionByDefault: encryptionDefault,
});

export const bucketEncryption = new BucketEncryption({
  ServerSideEncryptionConfiguration: [encryptionRule],
});

export const publicAccessBlock = new PublicAccessBlockConfiguration({
  BlockPublicAcls: true,
  BlockPublicPolicy: true,
  IgnorePublicAcls: true,
  RestrictPublicBuckets: true,
});

export const versioningEnabled = new VersioningConfiguration({
  Status: "Enabled",
});

export const lambdaTrustPolicy = {
  Version: "2012-10-17",
  Statement: [
    {
      Effect: "Allow",
      Principal: { Service: "lambda.amazonaws.com" },
      Action: "sts:AssumeRole",
    },
  ],
};

export const lambdaBasicExecutionArn =
  "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole";

Resource files import types from the lexicon and reference sibling exports through direct imports:

src/data-bucket.ts

import { Bucket, Sub, AWS, Ref } from "@intentius/chant-lexicon-aws";
import { versioningEnabled, bucketEncryption, publicAccessBlock } from "./defaults";
import { environment } from "./params";

export const dataBucket = new Bucket({
  BucketName: Sub`${AWS.StackName}-${Ref(environment)}-data`,
  VersioningConfiguration: versioningEnabled,
  BucketEncryption: bucketEncryption,
  PublicAccessBlockConfiguration: publicAccessBlock,
});

Every property is typed — your editor autocompletes bucketName, bucketEncryption, sseAlgorithm, and catches typos immediately. Cross-file references like bucketEncryption are resolved through standard imports at build time.

Composites

Built-in composites bundle common resource patterns into reusable factories:

src/main.ts

import { LambdaNode, Sub, AWS, Ref } from "@intentius/chant-lexicon-aws";
import { environment } from "./params";

export const app = LambdaNode({
  name: Sub`${AWS.StackName}-${Ref(environment)}-fn`,
  Code: {
    ZipFile: `exports.handler = async (event) => {
  console.log("Event:", JSON.stringify(event));
  return {
    statusCode: 200,
    body: JSON.stringify({ message: "Hello from Lambda!" }),
  };
};`,
  },
});

LambdaNode creates an IAM Role + Lambda Function with Node.js defaults. See Composites for all built-in composites.

See the AWS CloudFormation lexicon reference for intrinsic functions, composites, custom lint rules, and examples.

AWS walkthrough

For a complete walkthrough with S3 buckets, IAM roles, Lambda functions, and cross-resource references, see the AWS Examples.

Property constraints

Resource properties must be statically evaluable — chant reads your TypeScript as data, it never executes it. See TypeScript as Data for supported patterns.

Step 4: Build

chant build

The build command discovers all .ts files, collects exported declarables, resolves dependencies, and serializes to the target format.

Step 5: Run an Op

Resources synthesize to artifacts. Ops execute — phased, with retries and rollback. Write a minimal one:

hello.op.ts

import { Op, phase, shell } from "@intentius/chant-lexicon-temporal";

export default Op({
  name: "hello",
  overview: "Minimal local Op — no Temporal server required",
  taskQueue: "hello",
  phases: [
    phase("Greet", [
      shell("echo hello from chant"),
    ]),
  ],
});

chant run hello

[phase] Greet
  ✓ shellCmd(cmd=echo hello from chant)   42ms
Op "hello" completed in 0.1s

No Temporal server required — chant runs Ops locally by default. (The Op imports from @intentius/chant-lexicon-temporal, so install that package — but nothing has to be running.) For durable resume, gates, and schedules, configure a Temporal profile and pass --temporal. See Local vs Temporal.

Step 6: See drift, decide what to do

Once resources are deployed, chant tells you when the cloud and your source disagree — without hosting a state file:

chant lifecycle diff prod --live

That’s the observe position: report drift, change nothing. From there you turn the dial up per environment — open cloud → code PRs (ReconcileOp) or apply code → cloud behind a gate (ApplyOp). The lifecycle-reconcile-aws example walks the whole loop; Lifecycle Models explains the dial.

Next Steps

• Project Structure — understand what chant init created
• Core Concepts — learn the design principles behind chant
• Writing Resources — the full guide to defining resources
• Linting & Type-Checking — validate your definitions
• Choosing Your Deployment Model — synthesize only, or extend into durable deployment workflows
• Ops — define *.op.ts files for phased, observable deploys with gates and rollback
• Lifecycle Models — the observe → reconcile → authoritative dial, chosen per environment