Next.js SDK

The Syntropy Next.js SDK provides server-side integrations, request context helpers, and server action wrappers.

npm install @eclosion-tech/syntropy-nextjs

1. Server Initialization

// instrumentation.ts (Next.js 13+)
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { Syntropy } = await import('@eclosion-tech/syntropy-nextjs');

    Syntropy.init({
      projectId: process.env.NEXT_PUBLIC_SYNTROPY_DSN!,
      release: process.env.npm_package_version,
      environment: process.env.NODE_ENV,
    });
  }
}

// next.config.js
module.exports = {
  experimental: {
    instrumentationHook: true,
  },
};

2. Client Initialization

Initialize the browser SDK for client-side errors and session replay:

// app/providers.tsx
'use client';

import { useEffect } from 'react';
import { Syntropy } from '@eclosion-tech/syntropy-browser';

export function Providers({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    Syntropy.init({
      projectId: process.env.NEXT_PUBLIC_SYNTROPY_DSN!,
      release: process.env.NEXT_PUBLIC_APP_VERSION,
      environment: process.env.NODE_ENV,
    });
  }, []);

  return <>{children}</>;
}

Server Actions

Use wrapServerAction to capture exceptions and include action context:

// app/actions.ts
'use server';

import { wrapServerAction } from '@eclosion-tech/syntropy-nextjs';

export const createUser = wrapServerAction(async (formData: FormData) => {
  // Throwing errors here will be captured automatically
  return { ok: true };
}, 'createUser');

Middleware Context

Use withSyntropy to add request/session context in Next middleware:

// middleware.ts
import { withSyntropy } from '@eclosion-tech/syntropy-nextjs';

export const middleware = withSyntropy();

API Routes

Manual capture in route handlers:

// app/api/example/route.ts
import { Syntropy } from '@eclosion-tech/syntropy-nextjs';

export async function GET() {
  try {
    const data = await fetchData();
    return Response.json(data);
  } catch (error) {
    if (error instanceof Error) {
      Syntropy.captureError(error, {
        tags: { route: '/api/example' },
      });
    }
    return Response.json({ error: 'Internal error' }, { status: 500 });
  }
}

Source Maps

Enable browser source maps in production and upload them to Syntropy:

// next.config.js
module.exports = {
  productionBrowserSourceMaps: true,
};

See Source Maps API.

Typed Project APIs

import { createSyntropyApiClient } from '@eclosion-tech/syntropy-nextjs';

const api = createSyntropyApiClient({
  baseUrl: 'https://syntropy.chat/api',
  apiKey: process.env.SYNTROPY_API_KEY,
});

await api.chatSchemas.list({
  organizationId: 'org_uuid',
  projectId: 'project_uuid',
});

See SDK API Client for the full API surface.