Backpack

Appearance

Migrating an existing project to Backpack ​

This migration guide explains how to migrate your existing project to Backpack.

Basics ​

Let's begin with some basics that require minimal changes to your code.

Upgrade to Node.js v22 ​

Backpack expects Node.js v22 for both local development and your Lambda runtime.

  • Install Node.js v22 on your machine (using Homebrew, n, or nvm).
  • In your project, ensure aws-cdk-lib is upgraded to v2.168.0 or higher.
  • Update the runtime of your Lambda CDK construct to NODEJS_22_X.
  • Use "es2023" for the lib option in your tsconfig.json.

Start using ES modules ​

It is recommended to switch to ECMAScript modules (ESM).

  • Add "type": "module" to your package.json.
  • Configure your Lambda bundling options to output ES modules with format: OutputFormat.ESM.
  • Update your code to be ESM-compliant (e.g. instead of use Node.js global __dir, use import.meta.dirname)

For more details, see our guide on ES modules.

Migrate to Vitest ​

If you are still using Jest for testing, you may run into some issues with ES modules. This is because its support for ECMAScript modules is still experimental and requires a specific setup.

We recommend replacing Jest with Vitest, a modern testing tool with built-in support for TypeScript and ESM. It requires minimal configuration, has fewer dependencies, and runs faster.

Migrating from Jest to Vitest is simple, as Vitest closely resembles Jest’s API.

Adopt TypeScript practices ​

You can simplify your tsconfig.json setup by using one of the presets provided by @backpack/typescript-config.

jsonc
{
  "extends": "@backpack/typescript-config/bundler",
  "include": ["**/*.ts"],
  "compilerOptions": {
    // Overrides if needed
  }
}

This approach ensures reasonable defaults, while still allowing you to override settings as necessary.

Use ESLint with Prettier ​

This step is optional, especially if you're satisfied with your current ESLint setup. However, if you already use many of the "recommended" presets and aim to reduce dependency clutter, consider adopting @backpack/eslint-config:

javascript
import backpack from "@backpack/eslint-config";
import tseslint from "typescript-eslint";

export default tseslint.config(
  ...backpack.configs.recommended,
  {
    rules: {
      // Additional rule overrides here...
    },
  }
);

This config includes reasonable default presets, but you can still customise or extend it.

Additionally, we recommend Prettier for consistent code formatting. You might also consider adding a pre-commit hook to enforce this.

TIP

Looking for examples?
Here are some pull requests showcasing the migration process:

Migrate your code ​

Once the basics are in place, you can begin adopting Backpack libraries and best practices.

Improve app configuration ​

If you are relying on global environment variables, consider reorganising your app to use a single (externalised) source for configuration. This approach streamlines environment management, makes setting up integration tests easier, and simplifies local development.

See our in-depth guide on configuration and secrets.

Use dependency injection ​

Improving your codebase by applying inversion of control patterns or using a dependency injection library is another step to consider. Although not mandatory, these practices improve maintainability and reduce boilerplate code.

For more information, see our guide on dependency injection.

AWS Lambda utilities ​

Backpack offers the @backpack/aws-lambda library, which contains utilities to enhance your Lambda functions, especially for REST APIs.

Refer to the API documentation of @backpack/aws-lambda.

Other AWS utilities ​

Backpack also provides libraries for working with AWS services like Secrets Manager, DynamoDB, and S3. You can explore all our AWS packages.

If you are currently using utilities from @ns/common-serverless-library, consider migrating to their Backpack counterparts.

Refer to the dedicated migration guide for details.

TIP

Looking for examples?
Here are some pull requests demonstrating migrations:

Find more inspiration ​

Demo projects ​

Explore our demo projects to find ideas and examples.

How-to guides ​

Check the how-to guides and learn how you can use Backpack for building apps.

CDK snippets ​

Check out the CDK snippets for examples of common CDK constructs.

Collaborate! ​

Finally, collaborate with us!

If you have suggestions for Backpack, such as new utilities or best practices, submit a pull request or join the discussion on our Slack channel.