@logsnag/remix
Version:
LogSnag client for Remix applications
189 lines (150 loc) • 4.5 kB
Markdown
<div align="center">
<img src="https://logsnag.com/og-image.png" alt="LogSnag"/>
<br>
<h1>/remix</h1>
<p>Clear, Simple, Effective Product Analytics for SaaS.</p>
<a href="https://www.npmjs.com/package/@logsnag/remix"><img src="https://img.shields.io/npm/v/@logsnag/remix" alt="NPM Version"></a>
<a href="https://discord.gg/dY3pRxgWua"><img src="https://img.shields.io/discord/922560704454750245?color=%237289DA&label=Discord" alt="Discord"></a>
<a href="https://docs.logsnag.com"><img src="https://img.shields.io/badge/Docs-LogSnag" alt="Documentation"></a>
<br>
<br>
</div>
## Installation
### Using npm
```bash
npm install /remix
```
### Using yarn
```bash
yarn add /remix
```
### Using pnpm
```bash
pnpm add /remix
```
## Usage
First, wrap your application with the `LogSnagProvider` at the top level, passing in your project and token:
> Set your token's scope to `public` in the LogSnag dashboard.
```tsx
import { LogSnagProvider } from '@logsnag/remix';
function App() {
return (
<html lang="en">
<head>{/* ... */}</head>
<body>
<LogSnagProvider
token="<TOKEN>"
project="<PROJECT_NAME>"
>
<Outlet />
</LogSnagProvider>
</body>
</html>
);
}
```
## Hooks
The `useLogSnag` hook can be used across your React 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.
```tsx
import { useLogSnag } from '@logsnag/remix';
export function Component() {
// Get the hooks
const { setUserId, track, identify } = useLogSnag();
// Set the user id when a 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
}
```
## Tracking Events
You can also track events directly from HTML elements using data attributes:
```jsx
<button
data-event="Upgraded Plan"
data-user-id="user-123" // optional (optional when set using setUserId)
data-channel="billing" // optional (defaults to "events")
data-icon=":moneybag:" // optional
data-tag-plan="Pro" // optional
data-tag-period="Monthly" // optional
data-tag-price="9.99" // optional
>
Upgrade to Pro
</button>
```
In this example, when the button is clicked, an event named "Upgraded Plan" will be tracked with the specified tags.
## Server-side Usage with Remix
For server-side usage, you can use LogSnag from `/remix/server` It behaves similarly to [`/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/remix/server';
// Initialize LogSnag
const logsnag = new LogSnag({
token: '<TOKEN>',
project: '<PROJECT_NAME>',
});
// 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: "👨",
});
```
## API Documentation
For more information about the LogSnag API, see: [docs.logsnag.com](https://docs.logsnag.com)
## Support
If you encounter any problems or issues, please contact us at [shayan.com](mailto:shayan.com)