docs: improve docs around bundlers/transpilers, methods of starting t…

…he agent (#2837)

- Re-write the 'Starting the agent' doc page: discuss all ways to start the
  agent, and discuss several gotchas.
- Update 'Support technologies' page with up-to-date node release schedule,
  and a section on the current ESM limitation.
- Drop es-modules.html in favor of the above.
- Add 'Get started with TypeScript' and add examples/typescript/.
- Add examples/esbuild/.
- Ensure 'npm run test:babel' fails if it doesn't use import apm from 'elastic-apm-node/start' to start the agent before other imports.

Co-authored-by: Brandon Morelli <brandon.morelli@elastic.co>

.eslintrc.json

@@ -14,6 +14,8 @@
     "/.nyc_output",
     "/build",
     "node_modules",
+    "/examples/esbuild/dist",
+    "/examples/typescript/dist",
     "/lib/opentelemetry-bridge/opentelemetry-core-mini",
     "/test/babel/out.js",
     "/test/lambda/fixtures/esbuild-bundled-handler/hello.js",

.gitignore

@@ -13,3 +13,4 @@
 node_modules
 /test/benchmarks/.tmp
 /tmp
+/examples/*/dist

docs/agent-api.asciidoc

@@ -7,22 +7,7 @@ endif::[]
 
 === `Agent` API
 
-NOTE: This is the API documentation for the Elastic APM Node.js Agent.
-For getting started,
-we recommend that you take a look at our framework specific documentation for either <<express,Express>>,
-<<hapi,hapi>>,
-<<koa,Koa>>,
-<<restify,Restify>>,
-<<fastify,Fastify>>,
-or <<custom-stack,custom frameworks>>.
-
-The Elastic APM agent for Node.js is a singleton.
-You get the agent instance by either requiring `elastic-apm-node` or `elastic-apm-node/start`.
-For details on the two approaches,
-see the <<advanced-setup,Setup and Configuration>> guide.
-
-The agent is also returned by the `start()` function,
-which allows you to require and start the agent on the same line:
+The Elastic APM Node.js agent is a singleton. You get the agent instance by requiring either `elastic-apm-node` or `elastic-apm-node/start`. The agent is also returned by the <<apm-start,`.start()`>> method, which allows you to require and start the agent on the same line:
 
 [source,js]
 ----
@@ -33,20 +18,15 @@ If you need to access the `Agent` in any part of your codebase,
 you can simply require `elastic-apm-node` to access the already started singleton.
 You therefore don't need to manage or pass around the started `Agent` yourself.
 
+
 [[apm-start]]
 ==== `apm.start([options])`
 
 Starts the Elastic APM agent for Node.js and returns itself.
 
 [IMPORTANT]
 ====
-Put the call to this function at the very top of your main app file - before requiring any other modules.
-
-If you are using Babel calling this function will not have the desired effect.
-See the <<es-modules,Babel / ES Modules support documentation>> for details.
-
-If you are using Typescript the import statement may be removed if it is not used.
-It is recommended to use `-r elastic-apm-node/start` when starting the app to avoid this.
+For the APM agent to automatically instrument Node.js modules, it must be started before those modules are loaded. See <<starting-the-agent>> for details and possible surprises with compilers/transpilers/bundlers.
 ====
 
 See the <<configuration,Configuration documentation>> for available options.

docs/configuration.asciidoc

@@ -33,7 +33,6 @@ will be normalized to the allowed characters. If the name cannot be inferred
 from package.json, then a fallback value of "unknown-nodejs-service" is used.
 
 
-[float]
 [[service-node-name]]
 ==== `serviceNodeName`
 

docs/redirects.asciidoc

@@ -41,4 +41,12 @@ This endpoint has moved. Please see <<transaction-add-labels>>.
 [role="exclude",id="get-started"]
 === Get started
 
-This page has moved. Please see <<set-up>>.
+This page has moved. Please see <<set-up>>.
+
+[role="exclude",id="es-modules"]
+=== ES Modules support
+
+This page has moved.
+
+- For details on ES Modules (ESM) support, see <<compatibility-esm>>.
+- For information on using the APM agent with TypeScript, see <<typescript>>.