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.

info

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.

info

See the AWS CDK Boostrap documentation

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

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

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:

my-service
├──README.md # a README with some helpful tips
├──infra # an AWS CDK application that deploys the repo's infrastructure
├──packages
    ├──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
tip

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>" }
tip

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:

Result:
goodbye my name
info

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.