This project is a "monorepo" meaning it contains several Node.js packages in one repository. The code for all packages are in the packages/
directory. We are using a concept called npm
workspaces to manage those multiple packages and a tool called changesets
to handle the versioning and releasing.
We welcome everyone to contribute to this project. If you don't know what to work on, check our open Issues and specifically for the Help Wanted
and Good First Issue
labels.
If you want to work on one of those open issues, please comment on the issue to let us know that you are working on it. Similarly if you can't work on it anymore, please let us know.
If you are planning to contribute something that does not have an open issue yet, please open an issue for it before you start working on it. This way we can help you find a good solution.
Make sure you have Node.js 18 or newer installed. Due to compatibility with Twilio Functions this project has to support at least Node.js 18.0.0.
We are using the npm CLI to manage our project. You'll need at least npm
version 8 or newer.
- Clone project and install dependencies
git clone https://github.com/twilio-labs/serverless-toolkit.git
cd serverless-toolkit
npm install
npm run bootstrap
- Perform changes. Check out Working with Workspaces for more info
- If you changed packages/plugins, run
twilio plugins:link <PATH_TO_THE_CHANGED_PACKAGE>
and then test the plugin locally by runningtwilio <PLUGIN_NAME> <COMMAND>
- Make sure tests pass by running
npm test
- Stage the files you changed by running
git add
with the files you changed. - If you have a customer facing change make sure to run
npm run changeset
at the root of the project, select what type of version change it is and which packages are impacted and describe the change. Check out "How we version" for more details. - Run
git commit
to kick off validation and enter your commit message. We are using conventional commits for this project. When you runnpm run cm
it will triggercommitizen
to assist you with your commit message. - Push your changes and submit a Pull Request
Working on your first Pull Request? You can learn how from this free series How to Contribute to an Open Source Project on GitHub
Version bumps are handled automatically by this GitHub Action whenever changes have been merged to main
. If the automation will detect any changeset files inside the .changeset
directory it will either open a new Pull Request to bump the version or force-push to the currently open Pull Request. In order to release to npm
you'll have to merge that Pull Request which will automatically kick off the release.
If the release fails, the issue might be in the NPM token expiring for twilio-labs-ci account. (For example a generic 404 not found response from NPM is usually token expiring) Current expiration is set for January 2026. Internal Slack channel for OSS support can help with the renewal.
All packages that are part of this project follow the SemVer convention. Specifically this means the following version changes apply for the following changes:
no change
(no changeset) - Changes indevDependencies
, changes at the root of the project that don't result in a compilation output change, test changes, documentation changes, etc.patch
- Any changes that do not add new features such as bug fixes that are not altering the behaviorminor
- New features that are additive and are not breaking current behaviormajor
- Any changes that are breaking changes incl. dropping support for features or arguments or drastic changes in behavior
npm will automatically link together the different dependencies that are part of the project when you run npm install
at the root.
Dev dependencies should ideally be installed at the top level using npm install --save-dev
. If you want to execute a binary from a dependency in a particular package you should install it in that particular package instead.
Installing dependencies for packages can be done in two ways. You can either use the npm install <package-name> -w <package-to-install-dependency-in>
command (ex. npm install lodash -w @twilio-labs/serverless-api
) or using npm install
inside the respective package.
The later might be the more intuitive one but it might cause some bootstraping issues.
Scripts that are on the top level can be run via npm run <script>
.
If you want to run a script in every individual package where it is defined you can run: npm run <script> --workspaces --if-present
.
To execute any bash command inside every package you can use npm exec
.
You can run npm run reset
to delete all node_modules
folder. To reinstall them run npm install
Please be aware that this project has a Code of Conduct. The tldr; is to just be excellent to each other ❤️
All third party contributors acknowledge that any contributions they provide will be made under the same open source license that the open source project is provided under.