@tell-rs/nextjs 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +94 -0
  2. package/dist/index.cjs +72 -0
  3. package/dist/index.cjs.map +1 -0
  4. package/dist/index.d.cts +37 -0
  5. package/dist/index.d.ts +37 -0
  6. package/dist/index.js +42 -0
  7. package/dist/index.js.map +1 -0
  8. package/package.json +45 -0
package/README.md ADDED
@@ -0,0 +1,94 @@
1
+ # @tell-rs/nextjs
2
+
3
+ Tell SDK Next.js integration — automatic page tracking for the App Router.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ # npm
9
+ npm install @tell-rs/nextjs @tell-rs/browser
10
+
11
+ # yarn
12
+ yarn add @tell-rs/nextjs @tell-rs/browser
13
+
14
+ # pnpm
15
+ pnpm add @tell-rs/nextjs @tell-rs/browser
16
+
17
+ # bun
18
+ bun add @tell-rs/nextjs @tell-rs/browser
19
+ ```
20
+
21
+ `@tell-rs/browser` is a peer dependency and must be installed alongside `@tell-rs/nextjs`.
22
+
23
+ ## Quick Start
24
+
25
+ Add `TellAnalytics` to your root layout:
26
+
27
+ ```tsx
28
+ // app/layout.tsx
29
+ import { TellAnalytics } from "@tell-rs/nextjs";
30
+
31
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
32
+ return (
33
+ <html>
34
+ <body>
35
+ <TellAnalytics apiKey="your-api-key" />
36
+ {children}
37
+ </body>
38
+ </html>
39
+ );
40
+ }
41
+ ```
42
+
43
+ That's it. Page views are tracked automatically on every route change.
44
+
45
+ ## API
46
+
47
+ ### `<TellAnalytics>`
48
+
49
+ | Prop | Type | Default | Description |
50
+ |------|------|---------|-------------|
51
+ | `apiKey` | `string` | | **Required.** Your Tell API key. |
52
+ | `options` | `TellBrowserConfig` | | Optional config passed to `tell.configure()`. |
53
+ | `trackPageViews` | `boolean` | `true` | Track `Page Viewed` events on route changes. |
54
+ | `pageViewProperties` | `Properties` | | Extra properties included with every page view. |
55
+ | `children` | `ReactNode` | | Optional children to render. |
56
+
57
+ Each `Page Viewed` event includes `url` and `path` properties automatically.
58
+
59
+ ### Manual Tracking
60
+
61
+ For events beyond page views, import `tell` directly:
62
+
63
+ ```tsx
64
+ "use client";
65
+
66
+ import { tell } from "@tell-rs/nextjs";
67
+
68
+ function CheckoutButton() {
69
+ return (
70
+ <button onClick={() => tell.track("Checkout Started", { items: 3 })}>
71
+ Checkout
72
+ </button>
73
+ );
74
+ }
75
+ ```
76
+
77
+ Or combine with `@tell-rs/react` hooks in the same project:
78
+
79
+ ```tsx
80
+ import { useTrack } from "@tell-rs/react";
81
+ ```
82
+
83
+ ## How It Works
84
+
85
+ `TellAnalytics` is a `"use client"` component that:
86
+
87
+ 1. Calls `tell.configure()` once on mount
88
+ 2. Watches `usePathname()` and `useSearchParams()` from `next/navigation`
89
+ 3. Fires `tell.track("Page Viewed", { url, path })` on every route change
90
+ 4. Calls `tell.close()` on unmount
91
+
92
+ ## License
93
+
94
+ MIT
package/dist/index.cjs ADDED
@@ -0,0 +1,72 @@
1
+ "use strict";
2
+ "use client";
3
+ var __create = Object.create;
4
+ var __defProp = Object.defineProperty;
5
+ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
6
+ var __getOwnPropNames = Object.getOwnPropertyNames;
7
+ var __getProtoOf = Object.getPrototypeOf;
8
+ var __hasOwnProp = Object.prototype.hasOwnProperty;
9
+ var __export = (target, all) => {
10
+ for (var name in all)
11
+ __defProp(target, name, { get: all[name], enumerable: true });
12
+ };
13
+ var __copyProps = (to, from, except, desc) => {
14
+ if (from && typeof from === "object" || typeof from === "function") {
15
+ for (let key of __getOwnPropNames(from))
16
+ if (!__hasOwnProp.call(to, key) && key !== except)
17
+ __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
18
+ }
19
+ return to;
20
+ };
21
+ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
22
+ // If the importer is in node compatibility mode or this is not an ESM
23
+ // file that has been converted to a CommonJS file using a Babel-
24
+ // compatible transform (i.e. "__esModule" has not been set), then set
25
+ // "default" to the CommonJS "module.exports" for node compatibility.
26
+ isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
27
+ mod
28
+ ));
29
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
30
+
31
+ // src/index.tsx
32
+ var index_exports = {};
33
+ __export(index_exports, {
34
+ TellAnalytics: () => TellAnalytics,
35
+ tell: () => import_browser2.tell
36
+ });
37
+ module.exports = __toCommonJS(index_exports);
38
+ var import_react = require("react");
39
+ var import_navigation = require("next/navigation");
40
+ var import_browser = __toESM(require("@tell-rs/browser"), 1);
41
+ var import_browser2 = require("@tell-rs/browser");
42
+ function TellAnalytics({
43
+ apiKey,
44
+ options,
45
+ trackPageViews = true,
46
+ pageViewProperties,
47
+ children
48
+ }) {
49
+ const initialized = (0, import_react.useRef)(false);
50
+ const pathname = (0, import_navigation.usePathname)();
51
+ const searchParams = (0, import_navigation.useSearchParams)();
52
+ (0, import_react.useEffect)(() => {
53
+ if (!initialized.current) {
54
+ import_browser.default.configure(apiKey, options);
55
+ initialized.current = true;
56
+ }
57
+ return () => {
58
+ import_browser.default.close();
59
+ };
60
+ }, []);
61
+ (0, import_react.useEffect)(() => {
62
+ if (!trackPageViews || !initialized.current) return;
63
+ const url = searchParams?.toString() ? `${pathname}?${searchParams.toString()}` : pathname;
64
+ import_browser.default.track("Page Viewed", {
65
+ url,
66
+ path: pathname,
67
+ ...pageViewProperties
68
+ });
69
+ }, [pathname, searchParams, trackPageViews, pageViewProperties]);
70
+ return children ?? null;
71
+ }
72
+ //# sourceMappingURL=index.cjs.map
package/dist/index.cjs.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/index.tsx"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useRef, type ReactNode } from \"react\";\nimport { usePathname, useSearchParams } from \"next/navigation\";\nimport tell from \"@tell-rs/browser\";\nimport type { TellBrowserConfig, Properties } from \"@tell-rs/browser\";\n\nexport { tell } from \"@tell-rs/browser\";\nexport type { TellBrowserConfig, Properties } from \"@tell-rs/browser\";\n\nexport interface TellAnalyticsProps {\n apiKey: string;\n options?: TellBrowserConfig;\n /** Track page views automatically on route change. Default: true */\n trackPageViews?: boolean;\n /** Extra properties to include with every page view event. */\n pageViewProperties?: Properties;\n children?: ReactNode;\n}\n\n/**\n * Drop-in Next.js analytics component.\n * Place in your root layout to auto-configure Tell and track page views.\n *\n * ```tsx\n * // app/layout.tsx\n * import { TellAnalytics } from \"@tell-rs/nextjs\";\n *\n * export default function RootLayout({ children }) {\n * return (\n * <html>\n * <body>\n * <TellAnalytics apiKey=\"...\" />\n * {children}\n * </body>\n * </html>\n * );\n * }\n * ```\n */\nexport function TellAnalytics({\n apiKey,\n options,\n trackPageViews = true,\n pageViewProperties,\n children,\n}: TellAnalyticsProps) {\n const initialized = useRef(false);\n const pathname = usePathname();\n const searchParams = useSearchParams();\n\n // Initialize once\n useEffect(() => {\n if (!initialized.current) {\n tell.configure(apiKey, options);\n initialized.current = true;\n }\n return () => {\n tell.close();\n };\n }, []); // eslint-disable-line react-hooks/exhaustive-deps\n\n // Track page views on route changes\n useEffect(() => {\n if (!trackPageViews || !initialized.current) return;\n\n const url = searchParams?.toString()\n ? `${pathname}?${searchParams.toString()}`\n : pathname;\n\n tell.track(\"Page Viewed\", {\n url,\n path: pathname,\n ...pageViewProperties,\n });\n }, [pathname, searchParams, trackPageViews, pageViewProperties]);\n\n return children ?? null;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,mBAAkD;AAClD,wBAA6C;AAC7C,qBAAiB;AAGjB,IAAAA,kBAAqB;AAiCd,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,EACjB;AAAA,EACA;AACF,GAAuB;AACrB,QAAM,kBAAc,qBAAO,KAAK;AAChC,QAAM,eAAW,+BAAY;AAC7B,QAAM,mBAAe,mCAAgB;AAGrC,8BAAU,MAAM;AACd,QAAI,CAAC,YAAY,SAAS;AACxB,qBAAAC,QAAK,UAAU,QAAQ,OAAO;AAC9B,kBAAY,UAAU;AAAA,IACxB;AACA,WAAO,MAAM;AACX,qBAAAA,QAAK,MAAM;AAAA,IACb;AAAA,EACF,GAAG,CAAC,CAAC;AAGL,8BAAU,MAAM;AACd,QAAI,CAAC,kBAAkB,CAAC,YAAY,QAAS;AAE7C,UAAM,MAAM,cAAc,SAAS,IAC/B,GAAG,QAAQ,IAAI,aAAa,SAAS,CAAC,KACtC;AAEJ,mBAAAA,QAAK,MAAM,eAAe;AAAA,MACxB;AAAA,MACA,MAAM;AAAA,MACN,GAAG;AAAA,IACL,CAAC;AAAA,EACH,GAAG,CAAC,UAAU,cAAc,gBAAgB,kBAAkB,CAAC;AAE/D,SAAO,YAAY;AACrB;","names":["import_browser","tell"]}
package/dist/index.d.cts ADDED
@@ -0,0 +1,37 @@
1
+ import * as react from 'react';
2
+ import { ReactNode } from 'react';
3
+ import { TellBrowserConfig, Properties } from '@tell-rs/browser';
4
+ export { Properties, TellBrowserConfig, tell } from '@tell-rs/browser';
5
+
6
+ interface TellAnalyticsProps {
7
+ apiKey: string;
8
+ options?: TellBrowserConfig;
9
+ /** Track page views automatically on route change. Default: true */
10
+ trackPageViews?: boolean;
11
+ /** Extra properties to include with every page view event. */
12
+ pageViewProperties?: Properties;
13
+ children?: ReactNode;
14
+ }
15
+ /**
16
+ * Drop-in Next.js analytics component.
17
+ * Place in your root layout to auto-configure Tell and track page views.
18
+ *
19
+ * ```tsx
20
+ * // app/layout.tsx
21
+ * import { TellAnalytics } from "@tell-rs/nextjs";
22
+ *
23
+ * export default function RootLayout({ children }) {
24
+ * return (
25
+ * <html>
26
+ * <body>
27
+ * <TellAnalytics apiKey="..." />
28
+ * {children}
29
+ * </body>
30
+ * </html>
31
+ * );
32
+ * }
33
+ * ```
34
+ */
35
+ declare function TellAnalytics({ apiKey, options, trackPageViews, pageViewProperties, children, }: TellAnalyticsProps): string | number | bigint | boolean | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
36
+
37
+ export { TellAnalytics, type TellAnalyticsProps };
package/dist/index.d.ts ADDED
@@ -0,0 +1,37 @@
1
+ import * as react from 'react';
2
+ import { ReactNode } from 'react';
3
+ import { TellBrowserConfig, Properties } from '@tell-rs/browser';
4
+ export { Properties, TellBrowserConfig, tell } from '@tell-rs/browser';
5
+
6
+ interface TellAnalyticsProps {
7
+ apiKey: string;
8
+ options?: TellBrowserConfig;
9
+ /** Track page views automatically on route change. Default: true */
10
+ trackPageViews?: boolean;
11
+ /** Extra properties to include with every page view event. */
12
+ pageViewProperties?: Properties;
13
+ children?: ReactNode;
14
+ }
15
+ /**
16
+ * Drop-in Next.js analytics component.
17
+ * Place in your root layout to auto-configure Tell and track page views.
18
+ *
19
+ * ```tsx
20
+ * // app/layout.tsx
21
+ * import { TellAnalytics } from "@tell-rs/nextjs";
22
+ *
23
+ * export default function RootLayout({ children }) {
24
+ * return (
25
+ * <html>
26
+ * <body>
27
+ * <TellAnalytics apiKey="..." />
28
+ * {children}
29
+ * </body>
30
+ * </html>
31
+ * );
32
+ * }
33
+ * ```
34
+ */
35
+ declare function TellAnalytics({ apiKey, options, trackPageViews, pageViewProperties, children, }: TellAnalyticsProps): string | number | bigint | boolean | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | Promise<string | number | bigint | boolean | react.ReactPortal | react.ReactElement<unknown, string | react.JSXElementConstructor<any>> | Iterable<ReactNode> | null | undefined> | null;
36
+
37
+ export { TellAnalytics, type TellAnalyticsProps };
package/dist/index.js ADDED
@@ -0,0 +1,42 @@
1
+ "use client";
2
+
3
+ // src/index.tsx
4
+ import { useEffect, useRef } from "react";
5
+ import { usePathname, useSearchParams } from "next/navigation";
6
+ import tell from "@tell-rs/browser";
7
+ import { tell as tell2 } from "@tell-rs/browser";
8
+ function TellAnalytics({
9
+ apiKey,
10
+ options,
11
+ trackPageViews = true,
12
+ pageViewProperties,
13
+ children
14
+ }) {
15
+ const initialized = useRef(false);
16
+ const pathname = usePathname();
17
+ const searchParams = useSearchParams();
18
+ useEffect(() => {
19
+ if (!initialized.current) {
20
+ tell.configure(apiKey, options);
21
+ initialized.current = true;
22
+ }
23
+ return () => {
24
+ tell.close();
25
+ };
26
+ }, []);
27
+ useEffect(() => {
28
+ if (!trackPageViews || !initialized.current) return;
29
+ const url = searchParams?.toString() ? `${pathname}?${searchParams.toString()}` : pathname;
30
+ tell.track("Page Viewed", {
31
+ url,
32
+ path: pathname,
33
+ ...pageViewProperties
34
+ });
35
+ }, [pathname, searchParams, trackPageViews, pageViewProperties]);
36
+ return children ?? null;
37
+ }
38
+ export {
39
+ TellAnalytics,
40
+ tell2 as tell
41
+ };
42
+ //# sourceMappingURL=index.js.map
package/dist/index.js.map ADDED
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["../src/index.tsx"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useRef, type ReactNode } from \"react\";\nimport { usePathname, useSearchParams } from \"next/navigation\";\nimport tell from \"@tell-rs/browser\";\nimport type { TellBrowserConfig, Properties } from \"@tell-rs/browser\";\n\nexport { tell } from \"@tell-rs/browser\";\nexport type { TellBrowserConfig, Properties } from \"@tell-rs/browser\";\n\nexport interface TellAnalyticsProps {\n apiKey: string;\n options?: TellBrowserConfig;\n /** Track page views automatically on route change. Default: true */\n trackPageViews?: boolean;\n /** Extra properties to include with every page view event. */\n pageViewProperties?: Properties;\n children?: ReactNode;\n}\n\n/**\n * Drop-in Next.js analytics component.\n * Place in your root layout to auto-configure Tell and track page views.\n *\n * ```tsx\n * // app/layout.tsx\n * import { TellAnalytics } from \"@tell-rs/nextjs\";\n *\n * export default function RootLayout({ children }) {\n * return (\n * <html>\n * <body>\n * <TellAnalytics apiKey=\"...\" />\n * {children}\n * </body>\n * </html>\n * );\n * }\n * ```\n */\nexport function TellAnalytics({\n apiKey,\n options,\n trackPageViews = true,\n pageViewProperties,\n children,\n}: TellAnalyticsProps) {\n const initialized = useRef(false);\n const pathname = usePathname();\n const searchParams = useSearchParams();\n\n // Initialize once\n useEffect(() => {\n if (!initialized.current) {\n tell.configure(apiKey, options);\n initialized.current = true;\n }\n return () => {\n tell.close();\n };\n }, []); // eslint-disable-line react-hooks/exhaustive-deps\n\n // Track page views on route changes\n useEffect(() => {\n if (!trackPageViews || !initialized.current) return;\n\n const url = searchParams?.toString()\n ? `${pathname}?${searchParams.toString()}`\n : pathname;\n\n tell.track(\"Page Viewed\", {\n url,\n path: pathname,\n ...pageViewProperties,\n });\n }, [pathname, searchParams, trackPageViews, pageViewProperties]);\n\n return children ?? null;\n}\n"],"mappings":";;;AAEA,SAAS,WAAW,cAA8B;AAClD,SAAS,aAAa,uBAAuB;AAC7C,OAAO,UAAU;AAGjB,SAAS,QAAAA,aAAY;AAiCd,SAAS,cAAc;AAAA,EAC5B;AAAA,EACA;AAAA,EACA,iBAAiB;AAAA,EACjB;AAAA,EACA;AACF,GAAuB;AACrB,QAAM,cAAc,OAAO,KAAK;AAChC,QAAM,WAAW,YAAY;AAC7B,QAAM,eAAe,gBAAgB;AAGrC,YAAU,MAAM;AACd,QAAI,CAAC,YAAY,SAAS;AACxB,WAAK,UAAU,QAAQ,OAAO;AAC9B,kBAAY,UAAU;AAAA,IACxB;AACA,WAAO,MAAM;AACX,WAAK,MAAM;AAAA,IACb;AAAA,EACF,GAAG,CAAC,CAAC;AAGL,YAAU,MAAM;AACd,QAAI,CAAC,kBAAkB,CAAC,YAAY,QAAS;AAE7C,UAAM,MAAM,cAAc,SAAS,IAC/B,GAAG,QAAQ,IAAI,aAAa,SAAS,CAAC,KACtC;AAEJ,SAAK,MAAM,eAAe;AAAA,MACxB;AAAA,MACA,MAAM;AAAA,MACN,GAAG;AAAA,IACL,CAAC;AAAA,EACH,GAAG,CAAC,UAAU,cAAc,gBAAgB,kBAAkB,CAAC;AAE/D,SAAO,YAAY;AACrB;","names":["tell"]}
package/package.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "name": "@tell-rs/nextjs",
3
+ "version": "0.1.0",
4
+ "description": "Tell SDK Next.js integration — automatic page tracking",
5
+ "type": "module",
6
+ "main": "./dist/index.cjs",
7
+ "module": "./dist/index.js",
8
+ "types": "./dist/index.d.ts",
9
+ "exports": {
10
+ ".": {
11
+ "types": "./dist/index.d.ts",
12
+ "import": "./dist/index.js",
13
+ "require": "./dist/index.cjs"
14
+ }
15
+ },
16
+ "files": ["dist"],
17
+ "scripts": {
18
+ "build": "tsup",
19
+ "test": "echo 'no tests'",
20
+ "typecheck": "tsc --noEmit",
21
+ "clean": "rm -rf dist"
22
+ },
23
+ "peerDependencies": {
24
+ "next": ">=13",
25
+ "react": ">=18",
26
+ "@tell-rs/browser": "*"
27
+ },
28
+ "devDependencies": {
29
+ "@types/react": "^19.0.0",
30
+ "next": "^15.0.0",
31
+ "react": "^19.0.0",
32
+ "@tell-rs/browser": "*",
33
+ "tsup": "^8.0.0",
34
+ "typescript": "^5.5.0"
35
+ },
36
+ "repository": {
37
+ "type": "git",
38
+ "url": "git+https://github.com/tell-rs/tell-js.git",
39
+ "directory": "packages/nextjs"
40
+ },
41
+ "homepage": "https://tell.rs",
42
+ "keywords": ["analytics", "nextjs", "next", "tell"],
43
+ "license": "MIT",
44
+ "author": "Arcade Labs Inc."
45
+ }