> For the complete documentation index, see [llms.txt](https://docs.logsnag.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.logsnag.com/sdks/next.md).
# Next
### Installation
#### Using npm
```bash
npm install @logsnag/next
```
#### Using yarn
```bash
yarn add @logsnag/next
```
#### Using pnpm
```bash
pnpm add @logsnag/next
```
### Usage
The usage depends on whether you are using the app directory structure or the pages directory structure.
> Set your token's scope to `public` in the LogSnag dashboard
**App Directory:**
In the app directory, you need to import the LogSnagProvider as a head element in your root layout component:
```tsx
import { LogSnagProvider } from '@logsnag/next';
export default function RootLayout({
children
}: {
children: React.ReactNode;
}) {
return (
{/* Other head elements */}
{/* Your layout */}
{children}
);
}
```
For setting the user id in server components, use the `SetUserIdServerComponent`:
```tsx
import { SetUserIdServerComponent } from '@logsnag/next';
export default function Page() {
const userId: string | null = 'user-123';
return (
<>
{/* Your page content */}
);
}
```
**Pages Directory:**
In the pages directory, you can wrap your app with the LogSnagProvider, similar to how you would do in a React application:
```tsx
import { LogSnagProvider } from '@logsnag/next';
export default function App({ Component, pageProps }: AppProps) {
return (
{/* Your app content */}
);
}
```
### Hooks
The `useLogSnag` hook can be used across your client components and provides the following methods:
* `track(options: TrackOptions)`: Track custom events.
* `identify(options: IdentifyOptions)`: Identify user traits.
* `setUserId(userId: string | null)`: Set the user id for the current user. If the user is not logged in, pass null.
* `clearUserId()`: Clear the user id for the current user.
* `setDebug(flag: boolean = true)`: Set debug mode for logging.
**Usage:**
```tsx
"use client";
import { useLogSnag } from '@logsnag/next';
export function Component() {
// Get the hooks
const { setUserId, track, identify } = useLogSnag();
// Set the user id when user logs in
setUserId('user-123');
// Track an event
track({
channel: "payments",
event: "New Subscription",
user_id: "user-123", // optional when set using setUserId
icon: "💰",
notify: true,
tags: {
plan: "premium",
cycle: "monthly",
trial: false
}
});
// Identify user traits (e.g., name, email, plan, etc.)
identify({
user_id: "user-123", // optional when set using setUserId
properties: {
name: "John Doe",
email: "john@doe.com",
plan: "premium",
}
});
// Rest of your component
}
```
These hooks have the same usage as their counterparts in the [@logsnag/react](https://www.npmjs.com/package/@logsnag/react) package.
### Tracking Events
You can also track events directly from HTML elements using data attributes:
```jsx
```
In this example, when the button is clicked, an event named "Upgraded Plan" will be tracked with the specified tags.
### Server-side Usage with Next
For server-side usage, you can use LogSnag from `@logsnag/next/server` It behaves similarly to [`@logsnag/node`](https://www.npmjs.com/package/@logsnag/node)
> Use a different token for server-side usage and set its scope to `private` in the LogSnag dashboard.
```typescript
import { LogSnag } from '@logsnag/next/server';
// Initialize LogSnagServer
const logsnag = new LogSnag({
token: '',
project: '',
});
// Use it in your server-side code
// Track an event
await logsnag.track({
channel: "payments",
event: "New Subscription",
user_id: "user-123",
icon: "💰",
notify: true,
tags: {
plan: "premium",
cycle: "monthly",
trial: false
}
});
// Identify a user
await logsnag.identify({
user_id: "user-123",
properties: {
name: "John Doe",
email: "john@doe.com",
plan: "premium",
}
});
// Track an insight
await logsnag.insight.track({
title: "User Count",
value: "100",
icon: "👨",
});
// Increment an insight value
await logsnag.insight.increment({
title: "User Count",
value: 1,
icon: "👨",
});
```