@dngbuilds/zapkit-react 0.0.1 → 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 (2) hide show
  1. package/README.md +193 -10
  2. package/package.json +27 -18
package/README.md CHANGED
@@ -1,23 +1,206 @@
1
- # vite-plus-starter
1
+ <div align="center">
2
+ <h1>⚡ @dngbuilds/zapkit-react</h1>
3
+ <p><strong>React hooks and provider for Starknet — wallet connection in minutes, not hours.</strong></p>
2
4
 
3
- A starter for creating a Vite Plus project.
5
+ <p>
6
+ <a href="https://www.npmjs.com/package/@dngbuilds/zapkit-react"><img src="https://img.shields.io/npm/v/@dngbuilds/zapkit-react?color=blue&label=npm" alt="npm version" /></a>
7
+ <a href="https://www.npmjs.com/package/@dngbuilds/zapkit-react"><img src="https://img.shields.io/npm/dm/@dngbuilds/zapkit-react?color=green" alt="npm downloads" /></a>
8
+ <a href="https://github.com/DngBuilds/zapkit/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license" /></a>
9
+ </p>
10
+ </div>
4
11
 
5
- ## Development
12
+ ---
6
13
 
7
- - Install dependencies:
14
+ ## Overview
15
+
16
+ `@dngbuilds/zapkit-react` provides a `<ZapProvider>` context and a set of React hooks for connecting wallets, fetching balances, staking, swapping, and bridging on Starknet. It builds on top of [`@dngbuilds/zapkit-core`](https://www.npmjs.com/package/@dngbuilds/zapkit-core) and uses [TanStack Query](https://tanstack.com/query) for data fetching.
17
+
18
+ ## Installation
8
19
 
9
20
  ```bash
10
- vp install
21
+ npm install @dngbuilds/zapkit-react
11
22
  ```
12
23
 
13
- - Run the unit tests:
24
+ > `@dngbuilds/zapkit-core` is included as a dependency — you don't need to install it separately.
14
25
 
15
- ```bash
16
- vp test
26
+ ## Quick Start
27
+
28
+ ### 1. Wrap your app with `<ZapProvider>`
29
+
30
+ ```tsx
31
+ import { ZapProvider } from "@dngbuilds/zapkit-react";
32
+
33
+ function App() {
34
+ return (
35
+ <ZapProvider config={{ network: "mainnet" }}>
36
+ <YourApp />
37
+ </ZapProvider>
38
+ );
39
+ }
40
+ ```
41
+
42
+ ### 2. Connect a wallet
43
+
44
+ ```tsx
45
+ import { useWallet, OnboardStrategy } from "@dngbuilds/zapkit-react";
46
+
47
+ function ConnectButton() {
48
+ const { address, status, connect, disconnect } = useWallet();
49
+
50
+ if (status === "connected") {
51
+ return (
52
+ <div>
53
+ <p>{address}</p>
54
+ <button onClick={disconnect}>Disconnect</button>
55
+ </div>
56
+ );
57
+ }
58
+
59
+ return (
60
+ <button
61
+ disabled={status === "connecting"}
62
+ onClick={() => connect({ strategy: OnboardStrategy.Cartridge })}
63
+ >
64
+ {status === "connecting" ? "Connecting…" : "Connect Wallet"}
65
+ </button>
66
+ );
67
+ }
17
68
  ```
18
69
 
19
- - Build the library:
70
+ ### 3. Fetch balances
71
+
72
+ ```tsx
73
+ import { useBalance } from "@dngbuilds/zapkit-react";
74
+
75
+ function Balance() {
76
+ const { data, isLoading } = useBalance({
77
+ token: { symbol: "ETH", address: "0x049d…" },
78
+ });
79
+
80
+ if (isLoading) return <p>Loading…</p>;
81
+ return <p>ETH: {data?.toString()}</p>;
82
+ }
83
+ ```
84
+
85
+ ## Provider
86
+
87
+ ### `<ZapProvider>`
88
+
89
+ Wraps your application and initializes ZapKit + TanStack Query.
90
+
91
+ ```tsx
92
+ <ZapProvider
93
+ config={{ network: "mainnet" }}
94
+ queryClient={customQueryClient} // optional — bring your own
95
+ showDevPanel={false} // optional — error overlay for dev
96
+ >
97
+ <App />
98
+ </ZapProvider>
99
+ ```
100
+
101
+ | Prop | Type | Default | Description |
102
+ | ------------- | -------------- | ------- | ---------------------------------------- |
103
+ | `config` | `ZapKitConfig` | — | Network and SDK configuration |
104
+ | `queryClient` | `QueryClient` | auto | Custom TanStack Query client |
105
+ | `showDevPanel`| `boolean` | `false` | Show developer error panel |
106
+
107
+ ## Hooks
108
+
109
+ ### `useWallet()`
110
+
111
+ Returns wallet connection state and actions.
112
+
113
+ ```ts
114
+ const {
115
+ address, // string | null — connected wallet address
116
+ ens, // string | null — resolved StarkNet ID
117
+ status, // "idle" | "connecting" | "connected" | "error"
118
+ balances, // Record<string, string>
119
+ loading, // boolean
120
+ error, // Error | null
121
+ connect, // (options: OnboardOptions) => Promise<void>
122
+ disconnect, // () => void
123
+ ensureReady,// () => Promise<void>
124
+ } = useWallet();
125
+ ```
126
+
127
+ ### `useZapKit()`
128
+
129
+ Returns the raw `ZapKit` instance for advanced use cases.
130
+
131
+ ```ts
132
+ const zapkit = useZapKit();
133
+ await zapkit?.stake({ poolAddress: "0x…", amount });
134
+ ```
135
+
136
+ ### Query Hooks (TanStack Query)
137
+
138
+ | Hook | Description |
139
+ | ------------------- | ---------------------------------- |
140
+ | `useBalance()` | Fetch token balance |
141
+ | `useStakingPools()` | List available staking pools |
142
+ | `useBridgingTokens()` | List available bridging tokens |
143
+
144
+ ### Mutation Hooks (TanStack Query)
145
+
146
+ | Hook | Description |
147
+ | --------------- | ----------------------------------- |
148
+ | `useSwap()` | Execute a token swap |
149
+ | `useStaking()` | Stake / unstake / claim rewards |
150
+ | `useLending()` | Lending protocol interactions |
151
+
152
+ ## Pre-built UI Components
153
+
154
+ ZapKit also provides a set of ready-to-use shadcn components you can install directly into your project:
20
155
 
21
156
  ```bash
22
- vp pack
157
+ npx shadcn@latest add "https://zapkit.vercel.app/r/connect-wallet-button.json"
158
+ npx shadcn@latest add "https://zapkit.vercel.app/r/wallet-card.json"
159
+ ```
160
+
161
+ Available components: `connect-wallet-button`, `address-badge`, `network-badge`, `wallet-card`, `token-amount`, `transaction-status`.
162
+
163
+ Browse the full registry at [zapkit.vercel.app](https://zapkit.vercel.app).
164
+
165
+ ## Re-exported from Core
166
+
167
+ For convenience, the following are re-exported from `@dngbuilds/zapkit-core`:
168
+
169
+ ```ts
170
+ // Values
171
+ export { OnboardStrategy, Amount, fromAddress, StarkSigner };
172
+ export { Tx, TxBuilder, ChainId, ExternalChain, BridgeToken };
173
+ export { getPresets, accountPresets };
174
+
175
+ // Types
176
+ export type { OnboardOptions, OnboardResult, Token, Pool, Address, Wallet };
177
+ export type { CartridgeWalletInterface, ConnectCartridgeOptions };
178
+ export type { EnsureReadyOptions, ExecuteOptions, RpcProvider, Call };
23
179
  ```
180
+
181
+ ## Wallet Strategies
182
+
183
+ | Strategy | Import | Description |
184
+ | ---------- | ------------------------- | ----------------------------------- |
185
+ | Cartridge | `OnboardStrategy.Cartridge` | Social login & passkeys |
186
+ | Signer | `OnboardStrategy.Signer` | Direct private-key signing |
187
+ | Privy | `OnboardStrategy.Privy` | Email & social auth via Privy |
188
+
189
+ ## Vite Configuration
190
+
191
+ Add the ZapKit Vite plugin to resolve optional peer dependencies:
192
+
193
+ ```ts
194
+ // vite.config.ts
195
+ import { defineConfig } from "vite";
196
+ import react from "@vitejs/plugin-react";
197
+ import { zapkitPlugin } from "@dngbuilds/zapkit-core/vite";
198
+
199
+ export default defineConfig({
200
+ plugins: [react(), zapkitPlugin()],
201
+ });
202
+ ```
203
+
204
+ ## License
205
+
206
+ [MIT](https://github.com/DngBuilds/zapkit/blob/master/LICENSE)
package/package.json CHANGED
@@ -1,17 +1,27 @@
1
1
  {
2
2
  "name": "@dngbuilds/zapkit-react",
3
- "version": "0.0.1",
4
- "description": "Zapkit React package.",
5
- "homepage": "",
3
+ "version": "0.1.0",
4
+ "description": "React hooks and provider for Starknet — wallet connection in minutes, not hours.",
5
+ "homepage": "https://zapkit.vercel.app",
6
6
  "bugs": {
7
- "url": ""
7
+ "url": "https://github.com/DngBuilds/zapkit/issues"
8
8
  },
9
9
  "license": "MIT",
10
10
  "author": "DngBuilds <dng.builds@gmail.com>",
11
11
  "repository": {
12
12
  "type": "git",
13
- "url": "git+https://github.com/author/library.git"
13
+ "url": "git+https://github.com/DngBuilds/zapkit.git",
14
+ "directory": "packages/react"
14
15
  },
16
+ "keywords": [
17
+ "starknet",
18
+ "wallet",
19
+ "react",
20
+ "hooks",
21
+ "web3",
22
+ "defi",
23
+ "zapkit"
24
+ ],
15
25
  "files": [
16
26
  "dist"
17
27
  ],
@@ -23,22 +33,15 @@
23
33
  "publishConfig": {
24
34
  "access": "public"
25
35
  },
26
- "scripts": {
27
- "build": "vp pack",
28
- "dev": "vp pack --watch",
29
- "test": "vp test",
30
- "check": "vp check",
31
- "prepublishOnly": "vp run build"
32
- },
33
36
  "dependencies": {
34
- "@tanstack/react-query": "catalog:",
35
- "@dngbuilds/zapkit-core": "workspace:*",
36
- "react": "catalog:",
37
- "react-dom": "catalog:"
37
+ "@tanstack/react-query": "^5.95.2",
38
+ "react": "^19.2.4",
39
+ "react-dom": "^19.2.4",
40
+ "@dngbuilds/zapkit-core": "0.1.0"
38
41
  },
39
42
  "devDependencies": {
40
43
  "@types/node": "^25.5.0",
41
- "@types/react": "catalog:",
44
+ "@types/react": "^19.2.14",
42
45
  "@typescript/native-preview": "7.0.0-dev.20260316.1",
43
46
  "bumpp": "^11.0.1",
44
47
  "typescript": "^5.9.3",
@@ -53,5 +56,11 @@
53
56
  "starknet": "9.4.2",
54
57
  "starkzap": "2.0.0",
55
58
  "ts-mixer": "6.0.4"
59
+ },
60
+ "scripts": {
61
+ "build": "vp pack",
62
+ "dev": "vp pack --watch",
63
+ "test": "vp test",
64
+ "check": "vp check"
56
65
  }
57
- }
66
+ }