​
Installation

@niledatbase/react contains components and hooks for using the API. It handles sessions, cookies, fetching data, and comes with built-in components to be used as either templates or directly in your application to handle common user tasks. It is designed to be used with @niledatabase/server, which handles API calls itself or forwards them to the regional API for your database. 
npm install @niledatabase/react @niledatabase/client

​
Using the Auth Provider

@niledatabase/react comes with two providers, <SignedIn /> and <SignedOut /> which wrap a central <SessionProvider />. By default, they will fetch a session. <SignedIn /> will only render children if the user is logged in. Conversely, <SignedOut /> will always render its children unless signed in. 
<SignedIn>
   Jerry, hello!
</SignedIn>

<SignedOut>
  No soup for you!
</SignedOut>
It is also possible to be explicit and obtain the session server side. To do that, you would use the following: 
import { SignedIn } from "@niledatabase/react";
import { nile } from "@/lib/nile";

export default async function SignUpPage() {
  const nileCtx = nile.withContext({ headers }) // headers from request
  const session = await nileCtx.auth.getSession(); 

  if (session.status === 'unauthenticated') {
    return <div>No soup for you!</div>
  }

  return (
    <SignedIn session={session}>
      Jerry, hello!
    </SignedIn>
  );
}

​
Functions

​
signIn

makes a POST request to the sign in endpoint. Expects a provider, and optional params for callbackUrl. For the cases of credentials (email + password) and email, you can opt out of redirection by passing redirect: false in the options 
signIn('google', { callbackUrl: '/dashboard' })
signIn('credentials', { callbackUrl: '/dashboard' })

​
signOut

makes a POST request to the sign out endpoint, with an optional params for callbackUrl to redirect the user, and redirect to leave the user on the page, but delete the session and notify the session providers the user has been logged out. 
signOut({ callbackUrl: '/sign-in' }) // go back to some sign in page
signOut({ redirect: false }) // Log out, leave the user on the page they're on

​
Hooks

​
useSession

You can obtain the current session via useSession(). This must be called within a <SignedIn /> or <SignedOut /> provider. 
import { useSession, UserInfo } from "@niledatabase/react";

export default function SignUpPage() {
  const session = useSession();

  if (session.status !== 'authenticated') {
    return <div>Loading...</div>
  }

  return (
    <UserInfo />
  );
}

​
useTenantId

The useTenantId hook manages the current tenant ID, persisting it in cookies and refetching tenant data when necessary. A tenant id is accessible via document.cookie with the name nile.tenant_id. This cookie is used by the server side SDK to make requests to the auth service. 
import { useTenantId } from '@niledatabase/react';

export default function TenantSelector() {
  const [tenantId, setTenantId] = useTenantId();

  return (
    <div>
      <p>Current Tenant: {tenantId ?? 'None'}</p>
      <button onClick={() => setTenantId('new-tenant-id')}>
        Change Tenant
      </button>
    </div>
  );
}
ValueTypeDescription
tenantIdstring | undefinedThe current tenant ID.
setTenantId(tenant: string) => voidFunction to update the tenant ID.
NameTypeDefaultDescription
paramsHookProps & { tenant: Tenant }undefinedInitial tenant data.
clientQueryClientundefinedReact Query client instance.
export type HookProps = {
  tenants?: Tenant[]; // a list of tenants
  onError?: (e: Error) => void; // failure callback
  baseUrl?: string; // fetch origin
};
  • Initializes the tenant ID from params.tenant.id, if provided.
  • If no tenant is found, it attempts to read from a cookie (nile.tenant_id).
  • If no cookie exists, it triggers a refetch of tenants.
  • Calling setTenantId(tenantId) updates both state and cookie.

​
useTenants

The useTenants hook fetches a list of tenants from an API endpoint using React Query. It supports optional preloaded data and can be disabled to prevent automatic queries. 
import { useTenants } from '@niledatabase/react';

export default function TenantList() {
  const { data: tenants, isLoading, error } = useTenants();

  if (isLoading) return <p>Loading tenants...</p>;
  if (error) return <p>Error loading tenants</p>;

  return (
    <ul>
      {tenants?.map((tenant) => (
        <li key={tenant.id}>{tenant.name}</li>
      ))}
    </ul>
  );
}
This hook returns the result of useQuery, which includes:
PropertyTypeDescription
dataTenant[] | undefinedList of tenants.
isLoadingbooleantrue while fetching data.
errorError | nullFetch error, if any.
refetch() => voidFunction to manually refetch tenants.
Parameters
NameTypeDefaultDescription
paramsHookProps & { disableQuery?: boolean }undefinedHook configuration options.
clientQueryClientundefinedOptional React Query client instance.
export type HookProps = {
  tenants?: Tenant[];
  onError?: (e: Error) => void;
  baseUrl?: string;
};
  • If disableQuery is true, the query is disabled.
  • If tenants is provided and not empty (in the event of hydration), the query is also disabled.
  • Otherwise, it fetches tenants from ${baseUrl}/api/tenants using fetch.
  • The request runs only once unless manually refetched.

​
useEmailSignIn

The useEmailSignIn hook provides a mutation for signing in a user using nile auth. It allows customizing the request with callbacks and options for redirection. 
import { useSignIn } from '@your-library/react';

export default function Login() {
  const signIn = useEmailSignIn({
    onSuccess: () => console.log('Login successful'),
    onError: (error) => console.error('Login failed', error),
    redirect: true,
  });

  return (
    <button onClick={() => signIn({ email: 'user@example.com' })}>
      Sign In
    </button>
  );
}
NameTypeDefaultDescription
onSuccess(data: Response) => voidundefinedCallback after a successful sign-in.
onError(error: Error) => voidundefinedCallback if sign-in fails.
beforeMutate(data: any) => anyundefinedFunction to modify data before mutation.
callbackUrlstringundefinedURL to redirect after login.
redirectbooleanfalseWhether to redirect after login.
  • Calls signIn('email', data) with optional modifications via beforeMutate.
  • Throws an error if authentication fails.
  • Redirects if redirect is true.

​
useMe

useMe is a React hook that fetches and returns the current authenticated user. It allows preloading a user via props or fetching from an API endpoint if no user is provided. 
'use client';
import { useMe } from '@niledatabase/react';

export default function Profile() {
  const user = useMe();

  if (!user) return <p>Loading...</p>;

  return <div>Welcome, {user.name}!</div>;
}
NameTypeDefaultDescription
fetchUrlstring/api/meAPI endpoint to fetch the user data.
userUser | undefined | nullundefinedInitial user data, avoids fetching if provided.
  • If a user is passed in props, it is set immediately.
  • If user is not provided, the hook fetches from fetchUrl and updates the state.
  • The request runs only once when the component mounts.

​
useResetPassword

The useResetPassword hook provides a way to handle password reset functionality. It sends reset requests to an authentication API and supports optional callbacks and preprocessing of request data. 
import { useResetPassword } from '@niledatabase/react';

export default function ResetPasswordForm() {
  const resetPassword = useResetPassword({
    onSuccess: () => alert('Password reset successful'),
    onError: (err) => console.error('Error resetting password:', err),
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const formData = new FormData(e.target as HTMLFormElement);
    resetPassword({
      email: formData.get('email') as string,
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" name="email" required placeholder="Enter your email" />
      <button type="submit">Reset Password</button>
    </form>
  );
}
NameTypeDefaultDescription
paramsParamsundefinedHook configuration options.
export type Params = {
  onSuccess?: (data: Response) => void;
  onError?: (error: Error) => void;
  beforeMutate?: (data: MutateFnParams) => MutateFnParams;
  callbackUrl?: string;
  baseUrl?: string;
  fetchUrl?: string;
};
  • Calls the API at ${baseUrl}/api/auth/reset-password (or a custom fetchUrl).
  • Uses PUT for password updates and POST for reset requests.
  • Calls onSuccess or onError based on the request outcome.
  • Runs a CSRF request when the hook is initialized.
  • Allows modifying data before sending using beforeMutate.

​
useSignUp

The useSignUp hook provides a way to handle user sign-up requests. It supports tenant creation, API customization, and session updates after successful registration. 
import { useSignUp } from '@niledatabase/react';

export default function SignUpForm() {
  const signUp = useSignUp({
    onSuccess: () => alert('Sign-up successful!'),
    onError: (err) => console.error('Sign-up failed:', err),
    createTenant: true, // Optionally create a tenant with the email of the user
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const formData = new FormData(e.target as HTMLFormElement);
    signUp({
      email: formData.get('email') as string,
      password: formData.get('password') as string,
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" name="email" required placeholder="Email" />
      <input type="password" name="password" required placeholder="Password" />
      <button type="submit">Sign Up</button>
    </form>
  );
}
NameTypeDefaultDescription
paramsPropsundefinedHook configuration options.
clientQueryClient (optional)undefinedReact Query client instance.
export type Props = {
  onSuccess?: (data: Response, variables: unknown) => void; // success callback
  onError?: (error: Error) => void; // error callback
  beforeMutate?: (data: SignUpInfo) => SignUpInfo; // optional modifications to the data prior to the API call
  callbackUrl?: string; // where the server should redirect users upon successful login
  baseUrl?: string; // configure fetch origin
  createTenant?: boolean | string; // if boolean, will create a tenant named with the user's email, else will be whatever name is provided (maps to /api/tenants?newTenantName=<name>)
};

export type SignUpInfo = {
  email: string;
  password: string;
  tenantId?: string;
  newTenantName?: string;
  fetchUrl?: string;
};
  • Sends a POST request to /api/signup (or a custom fetchUrl).
  • If createTenant is true, assigns newTenantName as the user’s email.
  • If createTenant is a string, it is used as the tenant name.
  • After a successful sign-up:
    • Updates the session.
    • Redirects to callbackUrl if provided, otherwise reloads the page.
  • Prefetches authentication providers and CSRF tokens on mount.

​
useSignIn

The useSignIn hook provides a simple way to authenticate users. It supports pre-processing login data before submission and handles authentication via credentials. 
import { useSignIn } from '@niledatabase/react';

export default function SignInForm() {
  const signIn = useSignIn({
    onSuccess: () => alert('Login successful!'),
    onError: (err) => console.error('Login failed:', err),
  });

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const formData = new FormData(e.target as HTMLFormElement);
    signIn({
      email: formData.get('email') as string,
      password: formData.get('password') as string,
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" name="email" required placeholder="Email" />
      <input type="password" name="password" required placeholder="Password" />
      <button type="submit">Sign In</button>
    </form>
  );
}
NameTypeDefaultDescription
paramsPropsundefinedHook configuration options.
export type Props = {
  onSuccess?: () => void;
  onError?: (error: Error) => void;
  beforeMutate?: (data: LoginInfo) => LoginInfo;
  callbackUrl?: string;
};

export type LoginInfo = {
  email: string;
  password: string;
};
  • Sends a sign-in request using NextAuth’s signIn('credentials', data).
  • If beforeMutate is provided, it modifies the login data before the request.
  • Calls onSuccess if login succeeds.
  • Calls onError if login fails.