@batterii/vurvey-brand-companion-sdk

v0.0.3

Published

8 days ago

Embeddable Vurvey Brand Companion for web apps: React component and Shadow DOM web component with bundled styles.

Vurvey Brand Companion SDK

Embeddable Vurvey Brand Companion for web apps: a React component and a Shadow DOM web component built with Tailwind CSS and shadcn/ui. Both paths bundle styles—no CSS import required for normal use. The web component isolates styles from the host app.

Package: @batterii/vurvey-brand-companion-sdk

Installation

npm install @batterii/vurvey-brand-companion-sdk

yarn add @batterii/vurvey-brand-companion-sdk

pnpm add @batterii/vurvey-brand-companion-sdk

Peer dependencies (React API only)

If you use the React component, install compatible React and React DOM in your app (the SDK lists them as peers):

npm install react react-dom

The web component path does not require React.

Entry points

| Import | Use case | | ---------------------------------------------------- | ------------------------------------------------------------- | | @batterii/vurvey-brand-companion-sdk | React component (VurveyBrandCompanion), shared types, icons | | @batterii/vurvey-brand-companion-sdk/web-component | Register <vurvey-brand-companion> (side-effect import) | | @batterii/vurvey-brand-companion-sdk/styles | Optional styles.css if you need a manual CSS import |

Usage

React — for React apps
Web component — for React, Vue, vanilla JS, etc., with Shadow DOM isolation

React component

Styles are applied when the component mounts; no CSS import is needed for typical use.

import { VurveyBrandCompanion } from "@batterii/vurvey-brand-companion-sdk";

function App() {
  return (
    <VurveyBrandCompanion
      apiKey="your-api-key"
      personaId="your-persona-id"
      onReady={() => console.log("SDK ready!")}
    />
  );
}

Web component (Shadow DOM)

Import once to register the custom element. Styles are bundled and injected inside the shadow root—no CSS import needed for typical use.

React example

import "@batterii/vurvey-brand-companion-sdk/web-component";

function App() {
  return (
    <div style={{ height: "100vh" }}>
      <vurvey-brand-companion
        api-key="your-api-key"
        persona-id="your-persona-id"
      />
    </div>
  );
}

Vanilla JavaScript example

<!DOCTYPE html>
<html>
  <head>
    <script type="module">
      import "@batterii/vurvey-brand-companion-sdk/web-component";
    </script>
    <style>
      body {
        margin: 0;
        height: 100vh;
      }
      vurvey-brand-companion {
        display: block;
        width: 100%;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <vurvey-brand-companion
      api-key="your-api-key"
      persona-id="your-persona-id"
    ></vurvey-brand-companion>

    <script>
      const companion = document.querySelector("vurvey-brand-companion");
      companion.addEventListener("ready", () => {
        console.log("SDK is ready!");
      });
    </script>
  </body>
</html>

Vue example

<template>
  <div class="container">
    <vurvey-brand-companion
      :api-key="apiKey"
      :persona-id="personaId"
      @ready="handleReady"
    />
  </div>
</template>

<script setup lang="ts">
import "@batterii/vurvey-brand-companion-sdk/web-component";

const apiKey = "your-api-key";
const personaId = "your-persona-id";

const handleReady = () => {
  console.log("SDK is ready!");
};
</script>

<style scoped>
.container {
  width: 100%;
  height: 100vh;
}
</style>

Web component attributes

api-key (required): Your API key
persona-id (required): Your persona ID

Web component events

ready: Fired when the component is fully loaded and ready

const companion = document.querySelector("vurvey-brand-companion");
companion.addEventListener("ready", () => {
  console.log("Component is ready!");
});

Shadow DOM benefits

Style isolation — Host CSS does not leak in; companion styles do not leak out
No CSS conflicts — Safer to embed in existing apps
Automatic style injection — No manual CSS import for normal use

TypeScript

import type { AppProps } from "@batterii/vurvey-brand-companion-sdk";
import { VurveyBrandCompanion } from "@batterii/vurvey-brand-companion-sdk";
import type { VurveyBrandCompanionElement } from "@batterii/vurvey-brand-companion-sdk/web-component";

Notes for consumers

React path: Uses React 18 or 19 as peer dependencies; install react and react-dom in your app.
Bundled runtime deps: You do not need Tailwind or shadcn in the host app—the prebuilt package includes what it needs.
Path aliases (@/* in this repo) are resolved at publish build time; consumers do not configure them.
Optional CSS: Use @batterii/vurvey-brand-companion-sdk/styles only if you intentionally want the raw stylesheet.

Developing this package

For contributors working in this repository (not required for npm consumers).

Install and build

npm install
npm run build

This will:

Process Tailwind CSS into dist/styles.css
Inline CSS into src/styles-inlined.ts for automatic injection in builds
Build TypeScript with tsup into dist/

Local dev

npm run dev

Examples with hot reload:

npm run dev:react
npm run dev:vue
npm run dev:vanilla