chore: use tsx for all Nx commands to be able to execute local plugins same as other projects

Author: BioPhoton

.env.example

@@ -1,2 +1,8 @@
-# for uploading to portal
+# Example environment variables
+# These are for reference only - use .env.local for local development
+
+# For uploading to Code PushUp portal
 CP_API_KEY=
+
+# Note: For local development with tsx/TypeScript execution,
+# copy .env.local.example to .env.local and configure NODE_OPTIONS there

.env.local.example

@@ -0,0 +1,12 @@
+# Local development environment variables
+# Copy this to .env.local (gitignored) and customize for your setup
+
+# Enable tsx for TypeScript execution in Nx
+# This allows running local generator/executor directly as .ts files without pre-compilation
+# This allowes the local plugins to import files with .js extensions (same as the packages in the repository)
+NODE_OPTIONS=--import tsx
+# This is used to resolve the paths in the local generator/executor so local packages can be imported as path aliases
+TSX_TSCONFIG_PATH=tsconfig.base.json
+
+# Local API keys (optional - only if testing upload features)
+# CP_API_KEY=your_api_key_here

.github/workflows/ci.yml

@@ -9,6 +9,8 @@ on:
 env:
   NX_NON_NATIVE_HASHER: true
   NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+  NODE_OPTIONS: --import tsx
+  TSX_TSCONFIG_PATH: tsconfig.base.json
 
 jobs:
   format:

.github/workflows/code-pushup-fork.yml

@@ -13,6 +13,8 @@ on:
 
 env:
   NX_NON_NATIVE_HASHER: true
+  NODE_OPTIONS: --import tsx
+  TSX_TSCONFIG_PATH: tsconfig.base.json
 
 permissions:
   pull-requests: write

.github/workflows/code-pushup.yml

@@ -9,6 +9,8 @@ on:
 env:
   NX_NON_NATIVE_HASHER: true
   NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+  NODE_OPTIONS: --import tsx
+  TSX_TSCONFIG_PATH: tsconfig.base.json
 
 permissions:
   pull-requests: write

.github/workflows/coverage.yml

@@ -7,6 +7,8 @@ on:
 env:
   NX_NON_NATIVE_HASHER: true
   NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+  NODE_OPTIONS: --import tsx
+  TSX_TSCONFIG_PATH: tsconfig.base.json
 
 jobs:
   list-packages:

.github/workflows/publish.yml

@@ -18,6 +18,8 @@ permissions:
 env:
   NX_NON_NATIVE_HASHER: true
   NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+  NODE_OPTIONS: --import tsx
+  TSX_TSCONFIG_PATH: tsconfig.base.json
 
 jobs:
   publish:

.github/workflows/release.yml

@@ -17,6 +17,8 @@ jobs:
     env:
       NX_NON_NATIVE_HASHER: true
       NX_CLOUD_ACCESS_TOKEN: ${{ secrets.NX_CLOUD_ACCESS_TOKEN }}
+      NODE_OPTIONS: --import tsx
+      TSX_TSCONFIG_PATH: tsconfig.base.json
     steps:
       - name: Authenticate as "Code PushUp Bot" GitHub App
         uses: actions/create-github-app-token@v2

.gitignore

@@ -1,6 +1,7 @@
 # See http://help.github.com/ignore-files/ for more about ignoring files.
 
 .env
+.env.local
 .npmrc
 
 # compiled output

CONTRIBUTING.md

@@ -16,11 +16,38 @@ npm install
 
 This table provides a quick overview of the environmental setup, with detailed explanations in the corresponding sections.
 
-| Feature                         | Local Default | CI Default       | Description                                                                                                                   |
-| ------------------------------- | ------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| `env.INCLUDE_SLOW_TESTS` **❗️** | `false`       | `true`           | Controls inclusion of long-running tests. Overridden by setting. Details in the [Testing](#Testing) section.                  |
-| `env.CUSTOM_CHROME_PATH`        | N/A           | Windows **❗️❗️** | Path to Chrome executable. See [plugin-lighthouse/CONTRIBUTING.md](./packages/plugin-lighthouse/CONTRIBUTING.md#chrome-path). |
-| Quality Pipeline                | Off           | On               | Runs all plugins against the codebase.                                                                                        |
+| Feature                         | Local Default       | CI Default                | Description                                                                                                                   |
+| ------------------------------- | ------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `NODE_OPTIONS` **⚙️**           | Set in `.env.local` | Set globally in workflows | `--import tsx` - Enables TypeScript execution for local Nx plugins and generators. **Required for development.**              |
+| `TSX_TSCONFIG_PATH` **⚙️**      | Set in `.env.local` | Set globally in workflows | `tsconfig.base.json` - Resolves TypeScript path aliases for local packages. **Required for development.**                     |
+| `env.INCLUDE_SLOW_TESTS` **❗️** | `false`             | `true`                    | Controls inclusion of long-running tests. Overridden by setting. Details in the [Testing](#Testing) section.                  |
+| `env.CUSTOM_CHROME_PATH`        | N/A                 | Windows **❗️❗️**          | Path to Chrome executable. See [plugin-lighthouse/CONTRIBUTING.md](./packages/plugin-lighthouse/CONTRIBUTING.md#chrome-path). |
+| Quality Pipeline                | Off                 | On                        | Runs all plugins against the codebase.                                                                                        |
+
+**⚙️** TypeScript Execution Setup (Required)
+
+This project uses local Nx plugins and generators written in TypeScript. To run them, you need:
+
+1. **Create `.env.local`** (gitignored, local-only):
+
+   ```sh
+   cp .env.local.example .env.local
+   ```
+
+2. **The file includes** (already configured in the example):
+
+   ```sh
+   NODE_OPTIONS=--import tsx
+   TSX_TSCONFIG_PATH=tsconfig.base.json
+   ```
+
+3. **Why these are needed**:
+   - `NODE_OPTIONS` - Allows importing TypeScript files with `.js` extensions (used throughout the repo)
+   - `TSX_TSCONFIG_PATH` - Enables path aliases like `@code-pushup/models` in generators/executors
+
+4. **CI Configuration**:
+   - Both variables are set **globally** in all GitHub Actions workflows
+   - Ensures consistent behavior between local development and CI
 
 **❗️** Test Inclusion Logic
 
@@ -66,7 +93,7 @@ Some of the plugins have a longer runtime. In order to ensure better DX, longer
 
 You can control the execution of long-running tests over the `INCLUDE_SLOW_TESTS` environment variable.
 
-To change this setup, open (or create) the `.env` file in the root folder.
+To change this setup, open your `.env.local` file in the root folder (or copy from `.env.local.example` if it doesn't exist).
 Edit or add the environment variable there as follows: `INCLUDE_SLOW_TESTS=true`.
 
 ## Git