Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Add Node.js SDK docs back

Edward Cuie3506c40fd22
diff --git a/docs/src/content/sdks/node.mdx b/docs/src/content/sdks/node.mdx
new file mode 100644
index 000000000..68826dd8d
--- /dev/null
+++ b/docs/src/content/sdks/node.mdx
@@ -0,0 +1,164 @@
+import { Callout } from "nextra/components"
+
+# JavaScript (Node.js)
+
+## Installation
+
+```bash filename="npm"
+npm install @rybbit/node
+```
+
+```bash filename="yarn"
+yarn add @rybbit/node
+```
+
+## Initialization
+
+### Syntax
+
+```typescript
+import { Rybbit } from "@rybbit/node";
+
+const rybbit = new Rybbit(config: RybbitConfig);
+```
+
+### Example
+
+```javascript
+import { Rybbit } from "@rybbit/node";
+
+const rybbit = new Rybbit({
+ analyticsHost: "https://api.rybbit.io/api",
+ siteId: "1",
+ origin: "https://rybbit.io",
+});
+```
+
+<Callout type="warning">
+The `Rybbit` constructor will throw an error if required configuration options (`analyticsHost`, `siteId`, `origin`) are missing or invalid.
+</Callout>
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+| :-------------- | :----------------- | :------ | :----------------------------------------------------------------------------------------------- |
+| `analyticsHost` | `string` | - | **Required.** URL of your Rybbit analytics instance (e.g., `https://rybbit.yourdomain.com/api`). |
+| `siteId` | `string \| number` | - | **Required.** The Site ID for your website obtained from your Rybbit instance. |
+| `origin` | `string` | - | **Required.** The domain of your website. |
+| `userAgent` | `string` | `""` | A custom User-Agent string to send with tracking requests. |
+| `debug` | `boolean` | `false` | If `true`, enables detailed logging to the console. |
+
+## Tracking Pageviews
+
+While pageviews are traditionally a browser concept, the Node.js SDK provides a `pageview` method to track events that are analogous to a user viewing a page or a significant resource. This can be useful for tracking views of server-rendered pages before client-side JavaScript takes over, or for tracking views of API resources.
+
+### Syntax
+
+```typescript
+await rybbit.pageview(payload?: Payload);
+```
+
+### Parameters
+
+- **`payload`** (`object`, Optional): An object containing details about the pageview. All properties are optional.
+ - `hostname` (`string`): The hostname associated with this pageview.
+ - `pathname` (`string`): The path of the page/resource being viewed.
+ - `querystring` (`string`): Any query parameters associated with the path.
+ - `screenWidth` (`number`): Screen width in pixels.
+ - `screenHeight` (`number`): Screen height in pixels.
+ - `language` (`string`): Language code.
+ - `page_title` (`string`): The title of the page or resource.
+ - `referrer` (`string`): The referrer URL.
+
+<Callout type="info">
+The fields `screenWidth`, `screenHeight`, `language`, `page_title`, and `referrer` are typically browser-derived. When using the Node.js SDK, you would only provide these if they are relevant and available in your server-side context. For many server-side pageview events, `hostname` and `pathname` might be the most relevant.
+</Callout>
+
+### Example
+
+```javascript
+// Track a server-rendered page view
+async function handleProductPageRequest(req, res) {
+ // ... server logic to render product page ...
+
+ await rybbit.pageview({
+ hostname: req.hostname,
+ pathname: `/products/${req.params.productId}`,
+ page_title: `Product - ${product.name}`
+ });
+
+ // ... send response ...
+}
+
+// Track an API resource view
+async function serveApiResource(req) {
+ await rybbit.pageview({
+ hostname: "api.myservice.com",
+ pathname: `/v1/items/${req.params.itemId}`
+ });
+ // ... return API data ...
+}
+```
+
+## Tracking Custom Events
+
+Use custom events to track specific actions or milestones occurring in your backend system. Examples include user account creation, background job completion, API endpoint usage, or any significant server-side process.
+
+### Syntax
+
+```typescript
+await rybbit.event(eventName: string, payload?: Payload, properties?: TrackProperties);
+```
+
+### Parameters
+
+- **`eventName`** (`string`, Required): The name of the event you want to track.
+- **`payload`** (`object`, Optional): An object containing contextual details for the event. All properties are optional.
+ - `hostname` (`string`): The hostname associated with this event.
+ - `pathname` (`string`): The path or resource context for this event.
+ - `querystring` (`string`): Any query parameters relevant to the event's context.
+ - `screenWidth` (`number`): Screen width in pixels.
+ - `screenHeight` (`number`): Screen height in pixels.
+ - `language` (`string`): Language code.
+ - `page_title` (`string`): The title of the page or resource context.
+ - `referrer` (`string`): The referrer URL.
+- **`properties`** (`object`, Optional): An object containing additional key-value pairs related to the event. Values should ideally be strings, numbers, or booleans. Keep the structure flat.
+
+<Callout type="info">
+The `payload` fields (`hostname`, `pathname`, etc.) provide general context for the event, similar to a pageview. The `properties` object is for data specific to the custom `eventName` itself (e.g., for an `"order_processed"` event, properties might include `orderId: 12345` and `totalAmount: 99.99`).
+</Callout>
+
+### Example
+
+```javascript
+// Track a new user registration
+async function registerUser(userData) {
+ // ... process user registration ...
+
+ await rybbit.event("user_registered",
+ { hostname: "auth.myservice.com", pathname: "/register" },
+ { userId: newUserId, registrationMethod: "email" }
+ );
+}
+
+// Track a background job completion
+async function processDailyReport(reportId) {
+ // ... generate report ...
+
+ await rybbit.event("report_generated",
+ {},
+ { reportId: reportId, status: "success", processingTimeMs: 12345 }
+ );
+}
+
+// Track an API endpoint usage with specific data
+async function handleApiRequest(req) {
+ // ... handle request ...
+ await rybbit.event(
+ "api_v1_item_lookup",
+ { hostname: req.hostname, pathname: req.path },
+ { itemId: req.params.itemId, clientVersion: req.headers["x-client-version"] }
+ );
+ // ... return response ...
+}
+```