Next.js Integration

import { Aside } from ‘@astrojs/starlight/components’;

Client-side setup

Same as React — create a shared client and import it.

src/lib/gunsole.ts

import { createGunsoleClient } from "gunsole-js";

export const gun = createGunsoleClient({
  projectId: "my-nextjs-app",
  apiKey: "dev",
  mode: "local",
  defaultTags: {
    framework: "nextjs",
  },
});

Only import the client in client components (`"use client"`). The SDK uses browser APIs (`window`, `fetch`) that aren't available during SSR.

Server-side logging

For API routes and server components, create a separate client instance:

src/lib/gunsole-server.ts

import { createGunsoleClient } from "gunsole-js";

export const gunServer = createGunsoleClient({
  projectId: "my-nextjs-app",
  apiKey: "dev",
  mode: "local",
  defaultTags: {
    framework: "nextjs",
    runtime: "server",
  },
});

API Routes (App Router)

app/api/users/route.ts

import { gunServer } from "@/lib/gunsole-server";
import { NextResponse } from "next/server";

export async function GET() {
  const start = Date.now();
  const users = await db.query("SELECT * FROM users");

  gunServer.info({
    bucket: "api",
    message: `GET /api/users → 200`,
    context: { count: users.length, latencyMs: Date.now() - start },
    tags: { route: "/api/users", method: "GET", status: "200" },
  });

  return NextResponse.json(users);
}

Middleware

middleware.ts

import { gunServer } from "@/lib/gunsole-server";
import { NextResponse } from "next/server";

export function middleware(request) {
  gunServer.info({
    bucket: "middleware",
    message: `${request.method} ${request.nextUrl.pathname}`,
    tags: {
      path: request.nextUrl.pathname,
      method: request.method,
    },
  });

  return NextResponse.next();
}

Both runtimes, one project

Use the same projectId for client and server. In the desktop app, use the runtime tag to distinguish:

• runtime: "client" — browser logs
• runtime: "server" — Node.js logs

All logs from your Next.js app appear under one project, filterable by where they came from.