Thank you for taking the time to contribute to Trigger.dev. Your involvement is not just welcomed, but we encourage it! 🚀
Please take some time to read this guide to understand contributing best practices for Trigger.dev.
Thank you for helping us make Trigger.dev even better! 🤩
The development branch is main
. This is the branch that all pull
requests should be made against. The changes on the main
branch are tagged into a release monthly.
- Node.js version >=16.x
- pnpm package manager version 7
- Docker
-
Clone the repo into a public GitHub repository or fork the repo. If you plan to distribute the code, keep the source code public to comply with the Apache Licence 2.0.
git clone https://github.com/<github_username>/trigger.dev.git
If you are on windows, run the following command on gitbash with admin privileges:
git clone -c core.symlinks=true https://github.com/<github_username>/trigger.dev.git
-
Navigate to the project folder
cd trigger.dev
-
Install the required packages using pnpm.
pnpm i
-
Create your
.env
filecp .env.example .env
-
Open it and generate a new value for
ENCRYPTION_KEY
:ENCRYPTION_KEY
is used to two-way encrypt OAuth access tokens and so you'll probably want to actually generate a unique value, and it must be a random 16 byte hex string. You can generate one with the following command:openssl rand -hex 16
Feel free to update
SESSION_SECRET
andMAGIC_LINK_SECRET
as well using the same method. -
Start Docker. This starts the required services like Postgres. If this is your first time using Docker, consider going through this guide
pnpm run docker
This will also start and run a local instance of pgAdmin on localhost:5480, preconfigured with email
admin@example.com
and pwdadmin
. Then usepostgres
as the password to the Trigger.dev server. -
Migrate the database
pnpm run db:migrate
-
Build the app
pnpm run build --filter webapp
-
Run the seed script
pnpm run db:seed
-
Run the app. See the section below.
-
You can run the app with:
pnpm run dev --filter webapp
It should run on port
3030
: http://localhost:3030 -
Once the app is running click the magic link button and enter your email.
-
Check your terminal, the magic link email should have printed out as following:
webapp:dev: Log in to Trigger.dev webapp:dev: webapp:dev: Click here to log in with this magic link webapp:dev: [http://localhost:3030/magic?token=U2FsdGVkX18OvB0JxgaswTLCSbaRz%2FY82TN0EZWhSzFyZYwgG%2BIzKVTkeiaOtWfotPw7F8RwFzCHh53aBpMEu%2B%2B%2FItb%2FcJYh89MSjc3Pz92bevoEjqxSQ%2Ff%2BZbks09JOpqlBbYC3FzGWC8vuSVFBlxqLXxteSDLthZSUaC%2BS2LaA%2BJgp%2BLO7hgjAaC2lXbCHrM7MTgTdXOFt7i0Dvvuwz6%2BWY25RnfomZOPqDsyH0xz8Q2rzPTz0Xu53WSXrZ1hd] webapp:dev: webapp:dev: If you didn't try to log in, you can safely ignore this email.
Paste the magic link shown in your terminal into your browser to login.
-
Modify packages/database/prisma/schema.prisma file
-
Change directory to the packages/database folder
cd packages/database
-
Generate the Prisma client
pnpm run generate
The above updates the prisma client generated into node_modules/.prisma/client folder. This helps with typing of relevant prisma models. It ensures typescript recognizes fields added or removed from a model and type-checks appropriately.
-
Create and apply the migrations
pnpm run db:migrate:dev
This creates a migration file and executes the migrations against your database and applies changes to the database schema(s)
-
Commit generated migrations as well as changes to the schema.prisma file
-
If you're using VSCode you may need to restart the Typescript server in the webapp to get updated type inference. Open a TypeScript file, then open the Command Palette (View > Command Palette) and run
TypeScript: Restart TS server
.
To test CLI changes, follow the steps below:
- Build the CLI and watch for changes
cd packages/cli
pnpm run dev
-
Open a new Terminal window and run the webapp locally and then create a new project in the dashboard. Copy out the dev API key.
-
Create a new temporary Next.js app in references directory
cd ./references
pnpm create next-app@latest test-cli --ts --no-eslint --tailwind --app --src-dir --import-alias "@/*"
- Then once that's finished, add the
@trigger.dev/cli
to thedevDependencies
of the newly created Next.js app'spackage.json
file, like so:
{
// other package.json properties
"devDependencies": { "@trigger.dev/cli": "workspace:*" }
}
- Back in the terminal, navigate into the reference, and initialize the CLI. When prompted, select
self-hosted
and enterlocalhost:3030
if you are testing against the local instance of Trigger.dev, or you can just use the Trigger.dev cloud. When asked for an API key, use the key you copied earlier.
cd ./test-cli
pnpm i
pnpm exec trigger-cli init
- If you are just testing the
init
command, you can stop here. If you'd like to test thedev
command, first start the Next.js app on port 3000:
pnpm run dev
- Open a new terminal window, and then run the
dev
command like so:
pnpm exec trigger-cli dev
- Please remember to delete the temporary project you created after you've tested the changes, and before you raise a PR.
To run the end-to-end tests, follow the steps below:
- Set up environment variables (copy example envs into the correct place)
cp ./.env.example ./.env
cp ./references/nextjs-test/.env.example ./references/nextjs-test/.env.local
- Set up dependencies
# Build packages
pnpm run build --filter @references/nextjs-test^...
pnpm --filter @trigger.dev/database generate
# Move trigger-cli bin to correct place
pnpm install --frozen-lockfile
# Install playwrite browsers (ONE TIME ONLY)
npx playwright install
- Set up the database
pnpm run docker
pnpm run db:migrate
pnpm run db:seed
- Run the end-to-end tests
pnpm run test:e2e
The end-to-end tests use a setup
and teardown
script to seed the database with test data. If the test runner doesn't exit cleanly, then the database can be left in a state where the tests can't run because the setup
script will try to create data that already exists. If this happens, you can manually delete the users
and organizations
from the database using prisma studio:
# With the database running (i.e. pnpm run docker)
pnpm run db:studio
The references/job-catalog project defines simple jobs you can get started with.
cd
intoreferences/job-catalog
- Create a
.env
file with the following content, replacing<TRIGGER_DEV_API_KEY>
with an actual key:
TRIGGER_API_KEY=[TRIGGER_DEV_API_KEY]
TRIGGER_API_URL=http://localhost:3030
TRIGGER_API_URL
is used to configure the URL for your Trigger.dev instance,
where the jobs will be registered.
- Run one of the the
job-catalog
files:
pnpm run events
This will open up a local server using express
on port 8080. Then in a new terminal window you can run the trigger-cli dev command:
pnpm run dev:trigger
See the Job Catalog file for more.
- Navigate to your trigger.dev instance (http://localhost:3030), to see the jobs. You can use the test feature to trigger them.
If you get errors, be sure to fix them before committing.
- Be sure to check the "Allow edits from maintainers" option while creating you PR.
- If your PR refers to or fixes an issue, be sure to add
refs #XXX
orfixes #XXX
to the PR description. ReplacingXXX
with the respective issue number. See more about Linking a pull request to an issue . - Be sure to fill the PR Template accordingly.
We use changesets to manage our package versions and changelogs. If you've never used changesets before, first read their guide here.
If you are contributing a change to any packages in this monorepo (anything in either the /packages
or /integrations
directories), then you will need to add a changeset to your Pull Requests before they can be merged.
To add a changeset, run the following command in the root of the repo
pnpm run changeset:add
Here's an example of creating a patch
changeset for the @trigger.dev/github
and @trigger.dev/slack
packages (click to view):
You will be prompted to select which packages to include in the changeset. Only select the packages that you have made changes for.
Most of the time the changes you'll make are likely to be categorized as patch releases. If you feel like there is the need for a minor or major release of the package based on the changes being made, add the changeset as such and it will be discussed during PR review.
When receiving the following error message:
webapp:dev: Error: listen EADDRINUSE: address already in use :::3030
The process running on port 3030
should be destroyed.
- Get the
PID
of the process running on PORT3030
lsof -i :3030
- Kill the process
sudo kill -9 <PID>