Skip to main content

Installation

Install the SDK​

Pick your package manager:

npm install @one_deploy/sdk@1.1.0
yarn
yarn add @one_deploy/sdk@1.1.0
pnpm
pnpm add @one_deploy/sdk@1.1.0

Peer Dependencies​

The SDK has a small set of peer dependencies. Only react is strictly required; the others are optional and depend on which features you use.

PackageVersionRequired?When needed
react>=18.0.0YesAlways (hooks, providers, components)
react-dom>=18.0.0Only for webWeb widgets (connect button, payment widgets, NFT gallery)
react-native>=0.72.0Only for RNAI trading and forex React Native components
thirdweb>=5.0.0OptionalSmart wallet connect, on-chain reads/writes via OneThirdwebProvider

Install the optional peers you need:

Web app with wallet features
npm install react react-dom thirdweb
React Native (AI trading / forex only)
npm install react react-native
Server / Node (headless, no UI)
npm install react
# react is still needed because hooks are typed against it,
# but no DOM or RN runtime is required.

Package Exports Map​

@one_deploy/sdk uses the exports field in package.json to expose 8 entry points. Each entry point is independently tree-shakable.

Import pathWhat it contains
@one_deploy/sdkRe-exports everything (barrel). Fine for prototyping; prefer specific paths for production.
@one_deploy/sdk/servicesOneEngineClient, PriceService, SupabaseService, UsageService, forexSimulationEngine, botSimulationEngine
@one_deploy/sdk/typesAll TypeScript interfaces and type aliases
@one_deploy/sdk/utilsHelper functions (formatting, validation, chain helpers)
@one_deploy/sdk/configDefault config constants, chain definitions, contract addresses
@one_deploy/sdk/providersOneProvider, OneThirdwebProvider
@one_deploy/sdk/hooksAll 27+ hooks (useOne, useOneAuth, useWalletBalance, useAIStrategies, etc.)
@one_deploy/sdk/componentsWeb-only widgets (connect button, pay widget, onramp, offramp, swap, NFT gallery, balance display)
@one_deploy/sdk/react-nativeReact Native-only components (AI trading selectors, forex cards)

Example -- targeted imports​

// Only pulls in the engine client, nothing else
import { OneEngineClient } from "@one_deploy/sdk/services";

// Only pulls in the swap hook
import { useOneSwap } from "@one_deploy/sdk/hooks";

// Only pulls in TypeScript types (zero runtime cost)
import type { OneConfig, SwapQuote } from "@one_deploy/sdk/types";

Tree-Shaking​

The SDK ships ESM and CommonJS builds. Modern bundlers (Vite, Next.js, esbuild, webpack 5) will automatically tree-shake unused code when you use the specific entry points listed above.

For the best bundle size:

  1. Import from sub-paths instead of the barrel @one_deploy/sdk.
  2. Use import type for anything that is only needed at compile time.
  3. Avoid importing @one_deploy/sdk/react-native in web builds (and vice versa) -- your bundler will warn if platform-specific code leaks across targets.

Bundle impact (approximate)​

What you importGzipped size
OneEngineClient only~8 kB
All hooks~12 kB
Web providers + hooks + components~34 kB
Full barrel import~52 kB

TypeScript​

The SDK ships first-class TypeScript declarations for every export. No @types/* package is needed. Minimum TypeScript version: 5.0.

tsconfig.json (relevant fields)
{
  "compilerOptions": {
    "moduleResolution": "bundler",   // or "node16" / "nodenext"
    "target": "ES2020",
    "strict": true
  }
}

If you use moduleResolution: "node" (legacy), the sub-path exports will still resolve, but "bundler" or "node16" is recommended.

Verify the Installation​

smoke-test.ts
import { OneEngineClient } from "@one_deploy/sdk/services";
import type { OneConfig } from "@one_deploy/sdk/types";

const config: OneConfig = {
  clientId: process.env.ONE_CLIENT_ID!,
  engineUrl: process.env.ONE_ENGINE_URL!,
};

const engine = new OneEngineClient({
  baseUrl: config.engineUrl,
  clientId: config.clientId,
});

console.log("ONE SDK installed. Engine target:", config.engineUrl);

Next Steps​