Skip to content

Set up the toolchain locally

In this tutorial we will get the dia-scripts toolchain running on your machine, ending with a green local check of a DIA Salesforce project. Work through the steps in order; each one produces a result you can see before we move on.

What we need first

We need five tools on your machine. Step 2 confirms their versions, so for now just have them installed:

  • Node.js >=22.22.3 — the engines floor in package.json; the CLI refuses to start below >=22. Install the latest Node LTS.
  • npm 11.19.0 or newer (npm install --global npm@latest).
  • Java 17+.
  • Salesforce CLI (sf).
  • Git.

Step 1 — Get the project

Clone your project and move into it:

git clone <your-project-repo-url>
cd <your-project>

You now have the project's source, including the scripts/dia-scripts/ toolchain, on disk.

Step 2 — Run setup

Run the toolchain's own setup command:

npm run setup

Watch the output: it prints each tool it checks and its version, then installs the npm dependencies exactly as pinned in the lockfile (the SF CLI plugins among them), links the plugins into sf, and configures the git hooks. If it stops and tells you a tool is missing or too old, install or upgrade that one tool and run npm run setup again. We continue only once it finishes cleanly.

Step 3 — Confirm the dia-scripts CLI runs

Ask one of the command groups to describe itself:

node ./scripts/dia-scripts/index.mjs ci --help

You will see the ci group's subcommands listed — auth-devhub, auth-deploy, install-tools, teardown, and the rest. Seeing them means the dia-scripts CLI loaded and your Node version is acceptable. (If instead you see a Node version error, your Node is below the required floor — install the required version and run this again.)

The root has no --help

node …/index.mjs --help prints nothing useful — ask a specific command or group for help instead, as above.

Step 4 — Check the toolchain works

We do not have a Salesforce org yet — we create one in the next tutorial — so we run only the checks that need no org: linting and the JavaScript (Jest) tests.

npm run lint
npm run test -- javascript

Both finishing cleanly is the result we are after: the toolchain runs on your machine. lint checks metadata, JavaScript, and markdown; the Jest run exercises the LWC tests, neither of which touches an org.

Do not run npm run validate yet — it needs an org.

Step 5 — See what a commit will run

The commit hook formats your staged changes and runs the lint you just saw. Run the formatter by hand once so you know what it does before it happens inside a commit:

npm run format:changed

format:changed reformats the files you have changed and prints their names. No output means nothing needed formatting. Either way, your commits will pass their checks rather than bounce.

For what the commit hook actually runs, see what happens when you commit.

What we did

The toolchain now runs on your machine: the dia-scripts CLI loads, lint and the JavaScript tests are green, and format works. From here, take a real change into an org in Deploy your first change to a scratch org.

When you want to understand how the toolchain is put together — the single dia-scripts CLI, and why the Node version matters — read The codebase and the CLI.