This is the AWS CDK v2 Developer Guide. The older CDK v1 entered maintenance on June 1, 2022 and ended support on June 1, 2023.

# Getting started with the CDK Toolkit Library
Getting started

Get started with using the AWS CDK Toolkit Library to programmatically perform CDK actions, such as synthesis and deployment, in your code.

## Prerequisites


1. Supported version of Node.js installed.

1.  AWS credentials configured.

1. Basic familiarity with the AWS CDK.

For more information, see [AWS CDK prerequisites](prerequisites.md).

## Step 1: Installing the CDK Toolkit Library


Install the CDK Toolkit Library package in your project’s development environment by running the following:

```
npm install --save @aws-cdk/toolkit-lib
```

## Step 2: Initializing the CDK Toolkit Library


Create a CDK Toolkit instance to perform programmatic actions on your CDK app.

```
import { Toolkit } from '@aws-cdk/toolkit-lib';

const toolkit = new Toolkit({
    // Optional configuration options go here
});
```

You can customize the CDK Toolkit instance during creation. For instructions, see [Configure your CDK Toolkit instance](toolkit-library-configure.md).

## Step 3: Creating a cloud assembly source for your CDK app


A cloud assembly source provides instructions for generating CloudFormation templates from your CDK app. You can create one in multiple ways. The following are a few examples:

1.  **An inline assembly builder function**:

   ```
   import * as cdk from 'aws-cdk-lib';
   
   const cloudAssemblySource = await toolkit.fromAssemblyBuilder(async () => {
     const app = new cdk.App();
     new MyStack(app, 'MyStack');
     return app.synth();
   });
   ```

1.  **An existing CDK app file**:

   ```
   const cloudAssemblySource = await toolkit.fromCdkApp("ts-node app.ts");
   ```

For more information, see [Configure cloud assembly sources](toolkit-library-configure-ca.md).

## Step 4: Defining programmatic actions for your CDK app


Now that you’ve created a CDK Toolkit instance and cloud assembly source, you can start to define programmatic actions. The following is a basic example that creates a deployment of the `MyStack` stack:

```
import { StackSelectionStrategy } from '@aws-cdk/toolkit-lib';

await toolkit.deploy(cloudAssemblySource, {
  stacks: {
    strategy: StackSelectionStrategy.PATTERN_MUST_MATCH, // Deploy only stacks that exactly match the provided patterns
    patterns: ["MyStack"],
  },
});
```

## Step 5: Customizing the CDK Toolkit further


You can configure and customize the CDK Toolkit further for your needs:
+  **Messages and interactions** - Configure how the CDK Toolkit communicates with users and applications. See [Configure messages & interactions](toolkit-library-configure-messages.md).
+  **Error handling** - Implement structured error handling for CDK operations. See [Configure error handling](toolkit-library-configure.md#toolkit-library-configure-errors).

## Additional resources


For more information on the CDK Toolkit Library `npm` package, see the [ReadMe](https://www.npmjs.com/package/@aws-cdk/toolkit-lib) in the *@aws-cdk/toolkit-lib* `npm` package.

For API reference information, see the [CDK Toolkit Library API reference](https://docs.aws.amazon.com/cdk/api/toolkit-lib/).