diff --git a/apps/docs/src/pages/docs/_meta.json b/apps/docs/src/pages/docs/_meta.json index c3475cc5..1843202b 100644 --- a/apps/docs/src/pages/docs/_meta.json +++ b/apps/docs/src/pages/docs/_meta.json @@ -12,6 +12,7 @@ "vue": "Vue", "astro": "Astro", "node": "Node (backend)", + "express": "Express (backend)", "-- Others": { "type": "separator", "title": "Others" diff --git a/apps/docs/src/pages/docs/express.mdx b/apps/docs/src/pages/docs/express.mdx new file mode 100644 index 00000000..ed75185d --- /dev/null +++ b/apps/docs/src/pages/docs/express.mdx @@ -0,0 +1,78 @@ +import Link from 'next/link'; +import { Callout, Steps, Tabs } from 'nextra/components'; +import { DeviceIdWarning } from 'src/components/device-id-warning'; +import { PersonalDataWarning } from 'src/components/personal-data-warning'; + +import SdkConfig from 'src/components/sdk-config.mdx'; + +# Express + +The Express middleware is a basic wrapper around [Javascript SDK](/docs/javascript). It provides a simple way to add the SDK to your Express application. + +## 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.event('sign-up', { + email: req.body.email, + }); + res.send('Hello World'); +}); + +app.listen(3000, () => { + console.log('Server is running on http://localhost:3000'); +}); +``` + +### Config + +- `clientId` - Your OpenPanel client ID. +- `clientSecret` - Your OpenPanel client secret. +- `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. + +## Typescript + +If `req.op` is not typed you can extend the `Request` interface. + +```ts +import { OpenpanelSdk } from '@openpanel/express'; + +declare global { + namespace Express { + export interface Request { + op: OpenpanelSdk; + } + } +} +```