> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vizochok.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the VIZOCHOK widget SDK in your project

## Package Manager

Install via npm or any compatible package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install @vizochok/widget
  ```

  ```bash yarn theme={null}
  yarn add @vizochok/widget
  ```

  ```bash pnpm theme={null}
  pnpm add @vizochok/widget
  ```
</CodeGroup>

Then import and use in your application:

```typescript theme={null}
import { VizochokWidget } from '@vizochok/widget';

const widget = new VizochokWidget({
  apiKey: 'pk_your_public_key',
  storeId: 'your-store-id',
});

widget.mount();
```

## CDN / Script Tag

For sites without a build system, load the widget directly from a CDN:

```html theme={null}
<script src="https://cdn.jsdelivr.net/npm/@vizochok/widget@latest/dist/vizochok-widget.umd.js"></script>
<script>
  const widget = new VizochokWidget({
    apiKey: 'pk_your_public_key',
    storeId: 'your-store-id',
  });
  widget.mount();
</script>
```

The UMD build exposes a global `VizochokWidget` constructor.

<Warning>
  Pin a specific version in production (e.g., `@vizochok/widget@0.1.2`) instead of `@latest` to avoid unexpected breaking changes.
</Warning>

## Bundle Size

| Build | File                     | Size         |
| ----- | ------------------------ | ------------ |
| ESM   | `vizochok-widget.esm.js` | \~11 KB gzip |
| UMD   | `vizochok-widget.umd.js` | \~12 KB gzip |

The SDK has **zero runtime dependencies**. All styles are bundled as a template literal string and injected into a Shadow DOM `<style>` element at mount time.

## TypeScript Support

The package ships with full TypeScript declarations (`dist/types.d.ts`). All public interfaces are exported:

```typescript theme={null}
import type {
  VizochokWidgetConfig,
  CartItem,
  CartChangedEvent,
  ProductItem,
  SessionSummary,
  WidgetError,
  ThemeMode,
} from '@vizochok/widget';
```

No additional `@types/` package is needed.

## Browser Compatibility

The widget uses standard Web APIs and is compatible with all modern browsers:

| Browser        | Minimum Version |
| -------------- | --------------- |
| Chrome         | 63+             |
| Firefox        | 67+             |
| Safari         | 13.1+           |
| Edge           | 79+             |
| Mobile Safari  | 13.4+           |
| Chrome Android | 63+             |

<Info>
  The widget relies on [Shadow DOM v1](https://caniuse.com/shadowdomv1) for CSS isolation and [WebSocket](https://caniuse.com/websockets) for real-time communication. Internet Explorer is not supported.
</Info>

## Module Formats

The package provides two build outputs:

* **ESM** (`vizochok-widget.esm.js`) -- for modern bundlers (Vite, Webpack 5, Rollup, esbuild). Referenced via the `module` field in `package.json`.
* **UMD** (`vizochok-widget.umd.js`) -- for script tags and legacy bundlers. Referenced via the `main` field in `package.json`.

Most bundlers will automatically pick the correct format based on your import syntax.

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/widget/configuration">
    Learn about all available config options
  </Card>

  <Card title="Quick Start" icon="bolt" href="/quickstart">
    Get a working widget in 5 minutes
  </Card>
</CardGroup>