@tell-rs/react 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @tell-rs/react
+
+Tell SDK React bindings — provider, hooks, and components.
+
+## Install
+
+```sh
+# npm
+npm install @tell-rs/react @tell-rs/browser
+
+# yarn
+yarn add @tell-rs/react @tell-rs/browser
+
+# pnpm
+pnpm add @tell-rs/react @tell-rs/browser
+
+# bun
+bun add @tell-rs/react @tell-rs/browser
+```
+
+`@tell-rs/browser` is a peer dependency and must be installed alongside `@tell-rs/react`.
+
+## Quick Start
+
+### 1. Add the provider
+
+Wrap your app with `TellProvider` at the root:
+
+```tsx
+// src/App.tsx
+import { TellProvider } from "@tell-rs/react";
+
+export default function App() {
+  return (
+    <TellProvider apiKey="your-api-key">
+      <YourApp />
+    </TellProvider>
+  );
+}
+```
+
+### 2. Track events
+
+```tsx
+import { useTrack } from "@tell-rs/react";
+
+function SignUpButton() {
+  const track = useTrack();
+
+  return (
+    <button onClick={() => track("Sign Up Clicked", { plan: "pro" })}>
+      Sign Up
+    </button>
+  );
+}
+```
+
+### 3. Identify users
+
+```tsx
+import { useIdentify } from "@tell-rs/react";
+
+function LoginForm() {
+  const identify = useIdentify();
+
+  function onLogin(user: { id: string; email: string }) {
+    identify(user.id, { email: user.email });
+  }
+
+  // ...
+}
+```
+
+## API
+
+### `<TellProvider>`
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `apiKey` | `string` | **Required.** Your Tell API key. |
+| `options` | `TellBrowserConfig` | Optional config passed to `tell.configure()`. |
+| `children` | `ReactNode` | Your app tree. |
+
+Calls `tell.configure()` once on mount and `tell.close()` on unmount.
+
+### Hooks
+
+| Hook | Returns | Description |
+|------|---------|-------------|
+| `useTell()` | `TellInstance` | The Tell singleton for direct access. |
+| `useTrack()` | `(name, props?) => void` | Stable callback for tracking events. |
+| `useIdentify()` | `(userId, traits?) => void` | Stable callback for identifying users. |
+
+### Direct access
+
+For cases where hooks aren't suitable:
+
+```ts
+import { tell } from "@tell-rs/react";
+
+tell.track("Background Task Done");
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,80 @@
+"use strict";
+"use client";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.tsx
+var index_exports = {};
+__export(index_exports, {
+  TellProvider: () => TellProvider,
+  tell: () => import_browser2.tell,
+  useIdentify: () => useIdentify,
+  useTell: () => useTell,
+  useTrack: () => useTrack
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var import_browser = __toESM(require("@tell-rs/browser"), 1);
+var import_browser2 = require("@tell-rs/browser");
+var import_jsx_runtime = require("react/jsx-runtime");
+var TellContext = (0, import_react.createContext)(import_browser.default);
+function TellProvider({ apiKey, options, children }) {
+  const initialized = (0, import_react.useRef)(false);
+  (0, import_react.useEffect)(() => {
+    if (!initialized.current) {
+      import_browser.default.configure(apiKey, options);
+      initialized.current = true;
+    }
+    return () => {
+      import_browser.default.close();
+    };
+  }, []);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(TellContext, { value: import_browser.default, children });
+}
+function useTell() {
+  return (0, import_react.useContext)(TellContext);
+}
+function useTrack() {
+  const t = useTell();
+  return (0, import_react.useCallback)(
+    (eventName, properties) => {
+      t.track(eventName, properties);
+    },
+    [t]
+  );
+}
+function useIdentify() {
+  const t = useTell();
+  return (0, import_react.useCallback)(
+    (userId, traits) => {
+      t.identify(userId, traits);
+    },
+    [t]
+  );
+}
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useCallback,\n  useRef,\n  type ReactNode,\n} from \"react\";\nimport tell from \"@tell-rs/browser\";\nimport type { TellBrowserConfig, TellInstance, Properties } from \"@tell-rs/browser\";\n\n// Re-export everything from @tell-rs/browser for convenience\nexport { tell } from \"@tell-rs/browser\";\nexport type { TellBrowserConfig, TellInstance, Properties } from \"@tell-rs/browser\";\n\n// ---------------------------------------------------------------------------\n// Context\n// ---------------------------------------------------------------------------\n\nconst TellContext = createContext<TellInstance>(tell);\n\nexport interface TellProviderProps {\n  apiKey: string;\n  options?: TellBrowserConfig;\n  children: ReactNode;\n}\n\n/**\n * Initializes the Tell SDK and provides it to the React tree.\n * Call once at the root of your app.\n */\nexport function TellProvider({ apiKey, options, children }: TellProviderProps) {\n  const initialized = useRef(false);\n\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  return <TellContext value={tell}>{children}</TellContext>;\n}\n\n// ---------------------------------------------------------------------------\n// Hooks\n// ---------------------------------------------------------------------------\n\n/** Access the Tell singleton instance. */\nexport function useTell(): TellInstance {\n  return useContext(TellContext);\n}\n\n/** Returns a stable `track` function. */\nexport function useTrack() {\n  const t = useTell();\n  return useCallback(\n    (eventName: string, properties?: Properties) => {\n      t.track(eventName, properties);\n    },\n    [t]\n  );\n}\n\n/** Returns a stable `identify` function. */\nexport function useIdentify() {\n  const t = useTell();\n  return useCallback(\n    (userId: string, traits?: Properties) => {\n      t.identify(userId, traits);\n    },\n    [t]\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAEA,mBAOO;AACP,qBAAiB;AAIjB,IAAAA,kBAAqB;AAgCZ;AAzBT,IAAM,kBAAc,4BAA4B,eAAAC,OAAI;AAY7C,SAAS,aAAa,EAAE,QAAQ,SAAS,SAAS,GAAsB;AAC7E,QAAM,kBAAc,qBAAO,KAAK;AAEhC,8BAAU,MAAM;AACd,QAAI,CAAC,YAAY,SAAS;AACxB,qBAAAA,QAAK,UAAU,QAAQ,OAAO;AAC9B,kBAAY,UAAU;AAAA,IACxB;AACA,WAAO,MAAM;AACX,qBAAAA,QAAK,MAAM;AAAA,IACb;AAAA,EACF,GAAG,CAAC,CAAC;AAEL,SAAO,4CAAC,eAAY,OAAO,eAAAA,SAAO,UAAS;AAC7C;AAOO,SAAS,UAAwB;AACtC,aAAO,yBAAW,WAAW;AAC/B;AAGO,SAAS,WAAW;AACzB,QAAM,IAAI,QAAQ;AAClB,aAAO;AAAA,IACL,CAAC,WAAmB,eAA4B;AAC9C,QAAE,MAAM,WAAW,UAAU;AAAA,IAC/B;AAAA,IACA,CAAC,CAAC;AAAA,EACJ;AACF;AAGO,SAAS,cAAc;AAC5B,QAAM,IAAI,QAAQ;AAClB,aAAO;AAAA,IACL,CAAC,QAAgB,WAAwB;AACvC,QAAE,SAAS,QAAQ,MAAM;AAAA,IAC3B;AAAA,IACA,CAAC,CAAC;AAAA,EACJ;AACF;","names":["import_browser","tell"]}

package/dist/index.d.cts

@@ -0,0 +1,23 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { TellBrowserConfig, Properties, TellInstance } from '@tell-rs/browser';
+export { Properties, TellBrowserConfig, TellInstance, tell } from '@tell-rs/browser';
+
+interface TellProviderProps {
+    apiKey: string;
+    options?: TellBrowserConfig;
+    children: ReactNode;
+}
+/**
+ * Initializes the Tell SDK and provides it to the React tree.
+ * Call once at the root of your app.
+ */
+declare function TellProvider({ apiKey, options, children }: TellProviderProps): react_jsx_runtime.JSX.Element;
+/** Access the Tell singleton instance. */
+declare function useTell(): TellInstance;
+/** Returns a stable `track` function. */
+declare function useTrack(): (eventName: string, properties?: Properties) => void;
+/** Returns a stable `identify` function. */
+declare function useIdentify(): (userId: string, traits?: Properties) => void;
+
+export { TellProvider, type TellProviderProps, useIdentify, useTell, useTrack };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { TellBrowserConfig, Properties, TellInstance } from '@tell-rs/browser';
+export { Properties, TellBrowserConfig, TellInstance, tell } from '@tell-rs/browser';
+
+interface TellProviderProps {
+    apiKey: string;
+    options?: TellBrowserConfig;
+    children: ReactNode;
+}
+/**
+ * Initializes the Tell SDK and provides it to the React tree.
+ * Call once at the root of your app.
+ */
+declare function TellProvider({ apiKey, options, children }: TellProviderProps): react_jsx_runtime.JSX.Element;
+/** Access the Tell singleton instance. */
+declare function useTell(): TellInstance;
+/** Returns a stable `track` function. */
+declare function useTrack(): (eventName: string, properties?: Properties) => void;
+/** Returns a stable `identify` function. */
+declare function useIdentify(): (userId: string, traits?: Properties) => void;
+
+export { TellProvider, type TellProviderProps, useIdentify, useTell, useTrack };

package/dist/index.js

@@ -0,0 +1,56 @@
+"use client";
+
+// src/index.tsx
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useCallback,
+  useRef
+} from "react";
+import tell from "@tell-rs/browser";
+import { tell as tell2 } from "@tell-rs/browser";
+import { jsx } from "react/jsx-runtime";
+var TellContext = createContext(tell);
+function TellProvider({ apiKey, options, children }) {
+  const initialized = useRef(false);
+  useEffect(() => {
+    if (!initialized.current) {
+      tell.configure(apiKey, options);
+      initialized.current = true;
+    }
+    return () => {
+      tell.close();
+    };
+  }, []);
+  return /* @__PURE__ */ jsx(TellContext, { value: tell, children });
+}
+function useTell() {
+  return useContext(TellContext);
+}
+function useTrack() {
+  const t = useTell();
+  return useCallback(
+    (eventName, properties) => {
+      t.track(eventName, properties);
+    },
+    [t]
+  );
+}
+function useIdentify() {
+  const t = useTell();
+  return useCallback(
+    (userId, traits) => {
+      t.identify(userId, traits);
+    },
+    [t]
+  );
+}
+export {
+  TellProvider,
+  tell2 as tell,
+  useIdentify,
+  useTell,
+  useTrack
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"sourcesContent":["\"use client\";\n\nimport {\n  createContext,\n  useContext,\n  useEffect,\n  useCallback,\n  useRef,\n  type ReactNode,\n} from \"react\";\nimport tell from \"@tell-rs/browser\";\nimport type { TellBrowserConfig, TellInstance, Properties } from \"@tell-rs/browser\";\n\n// Re-export everything from @tell-rs/browser for convenience\nexport { tell } from \"@tell-rs/browser\";\nexport type { TellBrowserConfig, TellInstance, Properties } from \"@tell-rs/browser\";\n\n// ---------------------------------------------------------------------------\n// Context\n// ---------------------------------------------------------------------------\n\nconst TellContext = createContext<TellInstance>(tell);\n\nexport interface TellProviderProps {\n  apiKey: string;\n  options?: TellBrowserConfig;\n  children: ReactNode;\n}\n\n/**\n * Initializes the Tell SDK and provides it to the React tree.\n * Call once at the root of your app.\n */\nexport function TellProvider({ apiKey, options, children }: TellProviderProps) {\n  const initialized = useRef(false);\n\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  return <TellContext value={tell}>{children}</TellContext>;\n}\n\n// ---------------------------------------------------------------------------\n// Hooks\n// ---------------------------------------------------------------------------\n\n/** Access the Tell singleton instance. */\nexport function useTell(): TellInstance {\n  return useContext(TellContext);\n}\n\n/** Returns a stable `track` function. */\nexport function useTrack() {\n  const t = useTell();\n  return useCallback(\n    (eventName: string, properties?: Properties) => {\n      t.track(eventName, properties);\n    },\n    [t]\n  );\n}\n\n/** Returns a stable `identify` function. */\nexport function useIdentify() {\n  const t = useTell();\n  return useCallback(\n    (userId: string, traits?: Properties) => {\n      t.identify(userId, traits);\n    },\n    [t]\n  );\n}\n"],"mappings":";;;AAEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AACP,OAAO,UAAU;AAIjB,SAAS,QAAAA,aAAY;AAgCZ;AAzBT,IAAM,cAAc,cAA4B,IAAI;AAY7C,SAAS,aAAa,EAAE,QAAQ,SAAS,SAAS,GAAsB;AAC7E,QAAM,cAAc,OAAO,KAAK;AAEhC,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;AAEL,SAAO,oBAAC,eAAY,OAAO,MAAO,UAAS;AAC7C;AAOO,SAAS,UAAwB;AACtC,SAAO,WAAW,WAAW;AAC/B;AAGO,SAAS,WAAW;AACzB,QAAM,IAAI,QAAQ;AAClB,SAAO;AAAA,IACL,CAAC,WAAmB,eAA4B;AAC9C,QAAE,MAAM,WAAW,UAAU;AAAA,IAC/B;AAAA,IACA,CAAC,CAAC;AAAA,EACJ;AACF;AAGO,SAAS,cAAc;AAC5B,QAAM,IAAI,QAAQ;AAClB,SAAO;AAAA,IACL,CAAC,QAAgB,WAAwB;AACvC,QAAE,SAAS,QAAQ,MAAM;AAAA,IAC3B;AAAA,IACA,CAAC,CAAC;AAAA,EACJ;AACF;","names":["tell"]}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@tell-rs/react",
+  "version": "0.1.0",
+  "description": "Tell SDK React bindings — provider, hooks, and components",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup",
+    "test": "echo 'no tests'",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "@tell-rs/browser": "*"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "@tell-rs/browser": "*",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tell-rs/tell-js.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://tell.rs",
+  "keywords": ["analytics", "react", "hooks", "tell"],
+  "license": "MIT",
+  "author": "Arcade Labs Inc."
+}