Add —env-file support to dev and deploy

Author: ericallam

docs/guides/new-build-system-preview.mdx

@@ -39,6 +39,8 @@ If you've added the `trigger.dev` CLI to your `devDependencies`, then you should
 
 Once you do that make sure you re-install your dependencies using `npm i` or the equivalent with your preferred package manager.
 
+<Note>If you deploy using GitHub actions, make sure you update the version there too.</Note>
+
 ## Update your `trigger.config.ts`
 
 The new build system does not effect your trigger task files at all, so those can remain unchanged. However, you may need to make changes to your `trigger.config.ts` file.
@@ -315,6 +317,88 @@ export default defineConfig({
 });
 ```
 
+## Changes to the `trigger.dev` CLI
+
+### No more typechecking during deploy
+
+We no longer run typechecking during the deploy command. This was causing issues with some projects, and we found that it wasn't necessary to run typechecking during the deploy command. If you want to run typechecking before deploying to Trigger.dev, you can run the `tsc` command before running the `deploy` command.
+
+```sh
+tsc && npx [email protected] deploy
+```
+
+Or if you are using GitHub actions, you can add an additional step to run the `tsc` command before deploying to Trigger.dev.
+
+```yaml
+- name: Install dependencies
+  run: npm install
+
+- name: Typecheck
+  run: npx tsc
+
+- name: 🚀 Deploy Trigger.dev
+  env:
+    TRIGGER_ACCESS_TOKEN: ${{ secrets.TRIGGER_ACCESS_TOKEN }}
+  run: |
+    npx [email protected] deploy
+```
+
+### deploy --dry-run
+
+You can now inspect the build output of your project without actually deploying it to Trigger.dev by using the `--dry-run` flag:
+
+```sh
+npx [email protected] deploy --dry-run
+```
+
+This will save the build output and print the path to the build output directory. If you face any issues with deploying, please include the build output in your issue report.
+
+### --env-file
+
+You can now pass the path to your local `.env` file using the `--env-file` flag during `dev` and `deploy` commands:
+
+```sh
+npx [email protected] dev --env-file ../../.env
+npx [email protected] deploy --env-file ../../.env
+```
+
+The `.env` file works slightly differently in `dev` vs `deploy`:
+
+- In `dev`, the `.env` file is loaded into the CLI's `process.env` and also into the environment variables of the Trigger.dev environment.
+- In `deploy`, the `.env` file is loaded into the CLI's `process.env` but not into the environment variables of the Trigger.dev environment. If you want to sync the environment variables from the `.env` file to the Trigger.dev environment variables, you can use the `syncEnvVars` build extension.
+
+### dev debugging in VS Code
+
+Debugging your tasks code in `dev` is now supported via VS Code, without having to pass in any additional flags. Create a launch configuration in `.vscode/launch.json`:
+
+```json launch.json
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Trigger.dev: Dev",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceFolder}",
+      "runtimeExecutable": "npx",
+      "runtimeArgs": ["[email protected]", "dev"],
+      "skipFiles": ["<node_internals>/**"],
+      "sourceMaps": true
+    }
+  ]
+}
+```
+
+Then you can start debugging your tasks code by selecting the `Trigger.dev: Dev` configuration in the debug panel, and set breakpoints in your tasks code.
+
+### TRIGGER_ACCESS_TOKEN in dev
+
+You can now authenticate the `dev` command using the `TRIGGER_ACCESS_TOKEN` environment variable. Previously this was only supported in the `deploy` command.
+
+```sh
+TRIGGER_ACCESS_TOKEN=<your access token> npx [email protected] dev
+```
+
 ## Known issues
 
 - Path aliases are not yet support in your `trigger.config.ts` file. To workaround this issue you'll need to rewrite path aliases to their relative paths. (See [this](https://github.com/unjs/jiti/issues/166) and [this](https://knip.dev/reference/known-issues#path-aliases-in-config-files)) for more info.

packages/cli-v3/src/commands/deploy.ts

@@ -69,6 +69,7 @@ const DeployCommandOptions = CommonCommandOptions.extend({
   saveLogs: z.boolean().default(false),
   skipUpdateCheck: z.boolean().default(false),
   noCache: z.boolean().default(false),
+  envFile: z.string().optional(),
 });
 
 type DeployCommandOptions = z.infer<typeof DeployCommandOptions>;
@@ -100,6 +101,10 @@ export function configureDeployCommand(program: Command) {
         "--skip-sync-env-vars",
         "Skip syncing environment variables when using the syncEnvVars extension."
       )
+      .option(
+        "--env-file <env file>",
+        "Path to the .env file to load into the CLI process. Defaults to .env in the project directory."
+      )
   )
     .addOption(
       new CommandOption(
@@ -209,7 +214,7 @@ async function _deployCommand(dir: string, options: DeployCommandOptions) {
   }
 
   const serverEnvVars = await projectClient.client.getEnvironmentVariables(resolvedConfig.project);
-  loadDotEnvVars(resolvedConfig.workingDir);
+  loadDotEnvVars(resolvedConfig.workingDir, options.envFile);
 
   const destination = getTmpDir(resolvedConfig.workingDir, "build", options.dryRun);
   const externalsExtension = createExternalsBuildExtension("deploy", resolvedConfig);

packages/cli-v3/src/commands/dev.ts

@@ -17,6 +17,7 @@ const DevCommandOptions = CommonCommandOptions.extend({
   config: z.string().optional(),
   projectRef: z.string().optional(),
   skipUpdateCheck: z.boolean().default(false),
+  envFile: z.string().optional(),
 });
 
 export type DevCommandOptions = z.infer<typeof DevCommandOptions>;
@@ -32,6 +33,10 @@ export function configureDevCommand(program: Command) {
         "-p, --project-ref <project ref>",
         "The project ref. Required if there is no config file."
       )
+      .option(
+        "--env-file <env file>",
+        "Path to the .env file to use for the dev session. Defaults to .env in the project directory."
+      )
       .option("--debug-otel", "Enable OpenTelemetry debugging")
       .option("--skip-update-check", "Skip checking for @trigger.dev package updates")
   ).action(async (_, options) => {

packages/cli-v3/src/dev/workerRuntime.ts

@@ -229,7 +229,7 @@ class DevWorkerRuntime implements WorkerRuntime {
     );
 
     const processEnv = gatherProcessEnv();
-    const dotEnvVars = resolveDotEnvVars();
+    const dotEnvVars = resolveDotEnvVars(undefined, this.options.args.envFile);
     const OTEL_IMPORT_HOOK_INCLUDES = getInstrumentedPackageNames(this.options.config).join(",");
 
     const stripEmptyValues = (obj: Record<string, string | undefined>) => {

packages/cli-v3/src/utilities/dotEnv.ts

@@ -4,12 +4,16 @@ import { env } from "std-env";
 
 const ENVVAR_FILES = [".env", ".env.development", ".env.local", ".env.development.local"];
 
-export function resolveDotEnvVars(cwd?: string) {
+export function resolveDotEnvVars(cwd?: string, envFile?: string) {
   const result: { [key: string]: string } = {};
 
+  const envFilePath = envFile
+    ? resolve(cwd ?? process.cwd(), envFile)
+    : ENVVAR_FILES.map((p) => resolve(cwd ?? process.cwd(), p));
+
   dotenv.config({
     processEnv: result,
-    path: ENVVAR_FILES.map((p) => resolve(cwd ?? process.cwd(), p)),
+    path: envFilePath,
   });
 
   env.TRIGGER_API_URL && (result.TRIGGER_API_URL = env.TRIGGER_API_URL);
@@ -21,8 +25,12 @@ export function resolveDotEnvVars(cwd?: string) {
   return result;
 }
 
-export function loadDotEnvVars(cwd?: string) {
+export function loadDotEnvVars(cwd?: string, envFile?: string) {
+  const envFilePath = envFile
+    ? resolve(cwd ?? process.cwd(), envFile)
+    : ENVVAR_FILES.map((p) => resolve(cwd ?? process.cwd(), p));
+
   dotenv.config({
-    path: ENVVAR_FILES.map((p) => resolve(cwd ?? process.cwd(), p)),
+    path: envFilePath,
   });
 }