@vylth/nexus-react

Nexus SSO SDK for React — add authentication to any VYLTH app in minutes.

Install

npm install @vylth/nexus-react

Quick Start

1. Wrap with NexusProvider

import { BrowserRouter } from 'react-router-dom';
import { NexusProvider } from '@vylth/nexus-react';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <BrowserRouter>
    <NexusProvider
      nexusUrl="https://accounts.vylth.com"
      clientId="YOUR_CLIENT_ID"
    >
      <App />
    </NexusProvider>
  </BrowserRouter>
);

2. Add Callback Route

import { NexusCallback } from '@vylth/nexus-react';

<Route path="/auth/callback" element={
  <NexusCallback
    onSuccess={() => window.location.replace('/')}
    onError={() => window.location.replace('/login')}
  />
} />

The callback route must match the redirect URI registered in Nexus.

3. Use Auth in Components

import { useNexus } from '@vylth/nexus-react';

function MyComponent() {
  const { user, isAuthenticated, isLoading, login, logout } = useNexus();

  if (isLoading) return <Spinner />;
  if (!isAuthenticated) { login(); return null; }

  return (
    <div>
      <p>Welcome, {user.username}</p>
      <p>Role: {user.globalRole}</p>
      <button onClick={logout}>Logout</button>
    </div>
  );
}

4. Login Button

import { NexusLoginButton } from '@vylth/nexus-react';

<NexusLoginButton />

Exports

| Export | Type | Description | |--------|------|-------------| | NexusProvider | Component | Context provider — wrap your app | | NexusCallback | Component | OAuth callback handler | | NexusLoginButton | Component | Pre-styled login button | | useNexus | Hook | Access auth state and user info |

User Fields

interface NexusUser {
  id: string;
  email: string;
  username?: string;
  firstName: string;
  lastName: string;
  avatar?: string;
  globalRole: string;       // citizen, pioneer, navigator, commander, executor
  emailVerified: boolean;
  affiliateCode?: string;
  appRoles?: Record<string, string>;
  twoFactorVerified?: boolean;
}

Prerequisites

1. Register your app in Nexus (accounts.vylth.com → Admin → Manage Apps)
2. Save the client_id from registration
3. Set your redirect URI (e.g., https://yourapp.vylth.com/auth/callback)

Full Docs

See the complete integration guide at accounts.vylth.com/docs