AWS.Amplify reference

App

Source: src/AWS/Amplify/App.ts

An AWS Amplify Hosting app. This resource provisions the app container; it does not connect a Git repository.

Connecting a repository requires an OAuth handshake (via CodeConnections or a personal access token) that is inherently human-in-the-loop and cannot be automated from infrastructure code. To wire a repo, create the app with this resource, then connect the repository from the Amplify console or CLI. Manual-deploy branches (no repo required) are code-driven via the Branch resource plus the CreateDeployment/StartDeployment bindings. For a fully code-driven static/SSR site on AWS, prefer Alchemy’s own Website composites (S3 + CloudFront).

App: Creating Amplify Apps

Basic App

const app = yield* App("MyApp", {
  description: "Marketing site",
  platform: "WEB",
});

App with Build Config and Redirects

const app = yield* App("MyApp", {
  platform: "WEB_COMPUTE",
  environmentVariables: { NODE_ENV: "production" },
  customRules: [
    { source: "/<*>", target: "/index.html", status: "404-200" },
  ],
  buildSpec: "version: 1\nfrontend:\n  phases:\n    build:\n      commands: []\n",
});

App: Deploying and Observing From a Function

Manual Deploy Pipeline (CreateDeployment + StartDeployment)

// init — bind the deployment operations to the app
const createDeployment = yield* AWS.Amplify.CreateDeployment(app);
const startDeployment = yield* AWS.Amplify.StartDeployment(app);

// runtime — stage, upload, release
const { jobId, zipUploadUrl } = yield* createDeployment({
  branchName: "main",
});
// PUT the site zip to zipUploadUrl, then:
yield* startDeployment({ branchName: "main", jobId });

React to Deployment Status Changes

yield* AWS.Amplify.consumeDeploymentStatusChanges(
  { jobStatus: ["FAILED"] },
  (events) =>
    Stream.runForEach(events, (event) =>
      Effect.log(`build failed on ${event.detail.branchName}`),
    ),
);

Branch

Source: src/AWS/Amplify/Branch.ts

A branch of an AWS Amplify Hosting app.

For apps without a connected Git repository, a branch is the target of the manual-deploy pipeline: stage a zip with CreateDeployment, upload it to the pre-signed URL, and release it with StartDeployment.

Branch: Creating Branches

Manual-Deploy Branch

const app = yield* App("MySite", { platform: "WEB" });
const branch = yield* Branch("Main", {
  appId: app.appId,
  branchName: "main",
  stage: "PRODUCTION",
  enableAutoBuild: false,
});

Password-Protected Branch with Content TTL

const branch = yield* Branch("Preview", {
  appId: app.appId,
  branchName: "preview",
  stage: "DEVELOPMENT",
  ttl: "10 minutes",
  enableBasicAuth: true,
  // base64 of "user:password"
  basicAuthCredentials: Redacted.make(credentials),
});

CreateDeployment

Source: src/AWS/Amplify/CreateDeployment.ts

Runtime binding for amplify:CreateDeployment.

Bind an App in the function’s init phase to get a callable that creates a manual deployment for a branch of an app with no connected repository. The result carries pre-signed upload URLs (zipUploadUrl, or per-file fileUploadUrls when a fileMap of MD5 hashes is supplied); upload the content there, then release it with StartDeployment. Provide the implementation with Effect.provide(AWS.Amplify.CreateDeploymentHttp).

CreateDeployment: Manual Deployments

// init — bind the operation to the app
const createDeployment = yield* AWS.Amplify.CreateDeployment(app);

// runtime — obtain the upload URL for the deployment artifact
const { jobId, zipUploadUrl } = yield* createDeployment({
  branchName: "main",
});
// PUT the site zip to `zipUploadUrl`, then start the deployment with jobId

DeleteJob

Source: src/AWS/Amplify/DeleteJob.ts

Runtime binding for amplify:DeleteJob.

Bind an App in the function’s init phase to get a callable that deletes a build job from a branch’s history — e.g. a maintenance function pruning old build records. Provide the implementation with Effect.provide(AWS.Amplify.DeleteJobHttp).

DeleteJob: Controlling Jobs

// init — bind the operation to the app
const deleteJob = yield* AWS.Amplify.DeleteJob(app);

// runtime — remove the job from the branch's history
yield* deleteJob({ branchName: "main", jobId: "42" });

GenerateAccessLogs

Source: src/AWS/Amplify/GenerateAccessLogs.ts

Runtime binding for amplify:GenerateAccessLogs.

Bind an App in the function’s init phase to get a callable that generates a pre-signed URL to the app’s access logs for a time range — e.g. an analytics function ingesting traffic data on a schedule. Provide the implementation with Effect.provide(AWS.Amplify.GenerateAccessLogsHttp).

GenerateAccessLogs: Reading Access Logs

// init — bind the operation to the app
const generateAccessLogs = yield* AWS.Amplify.GenerateAccessLogs(app);

// runtime — logUrl is a pre-signed CSV download
const { logUrl } = yield* generateAccessLogs({
  domainName: "example.com",
  startTime: new Date(Date.now() - 24 * 60 * 60 * 1000),
  endTime: new Date(),
});

GetArtifactUrl

Source: src/AWS/Amplify/GetArtifactUrl.ts

Runtime binding for amplify:GetArtifactUrl.

Bind an App in the function’s init phase to get a callable that resolves a pre-signed download URL for a build artifact discovered via ListArtifacts. Provide the implementation with Effect.provide(AWS.Amplify.GetArtifactUrlHttp).

GetArtifactUrl: Reading Artifacts

// init — bind the operation to the app
const listArtifacts = yield* AWS.Amplify.ListArtifacts(app);
const getArtifactUrl = yield* AWS.Amplify.GetArtifactUrl(app);

// runtime — resolve a pre-signed URL for the first artifact
const { artifacts } = yield* listArtifacts({
  branchName: "main",
  jobId: "42",
});
const { artifactUrl } = yield* getArtifactUrl({
  artifactId: artifacts[0].artifactId,
});

GetJob

Source: src/AWS/Amplify/GetJob.ts

Runtime binding for amplify:GetJob.

Bind an App in the function’s init phase to get a callable that reads a build job — its summary and per-step logs/status — for one of the app’s branches. Provide the implementation with Effect.provide(AWS.Amplify.GetJobHttp).

GetJob: Observing Jobs

// init — bind the operation to the app
const getJob = yield* AWS.Amplify.GetJob(app);

// runtime — read the job's current status
const { job } = yield* getJob({ branchName: "main", jobId: "42" });
if (job.summary.status === "FAILED") {
  yield* Effect.log(`build failed: ${job.summary.jobId}`);
}

ListArtifacts

Source: src/AWS/Amplify/ListArtifacts.ts

Runtime binding for amplify:ListArtifacts.

Bind an App in the function’s init phase to get a callable that lists the artifacts (e.g. test reports) a build job produced. Fetch an individual artifact with GetArtifactUrl. Provide the implementation with Effect.provide(AWS.Amplify.ListArtifactsHttp).

ListArtifacts: Reading Artifacts

// init — bind the operation to the app
const listArtifacts = yield* AWS.Amplify.ListArtifacts(app);

// runtime
const { artifacts } = yield* listArtifacts({
  branchName: "main",
  jobId: "42",
});

ListJobs

Source: src/AWS/Amplify/ListJobs.ts

Runtime binding for amplify:ListJobs.

Bind an App in the function’s init phase to get a callable that lists the build jobs of one of the app’s branches, newest first. Provide the implementation with Effect.provide(AWS.Amplify.ListJobsHttp).

ListJobs: Observing Jobs

// init — bind the operation to the app
const listJobs = yield* AWS.Amplify.ListJobs(app);

// runtime — the first summary is the most recent job
const { jobSummaries } = yield* listJobs({
  branchName: "main",
  maxResults: 1,
});
const latest = jobSummaries[0];

StartDeployment

Source: src/AWS/Amplify/StartDeployment.ts

Runtime binding for amplify:StartDeployment.

Bind an App in the function’s init phase to get a callable that releases a manual deployment on a branch of an app with no connected repository — either a deployment staged with CreateDeployment (jobId) or content fetched from a public sourceUrl (zip URL or S3 prefix). Provide the implementation with Effect.provide(AWS.Amplify.StartDeploymentHttp).

StartDeployment: Manual Deployments

Release a Staged Deployment

// init — bind the operation to the app
const startDeployment = yield* AWS.Amplify.StartDeployment(app);

// runtime — release the artifact uploaded via CreateDeployment
const { jobSummary } = yield* startDeployment({
  branchName: "main",
  jobId,
});

Deploy Directly from an S3 Prefix

const { jobSummary } = yield* startDeployment({
  branchName: "main",
  sourceUrl: "s3://my-site-artifacts/latest/",
  sourceUrlType: "BUCKET_PREFIX",
});

StartJob

Source: src/AWS/Amplify/StartJob.ts

Runtime binding for amplify:StartJob.

Bind an App in the function’s init phase to get a callable that starts a build/deploy job for one of the app’s branches — the app id is injected automatically and amplify:StartJob is granted on the app’s jobs. Provide the implementation with Effect.provide(AWS.Amplify.StartJobHttp).

The canonical use is a webhook Lambda that rebuilds the site when upstream content changes (a CMS publish, a data refresh, etc.).

StartJob: Starting Jobs

// init — bind the operation to the app
const startJob = yield* AWS.Amplify.StartJob(app);

// runtime — kick off a release of the main branch
const { jobSummary } = yield* startJob({
  branchName: "main",
  jobType: "RELEASE",
  jobReason: "CMS content published",
});

StopJob

Source: src/AWS/Amplify/StopJob.ts

Runtime binding for amplify:StopJob.

Bind an App in the function’s init phase to get a callable that cancels an in-progress build job on one of the app’s branches. Provide the implementation with Effect.provide(AWS.Amplify.StopJobHttp).

StopJob: Controlling Jobs

// init — bind the operation to the app
const stopJob = yield* AWS.Amplify.StopJob(app);

// runtime — cancel the job
const { jobSummary } = yield* stopJob({
  branchName: "main",
  jobId: "42",
});