Nodemon ExecMap: One Config, Multiple Languages

Why execMap Matters for TypeScript Projects

When you run a Node.js server that contains plain JavaScript, Nodemon simply executes node on the target file. If you add TypeScript files, the default behaviour fails because node can’t interpret .ts syntax. You could keep separate scripts, like ts-node src/index.ts, but that adds clutter to your package.json and makes the restart logic hard to read.

ExecMap solves this by letting you declare, per file extension, which command Nodemon should launch. Once configured, changing a TypeScript file will automatically trigger ts-node, and you keep a single nodemon command in your workflow.

Setting Up execMap in nodemon.json

The recommended way to enable execMap is via a nodemon.json at the root of your project. This file is read automatically by Nodemon and keeps your restart logic declarative.

{
  "watch": ["src"],
  "ext": "js ts",
  "execMap": {
    "ts": "ts-node -r tsconfig-paths/register"
  }
}

Explanation of fields:

• watch – directories Nodemon monitors.
• ext – file extensions that trigger a restart.
• execMap – maps an extension to the command to run.

Running npx nodemon (or npm run dev if you alias it) will now execute ts-node for any .ts file that changes, while still handling .js files with the default node command.

Command‑Line Override: A Quick Way for One‑Off Experiments

If you’re testing a new setup and don’t want to commit to nodemon.json, you can pass --exec-map directly:

npx nodemon --watch src --ext js ts --exec-map ts=ts-node src/index.ts

Here, --exec-map ts=ts-node temporarily tells Nodemon to use ts-node for .ts files. This is handy for quick experiments or CI scripts.

Verifying the Configuration

1. Ensure ts-node and any required loaders (e.g., tsconfig-paths) are installed locally: npm i -D ts-node tsconfig-paths.
2. Start Nodemon: npx nodemon.
   • Check the console output; you should see a line similar to Watching path: src and execMap: ts => ts-node -r tsconfig-paths/register if you run with --verbose.
3. Modify a .ts file, e.g., add console.log('changed'); and save.
   • Node should restart automatically, printing the new log. If nothing happens, verify that the file extension is included in ext and that the command path is correct.

Running npx nodemon --verbose forces Nodemon to list every command it runs, which is invaluable for debugging a mis‑configured execMap entry.

Trade‑Offs and Limitations

• PATH dependency: The command specified in execMap must exist in the system PATH or be a relative path to a local binary. If ts-node is missing, Nodemon will silently fail to restart the process, leading to confusing “no output” situations.
• Complexity for newcomers: A heavily customized execMap can obscure the default restart logic. New team members may need to read nodemon.json to understand why a .ts file is launched with ts-node instead of plain node.
• Version compatibility: execMap has been stable since Nodemon 2.x, but older projects using Nodemon 1.x will need to upgrade to access the feature.
• Debugging overhead: When a mapped command crashes, the error output can be noisy. It’s often useful to add --inspect or other flags to the execMap entry for debugging sessions.

When to Use execMap

• Projects that mix JavaScript and TypeScript or other transpiled languages (e.g., CoffeeScript).
• Teams that want a single, consistent start command (e.g., npm run dev) without juggling multiple scripts.
• Environments where you need to enforce a specific runtime (e.g., ts-node --transpileOnly for faster restarts).

Actionable Takeaway

1. Add a nodemon.json with an execMap entry for each language you use. 2. Install the corresponding runtimes locally. 3. Run npx nodemon --verbose to confirm that the mapped command is being used. 4. Keep the execMap entry simple; if you need special flags, consider a wrapper script (e.g., scripts/run-ts.js) instead of embedding them directly.

With execMap, you turn Nodemon into a language‑agnostic watcher that automatically picks the right interpreter, reducing boilerplate and keeping your development workflow clean.