Get started with TypeScript
editGet started with TypeScript
editThe Elastic APM Node.js agent is implemented in vanilla JavaScript, but includes TypeScript types. This document shows how to integrate the APM agent with your TypeScript project.
A small, complete example project can be found here.
Installation
editAdd elastic-apm-node
as a dependency to your application, and possibly @types/node
as a dev-dependency for type checking:
Installing |
tsconfig compiler options
editThe TypeScript authors strongly recommend that you use the "esModuleInterop": true
option in your "tsconfig.json". In case you do not, then the "default" import of the agent will not work, so instead of using import apm from 'elastic-apm-node/start'
or similar, you will have to use:
import * as apm from 'elastic-apm-node/start' // if using esModuleInterop:false
Currently the Elastic APM Node.js agent does not support instrumenting ECMA Script modules (ESM), so for full APM support you will need to tell TypeScript to generate JavaScript using CommonJS modules via the "module": "commonjs"
compiler option.
// tsconfig.json { "compilerOptions": { "module": "commonjs", "esModuleInterop": true, "moduleResolution": "node" // ... } }
The current TypeScript recommended tsconfigs for node use options that work with the APM agent.
Starting the agent
editFor the APM agent to be able to automatically instrument modules it must be started before you import other modules. This means that you should probably import and start the agent in your application’s main file (usually index.js
, server.js
or app.js
). One way to do this is as follows.
This start method requires you to use environment variables to configure the agent. See Starting the agent for all the ways to start the agent. |
Pay special attention to the possible surprise gotcha where the TypeScript compiler can throw away your import in the generated JavaScript.
Next steps
editThe APM agent will now trace your application, monitor performance, and record any uncaught exceptions. Refer to the following documentation to configure and use the APM agent.
If you can’t get the Node.js agent to work as expected, please follow the troubleshooting guide.