Skip to content

Commit 9608b8d

Browse files
konradbloorkonradbloor
committed
release: v0.1.0
Initial release of @zickt/react — the official React SDK for Zickt. - ZicktProvider component for React context-based integration - ZicktMessenger drop-in component for simple usage - useZickt hook with show, hide, showNewMessage, update, getVisitorId, shutdown - Full TypeScript support with ESM and CommonJS builds - React 18 and 19 support
0 parents  commit 9608b8d

27 files changed

Lines changed: 2127 additions & 0 deletions

‎.github/workflows/publish.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Publish to npm
2+
3+
on:
4+
release:
5+
types: [published]
6+
7+
permissions:
8+
contents: read
9+
id-token: write # Required for OIDC — this is how npm authenticates the publish
10+
11+
jobs:
12+
publish:
13+
runs-on: ubuntu-latest # Must be GitHub-hosted (not self-hosted)
14+
environment: npm # Must match the environment configured on npmjs.com
15+
steps:
16+
- uses: actions/checkout@v4
17+
18+
- uses: actions/setup-node@v4
19+
with:
20+
node-version: 24
21+
registry-url: https://registry.npmjs.org
22+
23+
- run: npm install
24+
25+
- name: Build
26+
run: npx rollup -c
27+
28+
# No NODE_AUTH_TOKEN needed — OIDC handles authentication
29+
# Provenance is automatic when publishing via trusted publishing from a public repo
30+
- name: Publish (Trusted Publishing)
31+
run: |
32+
VERSION=$(node -p "require('./package.json').version")
33+
if npm view "@zickt/react@${VERSION}" version 2>/dev/null; then
34+
echo "::notice::v${VERSION} already published to npm — skipping"
35+
else
36+
npm publish --access public
37+
fi
38+
39+
- name: Verify published package
40+
run: |
41+
VERSION="${{ github.event.release.tag_name }}"
42+
VERSION="${VERSION#v}"
43+
sleep 10
44+
mkdir /tmp/verify && cd /tmp/verify
45+
npm init -y
46+
npm install react react-dom @zickt/react@${VERSION}
47+
echo 'import { ZicktMessenger } from "@zickt/react";' > test.ts
48+
npx tsc --noEmit --moduleResolution bundler --jsx react-jsx test.ts
49+
rm -rf /tmp/verify

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
dist
2+
node_modules
3+
coverage
4+
*.tsbuildinfo
5+
package-lock.json

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Changelog
2+
3+
All notable changes to `@zickt/react` will be documented in this file.
4+
5+
## [0.1.0] - Unreleased
6+
7+
### Added
8+
9+
- `ZicktProvider` component for React context-based integration
10+
- `ZicktMessenger` drop-in component for simple usage
11+
- `useZickt` hook with `show`, `hide`, `showNewMessage`, `update`, `getVisitorId`, and `shutdown` methods
12+
- `isReady` state for knowing when the messenger has loaded
13+
- TypeScript types: `ZicktConfig`, `ZicktUser`, `ZicktCompany`, `ZicktAppearance`, `ZicktCallbacks`
14+
- ESM and CommonJS builds with source maps
15+
- Full source included for debugging

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Zickt Ltd
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
# @zickt/react
2+
3+
[![npm version](https://img.shields.io/npm/v/@zickt/react.svg)](https://www.npmjs.com/package/@zickt/react)
4+
[![npm bundle size](https://img.shields.io/bundlephobia/minzip/@zickt/react)](https://bundlephobia.com/package/@zickt/react)
5+
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
6+
[![TypeScript](https://img.shields.io/badge/types-included-blue.svg)](https://www.npmjs.com/package/@zickt/react)
7+
[![npm provenance](https://img.shields.io/badge/provenance-verified-brightgreen.svg)](https://docs.npmjs.com/generating-provenance-statements)
8+
[![100% Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](#quality)
9+
10+
Official React SDK for [Zickt](https://zickt.com) — add a [customer messaging widget](https://zickt.com) to your React app in one line.
11+
12+
[Zickt](https://zickt.com) is a modern customer communication platform for support, sales, and engagement. This package provides React components and hooks for embedding the [Zickt live chat widget](https://zickt.com) into any React application.
13+
14+
## Install
15+
16+
```bash
17+
npm install @zickt/react
18+
```
19+
20+
## Quick Start
21+
22+
```tsx
23+
import { ZicktMessenger } from '@zickt/react';
24+
25+
function App() {
26+
return (
27+
<>
28+
<YourApp />
29+
<ZicktMessenger channelKey="your-channel-key" />
30+
</>
31+
);
32+
}
33+
```
34+
35+
That's it. The messenger widget loads from Zickt's CDN and appears on your page. Get your channel key from the [Zickt dashboard](https://zickt.com).
36+
37+
## With Hooks
38+
39+
Use `ZicktProvider` and `useZickt` when you need programmatic control — showing/hiding the messenger or reading state.
40+
41+
```tsx
42+
import { ZicktProvider, useZickt } from '@zickt/react';
43+
44+
function App() {
45+
return (
46+
<ZicktProvider channelKey="your-channel-key" user={{ email: 'user@example.com', name: 'Jane' }}>
47+
<Dashboard />
48+
</ZicktProvider>
49+
);
50+
}
51+
52+
function Dashboard() {
53+
const { show, hide, isReady } = useZickt();
54+
55+
return (
56+
<div>
57+
<button onClick={() => show()}>Open Chat</button>
58+
<button onClick={() => hide()}>Close Chat</button>
59+
</div>
60+
);
61+
}
62+
```
63+
64+
## API
65+
66+
### `<ZicktMessenger />`
67+
68+
Drop-in component. Renders nothing visually — the messenger widget is injected by the SDK.
69+
70+
| Prop | Type | Description |
71+
| ------------------------ | ------------------------- | --------------------------------------------------------- |
72+
| `channelKey` | `string` | **Required.** Your [Zickt](https://zickt.com) channel key |
73+
| `user` | `ZicktUser` | Identify the current user |
74+
| `company` | `ZicktCompany` | Associate a company |
75+
| `appearance` | `ZicktAppearance` | Position and theme |
76+
| `hideDefaultLauncher` | `boolean` | Hide the default chat button |
77+
| `customLauncherSelector` | `string` | CSS selector for a custom launcher element |
78+
| `onReady` | `() => void` | Called when the messenger is fully loaded |
79+
| `onShow` | `() => void` | Called when the messenger opens |
80+
| `onHide` | `() => void` | Called when the messenger closes |
81+
| `onUnreadCountChanged` | `(count: number) => void` | Called when unread count changes |
82+
83+
### `<ZicktProvider />`
84+
85+
Wraps your app and provides context to `useZickt`. Accepts all the same props as `ZicktMessenger` plus `children`.
86+
87+
```tsx
88+
<ZicktProvider channelKey="your-channel-key" user={{ email: 'user@example.com' }}>
89+
{children}
90+
</ZicktProvider>
91+
```
92+
93+
### `useZickt()`
94+
95+
Hook for programmatic control. Must be used inside a `ZicktProvider`.
96+
97+
```tsx
98+
const {
99+
isReady, // boolean — true when messenger has loaded
100+
show, // () => void — open the messenger
101+
hide, // () => void — close the messenger
102+
showNewMessage, // (message?: string) => void — open with a pre-filled message
103+
update, // (config: Partial<ZicktConfig>) => void — update config at runtime
104+
getVisitorId, // () => string | undefined — get the current visitor ID
105+
shutdown, // () => void — shut down the messenger
106+
} = useZickt();
107+
```
108+
109+
## Types
110+
111+
All types are exported for use in your application:
112+
113+
```tsx
114+
import type {
115+
ZicktConfig,
116+
ZicktUser,
117+
ZicktCompany,
118+
ZicktAppearance,
119+
ZicktCallbacks,
120+
ZicktContextValue,
121+
ZicktProviderProps,
122+
ZicktMessengerProps,
123+
} from '@zickt/react';
124+
```
125+
126+
### `ZicktUser`
127+
128+
```typescript
129+
interface ZicktUser {
130+
id?: string;
131+
email?: string;
132+
name?: string;
133+
phone?: string;
134+
avatar?: string;
135+
[key: string]: unknown; // custom attributes
136+
}
137+
```
138+
139+
### `ZicktAppearance`
140+
141+
```typescript
142+
interface ZicktAppearance {
143+
position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
144+
theme?: 'light' | 'dark' | 'auto';
145+
}
146+
```
147+
148+
## Resources
149+
150+
- [Documentation](https://zickt.com/docs/channels/messenger/react) — full React SDK reference and guides
151+
- [Zickt website](https://zickt.com) — create a free account and get your channel key
152+
153+
## Requirements
154+
155+
- React 18 or 19
156+
- A [Zickt](https://zickt.com) account and channel key
157+
158+
## Quality
159+
160+
This package enforces strict quality gates on every release:
161+
162+
- **100% test coverage** — statements, branches, functions, lines (48 tests)
163+
- **Bundle size limit** — under 3 kB minified + brotli
164+
- **Strict TypeScript** — no `any`, explicit return types, strict boolean expressions
165+
- **28 ESLint rules** — all as error, including type-aware async/condition correctness
166+
- **Type validation** — [publint](https://publint.dev), [attw](https://arethetypeswrong.github.io), [tsd](https://github.com/tsdjs/tsd)
167+
- **npm provenance** — cryptographically signed builds linked to source
168+
169+
## License
170+
171+
[MIT](./LICENSE)

‎package.json‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
{
2+
"name": "@zickt/react",
3+
"version": "0.1.0",
4+
"description": "Official React SDK for Zickt (zickt.com) — add live chat, customer messaging, and support widgets to React apps",
5+
"main": "./dist/index.cjs",
6+
"module": "./dist/index.js",
7+
"types": "./dist/index.d.ts",
8+
"exports": {
9+
".": {
10+
"import": {
11+
"types": "./dist/index.d.ts",
12+
"default": "./dist/index.js"
13+
},
14+
"require": {
15+
"types": "./dist/index.d.cts",
16+
"default": "./dist/index.cjs"
17+
}
18+
}
19+
},
20+
"files": [
21+
"dist",
22+
"src",
23+
"!src/tests"
24+
],
25+
"scripts": {
26+
"build": "rollup -c",
27+
"dev": "rollup -c -w",
28+
"lint": "eslint .",
29+
"type-check": "tsgo --noEmit",
30+
"clean": "rm -rf dist",
31+
"check:publint": "publint",
32+
"check:attw": "attw --pack .",
33+
"check:size": "size-limit",
34+
"check:types": "tsd",
35+
"check:all": "pnpm check:publint && pnpm check:attw && pnpm check:size && pnpm check:types"
36+
},
37+
"size-limit": [
38+
{
39+
"path": "dist/index.js",
40+
"limit": "3 kB"
41+
}
42+
],
43+
"tsd": {
44+
"directory": "src/tests/types"
45+
},
46+
"engines": {
47+
"node": ">=18.0.0"
48+
},
49+
"peerDependencies": {
50+
"react": "^18.0.0 || ^19.0.0",
51+
"react-dom": "^18.0.0 || ^19.0.0"
52+
},
53+
"devDependencies": {
54+
"@arethetypeswrong/cli": "^0.18.2",
55+
"@rollup/plugin-node-resolve": "^15.2.3",
56+
"@rollup/plugin-typescript": "^11.1.6",
57+
"@size-limit/preset-small-lib": "^12.0.0",
58+
"@testing-library/jest-dom": "^6.6.3",
59+
"@testing-library/react": "^16.3.0",
60+
"@types/react": "^19.0.0",
61+
"@types/react-dom": "^19.0.0",
62+
"@vitest/coverage-v8": "^4.0.18",
63+
"jsdom": "^24.1.0",
64+
"publint": "^0.3.17",
65+
"react": "^19.0.0",
66+
"react-dom": "^19.0.0",
67+
"rollup": "^4.56.0",
68+
"rollup-plugin-dts": "^6.3.0",
69+
"size-limit": "^12.0.0",
70+
"tsd": "^0.33.0",
71+
"tslib": "^2.8.0",
72+
"typescript": "^5.9.0",
73+
"vitest": "^4.0.0"
74+
},
75+
"publishConfig": {
76+
"access": "public"
77+
},
78+
"repository": {
79+
"type": "git",
80+
"url": "git+https://github.com/zickt/react.git"
81+
},
82+
"homepage": "https://zickt.com/docs/channels/messenger/react",
83+
"bugs": {
84+
"url": "https://github.com/zickt/react/issues"
85+
},
86+
"author": {
87+
"name": "Zickt",
88+
"url": "https://zickt.com"
89+
},
90+
"funding": {
91+
"type": "custom",
92+
"url": "https://zickt.com"
93+
},
94+
"license": "MIT",
95+
"keywords": [
96+
"zickt",
97+
"react",
98+
"messenger",
99+
"chat",
100+
"widget",
101+
"live-chat",
102+
"customer-support",
103+
"customer-messaging",
104+
"support-widget",
105+
"chat-widget",
106+
"react-chat",
107+
"intercom-alternative",
108+
"intercom-react",
109+
"helpdesk",
110+
"in-app-messaging"
111+
],
112+
"sideEffects": false,
113+
"type": "module"
114+
}

0 commit comments

Comments
 (0)