# Install EZLogs in this Next.js app

Install the `ezlogs-nextjs` package (version 0.4.3 or newer). EZLogs turns requests, Server Actions, jobs and database changes into a plain-English activity log. Follow these steps exactly, change nothing else, then do the verify step.

## 1. Install the package

Use this project's package manager. Needs Node 18.17+ and Next.js 14+. Keep the version pin: if the install resolves to an older version, stop and tell me.

```bash
npm install ezlogs-nextjs@^0.4.3
# or: pnpm add ezlogs-nextjs@^0.4.3 / bun add ezlogs-nextjs@^0.4.3
```

## 2. Create `instrumentation.ts`

Put it at the project root, or at `src/instrumentation.ts` if the app uses the `src/` layout:

```ts
import { ezlogs } from "ezlogs-nextjs";

export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    ezlogs.init({
      projectToken: process.env.EZLOGS_PROJECT_TOKEN!,
    });
  }
}
```

If `instrumentation.ts` already exists, put the `ezlogs.init({...})` call inside the existing `register()`, in the `NEXT_RUNTIME === "nodejs"` branch. Export only one `register`.

## 3. Wrap the Next config

Wrap the existing config with `withEzlogsConfig`. Keep every existing option.

`next.config.ts`, `next.config.mjs` or ESM `next.config.js`:

```ts
import { withEzlogsConfig } from "ezlogs-nextjs/plugin";

export default withEzlogsConfig(nextConfig);
```

CommonJS `next.config.js`:

```js
const { withEzlogsConfig } = require("ezlogs-nextjs/plugin");
module.exports = withEzlogsConfig({ /* existing options */ });
```

It composes with other wrappers in either order, e.g. `withSentryConfig(withEzlogsConfig(nextConfig), { ... })`.

## 4. Set the environment variables

Add these to `.env.local` and to the hosting platform's environment variables (e.g. Vercel). Never commit the token.

```bash
EZLOGS_PROJECT_TOKEN=ezl_your_api_key_here
```

If the key above is still `ezl_your_api_key_here`, stop and ask me for my EZLogs API key (Settings → API keys at app.ezlogs.io). Never invent one.

## 5. Database changes

Only if the app uses Postgres (Supabase included); otherwise skip this step. `DATABASE_URL` (or `POSTGRES_URL`) must hold the Postgres connection string; if it is missing, ask me for it.

```bash
npm i pg
npx ezlogs-nextjs install-triggers
```

- Prisma: also use the extension.
  ```ts
  import { ezlogsPrisma } from "ezlogs-nextjs/prisma";
  export const prisma = new PrismaClient().$extends(ezlogsPrisma());
  ```
- postgres.js, or Drizzle on postgres-js: also wrap the `sql` instance, and pass the wrapped one to `drizzle(sql)`.
  ```ts
  import { wrapPostgresJs } from "ezlogs-nextjs/postgres";
  export const sql = wrapPostgresJs(postgres(process.env.DATABASE_URL!));
  ```
- Supabase (supabase-js), Drizzle on node-postgres, raw `pg`: nothing to wrap.

## 6. Background jobs

Only if the app uses BullMQ, Inngest, Trigger.dev, Supabase Queues (pgmq) or Upstash Workflow / QStash; otherwise skip this step. Wrap the runner exactly as https://github.com/dezsirazvan/ez_logs_agent_nextjs/blob/master/docs/jobs.md shows for it. If jobs run in a separate worker process (e.g. `node worker.js`), that process does not load `instrumentation.ts`: add `ezlogs.init({ projectToken: process.env.EZLOGS_PROJECT_TOKEN! })` at the top of the worker's entry file, before the worker starts, and create its database client the same way as in step 5.

## 7. Names for people

Records of people (users, members, customers) show by id unless `ezlogs.init` gets `displayNameFor`, e.g. `displayNameFor: { users: (row) => row.full_name ?? row.username }`. The key is the table name; use the table's real columns. Names show on shared links, so ask me before adding it.

## 8. Verify

Restart the dev server. The terminal must show this line once per server process:

```
[ezlogs] capturing → app.ezlogs.io (key ezl_XXXXXXXX…)
```

`ezl_XXXXXXXX` is the first 12 characters of `EZLOGS_PROJECT_TOKEN`.

- If it shows `[ezlogs] not capturing: projectToken missing` instead, the env var from step 4 is not loaded. Fix that and restart.
- Then call one of the app's API routes, or trigger a Server Action that writes to the database (e.g. submit a form). Events appear in EZLogs within a few seconds. Just opening a page shows nothing unless the app has a `middleware.ts` (or Next 16 `proxy.ts`), because page views are captured there.

Tell me which steps you did and paste the `[ezlogs]` line.

Reference: https://github.com/dezsirazvan/ez_logs_agent_nextjs#readme
