open-index/open-npm huggingface dataset:
npm package: @openpanel/express
Description: The Express middleware is a basic wrapper around Javascript SDK. It provides a simple way to add the SDK to your Express application.
Latest version: 1.3.0

# Express

The Express middleware is a basic wrapper around Javascript SDK. It provides a simple way to add the SDK to your Express application.

> 📖 **Full documentation:** [https://openpanel.dev/docs/sdks/express](https://openpanel.dev/docs/sdks/express)

---

Looking for a step-by-step tutorial? Check out the [Express analytics guide](https://openpanel.dev/guides/express-analytics).

## Installation

```bash
pnpm install @openpanel/express
```

## Usage

The default export of `@openpanel/express` is a function that returns an Express middleware. It will also append the Openpanel SDK to the `req` object.

You can access it via `req.op`.

```ts
import express from 'express';

import createOpenpanelMiddleware from '@openpanel/express';

const app = express();

app.use(
  createOpenpanelMiddleware({
    clientId: 'xxx',
    clientSecret: 'xxx',
    // trackRequest(url) {
    //   return url.includes('/v1')
    // },
    // getProfileId(req) {
    //   return req.user.id
    // }
  })
);

app.get('/sign-up', (req, res) => {
  // track sign up events
  req.op.track('sign-up', {
    email: req.body.email,
  });
  res.send('Hello World');
});

app.listen(3000, () => {
  console.log('Server is running on http://localhost:3000');
});
```

### Options

##### Common options

- `apiUrl` - The url of the openpanel API or your self-hosted instance
- `clientId` - The client id of your application
- `clientSecret` - The client secret of your application (**only required for server-side events**)
- `filter` - A function that will be called before sending an event. If it returns false, the event will not be sent
- `disabled` - If true, the library will not send any events

#### Express options

- `trackRequest` - A function that returns `true` if the request should be tracked.
- `getProfileId` - A function that returns the profile ID of the user making the request.

## Working with Groups

Groups let you track analytics at the account or company level. Since Express is a backend SDK, you can upsert groups and assign users from your route handlers.

See the [Groups guide](https://openpanel.dev/docs/get-started/groups) for the full walkthrough.

```ts
app.post('/login', async (req, res) => {
  const user = await loginUser(req.body);

  // Identify the user
  req.op.identify({ profileId: user.id, email: user.email });

  // Create/update the group entity
  req.op.upsertGroup({
    id: user.organizationId,
    type: 'company',
    name: user.organizationName,
    properties: { plan: user.plan },
  });

  // Assign the user to the group
  req.op.setGroup(user.organizationId);

  res.json({ ok: true });
});
```

## Typescript

If `req.op` is not typed you can extend the `Request` interface.

```ts
import { OpenPanel } from '@openpanel/express';

declare global {
  namespace Express {
    export interface Request {
      op: OpenPanel;
    }
  }
}
```