If at any point you would like some help, join us in Slack! You'll find members of the AppMap team there, along with other AppMap users.

Add AppMap to a project

Install the AppMap extension for your code editor

AppMap for Visual Studio Code

The AppMap extension is listed on the Visual Studio Code Marketplace.

  1. Open extensions from the sidebar in Visual Studio Code
  2. Type ‘AppMap’ into the search bar
  3. Click to install

Install from the VS Code Marketplace

AppMap for JetBrains IDEs

The AppMap plugin has official support for IntelliJ, PyCharm, and RubyMine listed on the JetBrains Marketplace.

  1. Start your JetBrains IDE and open Preferences
  2. Open Plugins / Marketplace
  3. Search for AppMap, select and install AppMap

Install from the JetBrains Marketplace

“Start with AppMap” (Java + IntelliJ users only)

If you’re programming in Java using IntelliJ, you can make AppMaps using the extension command “Start with AppMap”.

See AppMap for JetBrains - Start with AppMap for more information.

Install and configure the AppMap client library (for everyone else)

To make AppMaps, you’ll need to install and configure the AppMap client library for your programming language. The AppMap client library is a package (Ruby gem, Python / JavaScript / Java package) that you install using your dependency manager (Rubygems, Pip, Npm, Yarn, Maven, Gradle, etc).

The easiest way to get setup is to use the the command-line installation and configuration utility npx @appland/appmap@latest install. This installer requires Node.js - so if you don’t have Node installed and you don’t want to install it, you can follow the manual installation procedure.

Command-line installer

Open a terminal window in the top level folder of your project and run this command:

npx @appland/appmap@latest install

You will be guided through a series of steps for installing and configuring AppMap, that will look something like this:

$ npx @appland/appmap@latest install
Need to install the following packages:
  @appland/appmap@3.50.1
Ok to proceed? (y)
✔ Installing AppMap...
? Commit these files to your repo so that everyone on your team can use AppMap
  without them having to repeat the setup process. Bring runtime code analysis
  to your whole team!
  Gemfile
  Gemfile.lock
  appmap.yml

  Commit? Yes
✔ Validating the AppMap configuration...

   ╭─────────────────────────────────────────────────────────────────────╮
   │                                                                     │
   │              Success! AppMap has finished installing.               │
   │                                                                     │
   │                      NEXT STEP: Record AppMaps                      │
   │                                                                     │
   │   You can consult the AppMap documentation, or continue with the    │
   │     instructions provided in the AppMap code editor extension.      │
   │                                                                     │
   ╰─────────────────────────────────────────────────────────────────────╯

The installer changes your project’s build process (yarn.lock for Javascript, Gemfile for Ruby, etc) to run AppMap when the tests run and when developing locally. It doesn’t affect production.

Commit AppMap to Git — setup AppMap for your team

Once you’ve installed and configured AppMap for a project, you’ll see that the following files are locally modified:

  • Package manager files (Gemfile, requirements.txt, package.json, etc).
  • appmap.yml - the AppMap configuration file.

Commit these changes to your repo, so that the rest of your team can use AppMap without having to repeat the setup process.

Node.js requirements for install

AppMap installer requires Node.js version 14+

Node.js (usually referred to simply as “Node”) is a widely-used open source implementation of JavaScript for desktop and server environments.

The AppMap CLI relies on a tool called npx. npx is included in all modern Node.js installations, so installing Node.js will also install npx automatically.

Checking if you have Node.js or nvm installed

You can check to see if you have Node.js installed (and which version is present, if any) by running this in your terminal:

node  -v

If this command prints a version like v16.15.0 or similar, and the version is newer than v14, you very likely have the right version of Node.js installed, continue your AppMap installation.

If you do not have Node.js installed, or if you have a version that is older than version v14 then you should first install nvm, the Node.js Version Manager.

Installing nvm

We recommend that you use Node.js Version Manager (nvm) to install Node.js on your machine. Nvm makes managing and installing different versions of Node.js very simple.

First, check to see if nvm is already installed on your system using this command:

nvm -v

If you do not have nvm installed, follow the instructions for installing nvm (Mac/Linux) or nvm-windows (Windows).

Once you have nvm installed, use this commands to install and use the latest ‘long term support’ version of Node.js:

nvm install --lts

Now that you have Node.js installed you will also now have npx installed. You can continue with your AppMap installation.

Manual installation

The AppMap installer is a convenient way to install and configure AppMap. If you prefer to install and configure AppMap manually, you can do so using the instructions below.


Was this page helpful? thumb_up Yes thumb_down No
Thank you for your feedback!