Skip to main content

Quick Start

This guide will help you set up a project, deploy, make a change and test it.

0. Setup

1. Create a new project

To create a new Eventual project, run:

npm create eventual@latest

Install Dependenices

cd my-project
npm i

Configure AWS CLI Profile

Eventual works with AWS and relies on you having a configured AWS CLI profile.


See the Configuring the AWS CLI documentation.

After installing the AWS CLI, run the following command to configure your AWS CLI profile.

aws configure

Bootstrap your AWS Account (for AWS CDK usage)

In order to deploy an Eventual application, you need to first "bootstrap" the AWS account and region you wish to deploy your application to.

Run the following command from the root of your new project:

npx cdk bootstrap aws://(your-account-number)/(your-aws-region)

You will need to replace your-account-number and your-aws-region with your desired values, for example:

cdk bootstrap aws://123456789/us-east-1

Review the created project structure

The project template generates the following project structure containing 3 NPM packages:

├── # a README with some helpful tips
├──infra # an AWS CDK application that deploys the repo's infrastructure
├──service # the NPM package containing the @my-service/service business logic

2. Make a Change

You're now ready to make a change and deploy the application.

Let's update the formatMessage task in packages/service/src/hello.ts to give you an idea of how changes make their way to AWS.

export const formatMessage = task("formatName", async (name: string) => {
// return `hello ${name}`;
return `goodbye ${name}`;

3. Deploy the Service

Use the deploy script to deploy your Service to AWS with the AWS Cloud Development Kit.

npm run deploy

You can find the CDK application in infra/src/app.ts. This is where you configure infrastructure.

4. Invoke a Command

Execute the hello command.

npx eventual invoke hello "my name"

The hello command in the template triggers a workflow and returns its execution ID.

{ "executionId": "<execution-id>" }

To see how, take a look at hello in packages/service/src/hello.ts.

5. Check the status of a Workflow Execution

Use the eventual CLI to get the status of the workflow we just started.

npx eventual get execution <execution-id>

It should output:

goodbye my name

Note the "goodbye" in the output. We made a change to a task that was then invoked by a Workflow Execution. The data returned by that Workflow Execution is what we see here.

6. View the logs

To view the logs for the workflow execution we just started, use the eventual get logs command followed by the --execution flag and the execution ID:

npx eventual get logs --execution <execution-id>

Next Steps

  • To learn more about our features and capabilities, view the What is Eventual 📖 guide.
  • Review the Reference Docs for a deep dive into Eventual's API.