When the Gatling JavaScript CLI runs a TypeScript simulation, what is it executing the simulation on, and what does that rule out when you add an npm library to the project?

It is easy to read `npm install`, `npx gatling run` and a `.ts` file and conclude that a Gatling JavaScript simulation is a Node program. It is not, and almost every operational surprise in this SDK follows from that one fact. ## What npm actually does here npm plays three roles, none of which is *running the test*: - it **resolves and installs** `@gatling.io/core`, `@gatling.io/http` and any protocol packages, so your source has something to import; - it **installs the CLI** as a dev dependency, so `npx gatling` resolves an executable inside the project; - it **installs your own toolchain** — formatters, linters, type-checking — which run over your source and nothing else. A hint of what lies underneath is visible in the dependency graph itself: `@gatling.io/core` and `@gatling.io/http` both pull a shared package called `@gatling.io/jvm-types`. The npm packages are the authoring surface; they are not the load generator. ## Where the engine comes from The `gatling` CLI needs internet access to **automatically download the Gatling runtime bundle required to execute your simulations**, published on Gatling's `gatling-js` releases. By default it installs into: | platform | default location | override | |---|---|---| | Linux / macOS | `~/.gatling` | `--gatling-home` | | Windows | `%USERPROFILE%\.gatling` | `--gatling-home` | Because that directory is **outside your project**, it is shared across every Gatling JavaScript project on the machine and survives deleting `node_modules`. It also has to match the SDK version in `package.json`, which is another reason the `@gatling.io` packages move as one. ## The two dependency rules, and what they follow from You may add other npm libraries to a simulation project, **as long as**: 1. they do **not rely on native (non-JavaScript) binaries**; and 2. they do **not use JavaScript APIs which are specific to Node.js**. Both rules say the same thing from two directions: your simulation code is evaluated by the Gatling runtime bundle, not by the Node process that launched the CLI. A library that shells out to a compiled addon has nothing to bind to, and one that reaches for Node's own APIs is assuming a host that is not there. Pure-JavaScript utilities — date formatting, string generation, data shaping — are the safe shape. Dev dependencies are outside this entirely. Gatling's demo projects ship a Prettier configuration precisely because formatting your source never runs inside the load test. ## Working on a restricted machine The download is the part that surprises people on locked-down networks. Three facts cover almost every case: 1. **Proxies are inherited from npm.** The CLI picks up npm's proxy configuration when run through `npx gatling`, whether that comes from `HTTP_PROXY` / `HTTPS_PROXY` / `NOPROXY` or from a `.npmrc` — there is no separate Gatling proxy setting to configure. 2. **The bundle can be installed by hand.** Download the release archive matching the version pinned in `package.json` **and** your machine's system type and architecture, then run `npx gatling install <path-to-downloaded-file.zip>`. 3. **The cache can be relocated.** `--gatling-home` moves it, which matters when the home directory is small, shared, or wiped between sessions. ## What this changes about how you think about the SDK - **"It works on my laptop" has a new failure mode**: a machine that has already cached a bundle behaves differently from one that has not, and the difference is a network call, not your code. - **Library choice is a design constraint, not a preference.** Screen a candidate dependency against the two rules before you build test data tooling on top of it, because discovering the constraint after the helper library is embedded is expensive. - **Version drift is now two-sided**: the npm packages and the downloaded runtime both carry a version, and the documented upgrade procedure — bump `core`, `http` and `cli` together, reinstall — is what keeps them aligned. - **A dependency review is worth doing once, up front.** Transitive dependencies count as much as direct ones, so a small, apparently pure helper that pulls in a native module is the case that catches teams out — screen the tree, not just the package you chose. Note the boundary of what any of this tells you: it describes what the tooling installs and what the documentation permits. Precisely how the runtime evaluates a given library at run time is not something the packaging documentation states, so treat the two dependency rules as the contract and verify a borderline library by trying it rather than by reasoning about internals.