@tuwaio/sdk

@tuwaio/sdk is the Layer 8 (L8) package of the TUWA SDK: one package for React apps that re-exports the client packages of the TUWA projects under subpaths — Orbit Utils, Pulsar (transaction tracking), Satellite Connect (wallet connection), SIWX (sign-in with a wallet) and Nova UI Kit (connect and transaction components) — with the Nova stylesheets. Chain support comes from its two add-ons, @tuwaio/evm-sdk and @tuwaio/solana-sdk; none of the subpaths below loads EVM or Solana code.

🏛️ Core Capabilities

• One version to install: the TUWA packages and the libraries they share (zustand, immer, framer-motion, Radix UI, react-toastify, dayjs) are dependencies of @tuwaio/sdk, so a release of the SDK pins a set of TUWA versions that work together. react and react-dom are peer dependencies: the app keeps one copy of React.
• Subpaths: every subpath re-exports one entry point of a TUWA package, unchanged (see Subpaths). Its reference is on the site of that package.
• Stylesheets: @tuwaio/sdk/styles/*.css are copies of the compiled stylesheets of Nova Core, Nova Connect and Nova Transactions, with the fonts of Nova Core next to them in dist/styles/fonts. The app does not need Tailwind CSS.

💾 Installation

pnpm add @tuwaio/sdk react react-dom

Then add the chains of your app:

# EVM
pnpm add @tuwaio/evm-sdk @wagmi/core viem
 
# Solana
pnpm add @tuwaio/solana-sdk @solana/kit

pnpm (8 and later), npm (7 and later) and Bun also install the Wallet Standard peers of @tuwaio/solana-sdk (@wallet-standard/app, base, features, react, ui and ui-registry); with Yarn, add them to the command.

Do not install the re-exported TUWA packages separately at other versions: two copies of a package with a store or a React context, such as @tuwaio/satellite-react or @tuwaio/nova-connect, do not share their state or their types.

Import the stylesheets once, for example in the global CSS file of the app:

@import '@tuwaio/sdk/styles/all.css';

all.css joins nova-core.css (the --tuwa-* theme variables and the motions of the pixel icons), nova-connect.css and nova-transactions.css; import them one by one to leave one out.

Nova draws the pixel icons of @tuwaio/nova-icons in its look of paper and ink. For its classic look with Heroicons, install @heroicons/react (an optional peer, needed only for this) and give the set to every Nova provider the app renders. A NovaTransactionsProvider outside NovaConnectProvider takes its own icons:

pnpm add @heroicons/react

import { NovaConnectProvider } from '@tuwaio/sdk/nova-connect';
import { heroicons } from '@tuwaio/sdk/nova-core/heroicons';
import { NovaTransactionsProvider } from '@tuwaio/sdk/nova-transactions/providers';
import type { ComponentProps } from 'react';
 
export function ClassicNovaConnect(props: ComponentProps<typeof NovaConnectProvider>) {
  return <NovaConnectProvider {...props} icons={heroicons} />;
}
 
export function ClassicNovaTransactions(props: ComponentProps<typeof NovaTransactionsProvider>) {
  return <NovaTransactionsProvider {...props} icons={heroicons} />;
}

🧭 Subpaths

@tuwaio/sdk/nova-connect/evm and @tuwaio/sdk/nova-connect/solana re-export the chain entry points of Nova Connect for the add-ons; import them as @tuwaio/evm-sdk/nova-connect and @tuwaio/solana-sdk/nova-connect. They need the chain packages that the add-ons install, and going through @tuwaio/sdk makes their chain registration and types apply to the same copy of Nova Connect and Satellite React as the other subpaths.

@tuwaio/sdk/satellite/react re-exports @tuwaio/satellite-react with its own names, for @tuwaio/payments-sdk: the Payments module takes Nova, Satellite, Pulsar and Orbit from the subpaths of this package, so an app has one copy of each. Payments are not part of this package: apps without them install nothing of it.

🚀 Usage

The providers of an EVM app with a connect button:

'use client';
 
import { EVMConnectorsWatcher } from '@tuwaio/evm-sdk/nova-connect';
import { satelliteEVMAdapter } from '@tuwaio/evm-sdk/satellite';
import { NovaConnectProvider } from '@tuwaio/sdk/nova-connect';
import { ConnectButton } from '@tuwaio/sdk/nova-connect/components';
import { SatelliteConnectProvider } from '@tuwaio/sdk/satellite';
import { createConfig, http, injected } from '@wagmi/core';
import type { ReactNode } from 'react';
import { mainnet } from 'viem/chains';
 
const appChains = [mainnet] as const;
const wagmiConfig = createConfig({ chains: appChains, connectors: [injected()], transports: { [mainnet.id]: http() } });
const adapter = satelliteEVMAdapter(wagmiConfig, appChains);
 
export function Providers({ children }: { children: ReactNode }) {
  return (
    <SatelliteConnectProvider adapter={adapter} autoConnect>
      <EVMConnectorsWatcher wagmiConfig={wagmiConfig} />
      <NovaConnectProvider appChains={appChains}>{children}</NovaConnectProvider>
    </SatelliteConnectProvider>
  );
}
 
export function Header() {
  return <ConnectButton />;
}

The full setup — EVM and Solana, transaction tracking with Pulsar and Nova Transactions, SIWX sign-in and Quasar sync — is the Full-Stack React guide . Ready-made apps are in the starter templates .

The versions in this package go together: Nova UI Kit 0.11 shows a transaction sped up in the wallet as one operation, followed to its result, and needs @tuwaio/pulsar-core 0.12, which comes with it. An app with its own labels adds their new required keys: actions.replacementFailed in Nova Transactions, cancelled and transactionCancelled in Nova Connect. Nova Transactions 0.15.1 names the two regions of its toasts for screen readers (the transaction toasts and the validation errors): an app with its own toast or validationError labels adds their region key. Nova Icons 0.1.1 adds PowerIcon to /nova-icons/24/outline and SpacecraftIcon to /nova-icons/tuwa, and QuasarLoader of Nova Core 0.15.2 takes motion="assemble": the pixel mark assembles from its pixels as it appears. Nova Icons 0.1.2 adds the speaker to /nova-icons/24/outline: SpeakerWaveIcon with sound and SpeakerXMarkIcon muted. Nova Core 0.15.3 darkens the veil behind an open dialog and makes it a variable, --tuwa-backdrop (ink at 68% in the light theme, near-black at 76% in the dark one): set it to change the strength. Nova Icons 0.1.3 adds SparklesSlashIcon to /nova-icons/tuwa, the star of Sparkles struck through, for a switch of visual effects that is off.

🗄️ Browser Storage

@tuwaio/sdk saves nothing itself. The re-exported packages use these browser storage keys; each page lists when they are written:

• orbit-core:lastConnectedConnector, orbit-core:recentlyConnectedConnectorsListHelpers: the last connection and the recent wallets, in localStorage, or in sessionStorage until the tab closes when rememberWallet of SatelliteConnectProvider is false or “Remember this wallet” of Nova Connect is unticked (@tuwaio/satellite-core, read by Nova Connect);
• satellite-connect:impersonatedAddress in localStorage: the impersonated address (@tuwaio/satellite-core);
• the name passed to createPulsarStore in localStorage: the tracked transactions (@tuwaio/pulsar-core);
• siwx-react:session in localStorage: the SIWX session shown in the UI (@tuwaio/siwx-react);
• nova-transactions:closedToasts in localStorage: the keys of up to 50 pending transactions whose toast was closed, so it stays closed after a page load (@tuwaio/nova-transactions).

🌐 External Services

@tuwaio/sdk sends no requests itself. Of the packages it re-exports, only @tuwaio/nova-core does: it loads network and wallet icons that @web3icons/common does not have from raw.githubusercontent.com (details ). The chain requests (RPC endpoints, ENS, SNS, Pimlico, Safe Transaction Service) come from the chain packages of the add-ons: see @tuwaio/evm-sdk and @tuwaio/solana-sdk. The SIWX endpoints are those of your server.

📄 License

Licensed under the Apache-2.0 License. See the LICENSE  file for details.