Skip to content

Development environment

Join our Discord

This page describes how to setup your development environment (Cloud or locally) to contribute to Powertools for AWS Lambda (TypeScript).

graph LR
    Dev["Development environment"] --> Quality["Run quality checks locally"] --> PR["Prepare pull request"] --> Collaborate
End-to-end process

Requirements

First time contributing to an open-source project ever?

Read this introduction on how to fork and clone a project on GitHub.

Unless you're using the pre-configured Cloud environment, you'll need the following installed:

  • GitHub account. You'll need to be able to fork, clone, and contribute via pull request.
  • Node.js 20.x. The repository contains an .nvmrc file, so if you use tools like nvm, fnm you can switch version quickly.
  • npm 10.x. We use it to install dependencies and manage the workspaces.
  • Docker. We use it to run documentation, and non-JavaScript tooling.
  • Fork the repository. You'll work against your fork of this repository.
Additional requirements if running end-to-end tests

Cloud environment

A word of caution

Before using a Cloud environment, be mindful of the pricing structure. You can find more information about each service pricing respectively on Gitpod and GitHub Codespaces pages. When in doubt, use the local environment below.

Once provisioned, each Cloud environment will come with all development dependencies and tools you'll need to contribute already installed.

Gitpod

To use a pre-configured Gitpod environment, create or login to a Gitpod account, then replace YOUR_USERNAME with your GitHub username or organization.

1
https://gitpod.io/#https://github.com/YOUR_USERNAME/powertools-lambda-typescript  #(1)!
  1. For example, if your username is octocat, then the final URL should be https://gitpod.io/#https://github.com/octocat/powertools-lambda-typescript

GitHub Codespaces

To use a pre-configured GitHub Codespaces environment, navigate to your fork of the repository, then click on the green Code button, and select Create codespace on <branch_name> under the Codespaces tab (where <branch_name> is the branch you want to work on).

Local environment

Assuming you've got all requirements.

You can use npm run setup-local to install all dependencies locally and setup pre-commit hooks.

Curious about what setup-local does under the hood?

We use npm scripts to automate common tasks locally and in Continuous Integration environments.

Local documentation

You might find useful to run both the documentation website and the API reference locally while contributing:

  • Docs website: npm run docs-runLocalDocker
    • If this is your first time running the docs, you need to build the image: npm run docs-buildDockerImage
  • API reference: npm run docs-api-build-run