# Setting up AppSignal for an ExpressJS based app

* [Prerequisites](#prerequisite):- Skip if you already have an API key and an account
* [Signup](#signup)
* [Create an organization name](#create-an-organization-name)
* [Getting API key](#getting-api-key)
* [Install and configure in your project](#installation)
* Installing packages
* [Installing packages manually](#installing-packages-manually)
* [Using CLI](#using-cli-skip-if-followed-above-step)
* [Placing the code in right place](#placing-the-code)

## Prerequisites

### Signup

To get started we first need to sign up on [AppSignal](https://appsignal.com/users/sign_up) to get the API key.

### Create an organization name
After logging in fo the for the first time you will be prompted to create or join an organisation.

An organization is used for billing and other important stuff, so lets create an Organization, which only requires a name.

After creating an organization, we will be redirected to a page which looks something like this:-

### Getting API key


**Since this is guide is for ExpressJS, we choose Node.js option.**

Which then reveals the API Key along with setup instructions.


## Install and configure in your project

Now choose the express project in which you want to setup AppSignal and `cd` into it.
For the purpose of this guide we are using [this repo](https://github.com/iam-Akshat/appsignal-demo) to follow along.

There are two ways of setting up the app, one involves using the `@appsignal/cli` package which automatically installs the required packages and gives the relevant code snippets to paste **or** manually installing the packages.

First we will demonstrate the manual way of doing it.

#### Installing packages manually

cd appsignal-demo
npm i @appsignal/nodejs @appsignal/express

In the `app.js` file we see

// Regular imports
const express = require('express')
const bodyParser = require('body-parser')
const morgan = require('morgan')

const todoRouter = require('./routes/todoRoutes')

// Instantiating 
const app = express()
const logger = morgan('short')


// using middlewares
app.use(logger)
app.use(bodyParser.urlencoded({ extended: true }))
app.use(express.json())



// using routes
app.use('/api/todo',todoRouter)


// Not a good error handler
...

#### Using CLI - Skip if followed above step

cd appsignal-demo
npx @appsignal/cli install

This will prompt the user for the following things.
- **Environment** choose nodejs
- **API KEY** paste the key aquired earlier
- **App name** the name of your app to identify it in dashboard, in this case we chose "todo"
- **Whether to install express integration package**, choose yes

Then it outputs the snippets of code to paste in your code.

#### Placing the code
Where we require and instantiate is critical to correctly setting up AppSignal.
We need to place the **require and instantiation code on top, before we import any other module or instantiate any object.**

const { Appsignal } = require("@appsignal/nodejs");
const appsignal = new Appsignal({
    active: true,
    name: "todo",
    pushApiKey: process.env.APPSIGNAL_PUSH_API_KEY || 'your API token'
  });
// Regular imports
...

`name` is the name we want to identify our app from, since an organization can contain many apps and services.
`pushApiKey` is the API key we aquired in previous steps.
We recommend using environment variables to store the API key.

To use the **express integration** we use the `expressMiddleware` middleware provided by `@appsignal/express` which can be imported anywhere but on top.

const { expressMiddleware }=require("@appsignal/express"); 

To set express app to use our middleware we need to place it
before any routes are being used and after any middlewares being setup.

...
// using middlewares
app.use(logger)
app.use(bodyParser.urlencoded({ extended: true }))
app.use(express.json())
// after setting up all middlewares
app.use(expressMiddleware(appsignal))

// before setting up any routes

// using routes
app.use('/api/todo',todoRouter)
...

#### Setting up express error handler
AppSignal express integration also comes with a middleware for handling express error. Change line 7 import to also import `expressErrorHandler`

const { expressMiddleware, expressErrorHandler } = require("@appsignal/express"); 

After your routes and custom error handlers place this

app.use(expressErrorHandler(appsignal))

### Explore the metrics
Basic setup is done, now when you run your app using `npm start` and navigate
to AppSignal dashboard you will be able to see your app with the name given, in our case **todo**.

[The sample app used in demo](https://github.com/iam-Akshat/appsignal-demo) has two branches, the `completed` branch contains the final code.

Congrats on successfully setting up AppSignal, enjoy the awesome metrics and insight into your app.