Skip to main content
When you write TypeScript, your application runs compiled JavaScript from a dist/ directory — not the source files you edit in VS Code. If you place a probe on line 42 of src/handlers/user.ts, the agent needs to know which line in dist/handlers/user.js corresponds to that location. HyperProbe uses standard .map files generated by your TypeScript compiler or bundler to perform this mapping automatically, so you always work with your original source coordinates.

​
How source map resolution works

When the agent starts, one instance uploads the .map files from your build output to the HyperProbe backend. When you create a probe in VS Code pointing at a source file and line number, the backend uses the uploaded map to translate those coordinates into the compiled file and line that the running process actually executes. The agent instruments the compiled location — and the VS Code extension continues to display results in terms of the original source file.
Only one instance of the agent performs the upload. If multiple instances of your service are running, they coordinate automatically: one is designated as the uploader, the others poll until the upload is complete. This is handled entirely by the SDK — you do not need to configure it.

​
Prerequisites

Your build process must generate source map files (.map files) alongside your compiled output. HyperProbe requires standard V3 source maps; inline source maps embedded in the compiled file are not supported.

​
Step 1: Enable source maps in your build

Add "sourceMap": true to your tsconfig.json:
tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "outDir": "./dist",
    "sourceMap": true,
    "rootDir": "./src"
  }
}
After building with tsc, each .js file in dist/ has a corresponding .js.map file. These are the files HyperProbe reads.

​
Step 2: Set GIT_COMMIT in your deployment

The commitSha value is required for source map resolution. It acts as a key that associates the uploaded source maps with a specific build, preventing probe coordinates from one deployment being applied to a different one. Set GIT_COMMIT in your CI/CD pipeline or deployment configuration before the process starts: 
export GIT_COMMIT=$(git rev-parse HEAD)
node dist/index.js
If commitSha is missing or set to the string 'unknown', the agent will refuse to start and log a critical error. Always set GIT_COMMIT (or pass commitSha directly in the options) before deploying.

​
Step 3: Configure the SDK

Pass sourceMapDir and distLocation to HyperProbe.start. Both typically point to your build output directory.
src/index.ts
import { HyperProbe } from '@hyperprobe/node-sdk';

HyperProbe.start({
  serviceId: 'my-typescript-service',
  environment: 'production',
  brokerUrl: 'grpc://broker.example.com:50051',
  commitSha: process.env.GIT_COMMIT,

  sourceMapDir: './dist',  // directory where .map files are located
  distLocation: './dist',  // directory where compiled .js files are located
});
OptionEnv variableDescription
sourceMapDirHYPERPROBE_SOURCE_MAP_DIRDirectory where .map files are located. Defaults to process.cwd().
distLocationHYPERPROBE_DIST_LOCATIONDirectory where compiled .js files are located.
If sourceMapDir and distLocation are different (for example, if map files are published to a separate directory), set each path independently.

​
Verifying the upload

When source map upload succeeds, the agent logs the following at the hyperprobe:broker debug namespace: 
hyperprobe:broker Source map upload completed.
Enable debug logging by setting the DEBUG environment variable: 
DEBUG=hyperprobe:broker node dist/index.js
If the upload fails, the agent retries automatically. If another instance is already uploading, the current instance polls every 20 seconds until the upload is marked complete.

​
Project structure example

For a typical TypeScript project, your layout and configuration might look like this: 
my-service/
├── src/
│   ├── index.ts
│   └── handlers/
│       ├── user.ts
│       └── order.ts
├── dist/
│   ├── index.js
│   ├── index.js.map
│   └── handlers/
│       ├── user.js
│       ├── user.js.map
│       ├── order.js
│       └── order.js.map
├── tsconfig.json
└── package.json
With this structure, set: 
sourceMapDir: './dist',
distLocation: './dist',
When you place a probe on line 42 of src/handlers/user.ts, HyperProbe looks up the mapping in dist/handlers/user.js.map and instruments the correct line in dist/handlers/user.js.
Source maps do not need to be deployed alongside your application for production users. HyperProbe uploads them once per commit and stores them in the backend. You can strip .map files from your production Docker image after the agent has started and uploaded them, as long as the upload completes before the container is modified.