Archiva Docs

Install `@archiva/archiva-nextjs`

Run the following command to install the Next.js SDK:

npm install @archiva/archiva-nextjs

Set up your API key

The SDK needs your Archiva API key to authenticate requests. For security, this key should never be exposed to the browser—it stays on your server where it's safe.

Create a .env file in your project root if you don't have one already.

Add your Archiva API key:

ARCHIVA_SECRET_KEY=pk_test_your_api_key_here

Restart your Next.js dev server after adding the environment variable, as environment variables are loaded at startup.

[!IMPORTANT]

Your API key should never be exposed to the browser. The SDK uses your API key on the server to generate short-lived tokens (90 seconds) that your frontend can use to fetch events. This way, your main API key never leaves your server, but your frontend can still display events to users.

Add `<ArchivaProvider>` to your app

The ArchivaProvider component provides Archiva's context to your app and enables the Timeline component to fetch and display events.

Add the ArchivaProvider component to your app's layout.

Copy and paste the following code into your app/layout.tsx file:

import { ArchivaProvider } from '@archiva/archiva-nextjs/react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ArchivaProvider>
          {children}
        </ArchivaProvider>
      </body>
    </html>
  );
}

[!IMPORTANT]

Always import ArchivaProvider from @archiva/archiva-nextjs/react (not from the root package). This ensures the import is server-safe and won't trigger Next.js React Server Component errors.

Create your frontend token endpoint

The SDK needs a route to generate short-lived tokens for your frontend. This route uses your server-side API key to create tokens that your frontend can use to fetch events.

Create a new API route file at app/api/archiva/frontend-token/route.ts.

Copy and paste the following code:

import { GET } from '@archiva/archiva-nextjs/server';

// Export the GET handler - that's it!
export { GET };

This endpoint will be used automatically by the SDK to fetch tokens for displaying events.

Create your first event

Use the createEvent server action to log an audit event from your server components or API routes:

import { createEvent } from '@archiva/archiva-nextjs';

// In a server component or API route
await createEvent({
  actionKey: 'invoice.update',
  entityType: 'invoice',
  entityId: 'inv_12345',
  actorType: 'user',
  actorId: 'usr_123',
});

Events are stored securely and can be displayed using the Timeline component.

Display events with the Timeline component

Add the <Timeline> component to display activity logs in your UI.

Copy and paste the following code into a client component:

'use client';

import { Timeline } from '@archiva/archiva-nextjs/react';

export default function ActivityPage() {
  return (
    <div>
      <h1>Activity Timeline</h1>
      <Timeline />
    </div>
  );
}

The Timeline component automatically fetches events from your Archiva project and displays them in a beautiful, scrollable timeline.

It's time to build!

You've added Archiva to your Next.js app 🎉. From here, you can continue developing your application and adding more event logging throughout your app.

To configure your Archiva project settings, visit your Archiva dashboard to manage events, configure actions, and view analytics.

Next steps

Create events with server actions
Learn how to use the createEvent and createEvents server actions to log audit events throughout your Next.js application.
Customize the Timeline component
Explore the Timeline component's props and options to customize how events are displayed in your application.
Configure ArchivaProvider
Learn about the ArchivaProvider component's configuration options, including custom API URLs and project scoping.
View a complete example
See a complete working example that demonstrates creating events and displaying them in a timeline.
Next.js SDK Reference
Explore the complete Next.js SDK documentation and learn about all available components and actions.
API Reference
Learn about the Archiva REST API and how to use it directly if needed.

Install @archiva/archiva-nextjs