Users can sign up and be entered into the database via email + password. A JWT is used (which has a default expiry in 30 days). For Single Sign On, sessions are kept in the database in the auth.session table. @tanstack/react-query and react-hook-form are used to do much of the heavy lifting in the component. The component is styled via tailwind.

​
Installation

npm install @niledatabase/react @niledatabase/client

​
Email + Password Sign In

Uses simple <Email /> and <Password /> fields, along with the useSignIn() hook to sign a user in, if they exist. In most cases, you want to supply a callbackUrl, which is where the user will be redirected upon successful sign in. Error handling works the same as it does in <SignUpForm />

​
Email Only Sign In

With an SMTP provider configured on your database, users can supply their emails and be sent a link for sign in. The users enters their email, which causes the auth service to create a token (saved to the auth.verification_tokens table in your database), and send it in an email. The token is valid for 4 hours by default. Once the user clicks the link, they will exchange their token for a session and be redirected to whichever page was provided in the callbackUrl

​
Hooks

​
useSignIn

The useSignIn hook provides a way to authenticate users using credential-based sign-in within a React application. It utilizes React Query’s useMutation to handle authentication requests and supports optional lifecycle callbacks for customization.

​
Installation

npm install @niledatabase/react @niledatabase/client

​
Usage

import { useSignIn } from "@niledatabase/react";

const SignInComponent = () => {
  const signIn = useSignIn({
    beforeMutate: (data) => ({ ...data, extraParam: "value" }),
    onSuccess: () => console.log("Login successful"),
    onError: (error) => console.error("Login failed", error),
    callbackUrl: "/dashboard",
  });

  const handleLogin = () => {
    signIn({ email: "user@example.com", password: "securepassword" });
  };

  return <button onClick={handleLogin}>Sign In</button>;
};

​
API

useSignIn(params?: Props): (data: LoginInfo) => void
Parameters
NameTypeDescription
paramsProps (optional)Configuration options
Returns
A function that accepts LoginInfo containing user credentials to initiate the sign-in process.

​
Props

NameTypeDescription
callbackUrlstring (recommended)The URL to redirect to upon successful login.
beforeMutate(data: any) => any (optional)Optional function executed before the mutation occurs, allowing modification of request data.
onSuccess(data: LoginSuccess) => void (optional)Callback function triggered on a successful login.
onError(error: Error, data: any) => void (optional)Callback function triggered if the login fails.
clientQueryClient (optional)React Query client instance.
LoginInfo Type
export type LoginInfo = {
  email: string;
  password: string;
};
Example with Error Handling
const signIn = useSignIn({
  onSuccess={async (res) => {
    if (res.ok) {
      // something good happened
    } else {
      const error = await res.text();
      console.error(error);
    }
  }}
  onError={(e)=> {
    console.error('Catastrophic failure 😭', e)
  }}
});

signIn({ email: "user@example.com", password: "wrongpassword" });
  • Ensure that authentication providers are properly configured in your Next.js app.
  • Use beforeMutate to modify request payloads before submission.
  • The callbackUrl parameter determines the redirection URL post-login.

​
Theming

The component is styled using tailwind. It can be customized using the className and buttonText props, or using Tailwind CSS theme variables. You can find more details and full examples in the customization doc. In addition, the hooks documented for each component can be used if you’d like to use Nile Auth with your own components. If needed, you can peek at the source code of the component and use it as a template to create your own component for maximum customization.