From 46b7f694a932940bdf839179f8330e9c1029e9fd Mon Sep 17 00:00:00 2001 From: signor1 Date: Sat, 30 May 2026 13:09:56 +0100 Subject: [PATCH] =?UTF-8?q?chore(docs):=20clarify=20install=20=E2=80=94=20?= =?UTF-8?q?one=20package=20for=20React=20apps?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The landing CTA and the docs install page used to suggest installing both @usewhisk/react and @usewhisk/core, which is misleading: core is a regular dependency of react and is pulled in automatically, and every type and helper is re-exported, so React apps never need to install or import @usewhisk/core directly. - Landing CTA install snippet drops to a single package. - Docs install page is rewritten as a decision tree: lead with the one command, call out @tanstack/react-query as the one required peer, gate Solana adapters as optional, and reserve @usewhisk/core for the framework-agnostic case (Node, Vue/Svelte, server-side). - Type-safe bento snippet imports from @usewhisk/react so it matches the new guidance. --- apps/docs/src/components/marketing/cta.tsx | 4 +- .../components/marketing/feature-bento.tsx | 10 ++-- .../content/docs/getting-started/install.mdx | 54 +++++++++++++++---- 3 files changed, 50 insertions(+), 18 deletions(-) diff --git a/apps/docs/src/components/marketing/cta.tsx b/apps/docs/src/components/marketing/cta.tsx index 42baec5..6207a30 100644 --- a/apps/docs/src/components/marketing/cta.tsx +++ b/apps/docs/src/components/marketing/cta.tsx @@ -25,8 +25,8 @@ export function CTA({ className }: { className?: string }) { version.

-
- +
+
diff --git a/apps/docs/src/components/marketing/feature-bento.tsx b/apps/docs/src/components/marketing/feature-bento.tsx index e60beac..9f6d8cf 100644 --- a/apps/docs/src/components/marketing/feature-bento.tsx +++ b/apps/docs/src/components/marketing/feature-bento.tsx @@ -42,7 +42,7 @@ const FEATURES = [ }, { title: "Type-safe end to end", - body: "Chain names are a real union type from @usewhisk/core. A typo fails the build, not the user.", + body: "Chain names are a real union type from @usewhisk/react. A typo fails the build, not the user.", Icon: ShieldCheck, span: "md:col-span-1", visual: , @@ -193,9 +193,9 @@ function ChainGridVisual() { } /** - * Real Whisk `Chain` union from `@usewhisk/core` (see - * `packages/core/src/types/chain.ts`). A typo fails at the - * TypeScript layer, never at runtime. + * Real Whisk `Chain` union from `@usewhisk/react` (re-exported from + * `@usewhisk/core`, see `packages/core/src/types/chain.ts`). A typo + * fails at the TypeScript layer, never at runtime. */ function TypeSafeVisual() { const lines: CodeLine[] = [ @@ -203,7 +203,7 @@ function TypeSafeVisual() { { t: "import type", c: "keyword" }, { t: " { Chain } " }, { t: "from", c: "keyword" }, - { t: ' "@usewhisk/core"', c: "string" }, + { t: ' "@usewhisk/react"', c: "string" }, ], [ { t: "const", c: "keyword" }, diff --git a/apps/docs/src/content/docs/getting-started/install.mdx b/apps/docs/src/content/docs/getting-started/install.mdx index 8f74903..866a329 100644 --- a/apps/docs/src/content/docs/getting-started/install.mdx +++ b/apps/docs/src/content/docs/getting-started/install.mdx @@ -1,27 +1,59 @@ --- title: Install -description: Get the Whisk packages and their wallet-layer peers into your project. +description: One package for almost everyone. Here is what to install, and when. --- -Whisk lives in two packages. The React package pulls in the core -engine automatically and re-exports the helpers you'll touch most -often, so installing it once is usually enough: +For a React app, install one package: - + -The React package speaks to wallets through `wagmi` (EVM) and -`@solana/wallet-adapter-react` (Solana). If your app already uses -them, you can skip ahead. If not, install them now: +That is enough for most integrations. `@usewhisk/react` bundles the +core engine as a regular dependency and re-exports the helpers and +types you will actually touch (`Chain`, `Token`, `Quote`, `FeeBearer`, +`chainInfo`, `addressResolver`, `composeResolvers`, and more), so every +import in your app comes from `@usewhisk/react`. You never need to +write `@usewhisk/core` in an import path. - +## The one required peer -Solana support is optional. Add these only if you'll be sending from -a Solana address: +`@usewhisk/react` uses `wagmi` internally, which needs +`@tanstack/react-query` as a peer. If your app does not have it yet, +add it: + + + +`wagmi` and `viem` themselves are bundled (regular dependencies of +`@usewhisk/react`), so they are already in your `node_modules` after the +first install. Add them to your own `package.json` only if you also call +`wagmi`/`viem` APIs directly in your own code and want to pin a version. + +## Solana support (optional) + +Add these only if your widget should accept sends from a Solana wallet +(Phantom, Solflare, Backpack). EVM-only apps can skip this: +## Going headless or framework-agnostic + +There is exactly one situation that calls for installing `@usewhisk/core` +on its own: you want to run the engine **outside React**, for example +in a Node script, a Vue or Svelte app, or a server-side flow. + + + +`@usewhisk/core` is framework-agnostic. It exposes `createWhisk()` +plus the chain registry, fee logic, resolvers, error classes, and the +state-machine reducer. No DOM, no React, no wallet imports. + + + If you are using React, you do **not** need to install `@usewhisk/core` + directly. The React package already includes it, and every type and helper you + need is re-exported from `@usewhisk/react`. + + ## Import the stylesheet once Whisk's styles are scoped to a `[data-whisk]` attribute selector, so