Getting Started

This page walks you through the full path to a working integration, from creating your app to letting users log in. Each step links to a deeper page if you want more detail.

A coding agent can follow the same path from Agent skills: https://docs.blux.cc/SKILLS.md.

The flow looks like this:

1. Create an app in the Dashboard and grab your App ID.
2. Pick a package — React or core (vanilla JS) — and install it.
3. Initialize Blux with createConfig / BluxProvider, passing your App ID.
4. Customize appearance, login methods, language, and wallets in the config.
5. Use it — open the built-in modals (login, fundMe, profile) or call the data hooks/functions.

1. Create your app & get an App ID

Sign in at dashboard.blux.cc, create an app, and copy its App ID. The dashboard is also where you manage users, analytics, access rules, and which login providers are enabled.

2. Pick a package & install

Choose based on your stack — @bluxcc/react for React/Next.js/Vite, or @bluxcc/core for any other JavaScript project.

npm install @bluxcc/react

npm install @bluxcc/core

3. Initialize Blux

Wrap your app with BluxProvider (React) or call createConfig once at startup (vanilla JS). The only required option is appId. Leave out networks and the app uses Mainnet. Leave out appName and Blux uses "App". See Networks.

import { BluxProvider } from "@bluxcc/react";

<BluxProvider
  config={{
    appId: "your-app-id",
  }}
>
  {children}
</BluxProvider>

import { createConfig } from "@bluxcc/core";

createConfig({
  appId: "your-app-id",
});

4. Customize the config

Everything below is optional — Blux ships with sensible defaults. Add what you need to the same config object.

• Appearance — match your branding (colors, fonts, radius). → Appearance
• Login methods — choose which auth options appear and in what order. → Login Methods
• Wallets — reorder with orderWallets or hide some with excludeWallets; configure Trezor.
• Language — set the UI language. → Language

Enabling login methods

Add the methods you want to the loginMethods array — order determines display order:

createConfig({
  appId: "your-app-id",
  networks: [core.networks.mainnet],
  loginMethods: ["wallet", "email", "passkey", "google", "meta"],
});

5. Use Blux

Once initialized, you can use built-in modals, build a white-label login UI, or call data hooks/functions. Hosted actions and session state are exposed by useBlux in React and the blux object in vanilla JavaScript.

Built-in modals

import { useBlux } from "@bluxcc/react";

function App() {
  const { login, fundMe, profile, isAuthenticated } = useBlux();
  // login()   → open the auth modal
  // fundMe()  → open the on-ramp modal
  // profile() → open the account modal
}

import { blux } from "@bluxcc/core";

blux.login();   // open the auth modal
blux.fundMe();  // open the on-ramp modal
blux.profile(); // open the account modal

Data hooks & functions

When you want to build your own UI, read chain data and call contracts directly:

• Account data — balances, transactions, payments, offers, and more. → React hooks · Core functions
• Soroban contracts — read and write smart contracts. One read: useReadContract / readContract. Several reads at once: useReadContracts / readContracts. Writes: useWriteContract / writeContract.