Introduction

This post documents my process of building authentication in Next.js using Better Auth(opens in a new tab). The goal is to experience a production-ready workflow, since most applications rely on third-party auth rather than building everything from scratch in-house every time. I am following the Master Senior Level Authentication(opens in a new tab) tutorial but adapting it to my own preferences. This project comes right after my deep dives into a Go HTTP server and Go Authentication and Authorization, along with my post on the scratch-built Next.js Authentication Master Class(opens in a new tab) from the same channel. Throughout this post, I will contrast this Node.js implementation with the Go strategies I used previously. I also want to understand the implicit technical decisions Better Auth makes that I skipped in my own NextJS Auth Core project.

I created a basic frontend template in Next.js using TailwindCSS, ShadcnUI, and Drizzle ORM. This post focuses purely on the backend logic, so I won't detail the UI setup.

Database Index

Right out of the gate, the Better Auth documentation(opens in a new tab) provides multiple helper CLI commands that can even set up the database schema for us. Following the tutorial steps was straightforward with no major technical hurdles. However, it was a great learning opportunity to observe how the library structures the schema—specifically, choosing which columns to index for better performance. Indexing is something I did not consider extensively when setting up my previous projects from scratch. Looking at the generated migration file, it becomes clear that we should always index columns accessed frequently, such as the user ID across most tables or important values like session tokens. I also learned that Postgres implicitly indexes any column declared as UNIQUE or PRIMARY KEY.

Looking at the Drizzle schema, we can analyze the line (table) => [index("account_userId_idx").on(table.userId)] to understand the reasoning behind explicit indexing. If you are unfamiliar with Drizzle syntax, we can always inspect the generated migration file to look at the raw SQL directly. The SQL output is much simpler to digest.

For this table, Postgres implicitly indexes the primary key id already. However, the user_id column is declared later as a foreign key linking back to the user table.

Imagine a user with the user_id of james-123 signs up using Google OAuth. This creates one row in the account table. The same user might return the next day and sign in using a different OAuth provider like GitHub. They remain the exact same user with the user_id of james-123. This action creates a brand new row in the account table with a new unique id but the exact same user_id of james-123.

This scenario explains why we cannot declare the user_id column as UNIQUE—a single user can absolutely have multiple rows in the account table representing different linked providers. When the application needs to fetch all linked accounts for a specific user, an unindexed user_id column would force Postgres to perform a slow full-table scan. To prevent that performance bottleneck, we explicitly create an index on the user_id column.

The Hybrid Approach

Another smart thing Better Auth does is cache the session data in the cookie instead of querying the database for every request, even though we set up a session table. This hybrid approach feels very similar to the workflow in my Go Authentication and Authorization project. But instead of juggling access and refresh tokens, we are simply dealing with a single session state.

Better Auth first creates a 30-day session and stores it in the database. Then it signs the session data, places it in a cookie, and sets a very short internal cache validity—typically 5 minutes. For the next 5 minutes, every client request is validated purely via the fast math of a cookie signature with zero database lookups. On minute six, Better Auth sees the cache expire, silently pauses, checks the database to ensure the 30-day session is still valid, signs a new 5-minute cache, and lets the user proceed.

When it comes to revoking access, there are two scenarios. The first is self-revocation. When a user logs out, the server deletes the session in the database and immediately sends back an HTTP response header instructing the browser to clear the cookie. The cache is instantly destroyed, and access is revoked perfectly.

The second scenario is remote revocation. An admin can manually delete the database session row for a malicious user. Although the user's browser still holds a mathematically valid signed cookie, it only lives for a maximum of 5 more minutes—a totally acceptable trade-off for the massive performance gain.

Better Auth handles all this complexity under the hood. From a Next.js frontend perspective, we only need to call useSession. The library manages the tokens, catches expirations, and retries requests automatically. As a developer, the only requirement is configuring it properly inside auth.ts.

OAuth Integration

Integrating OAuth providers with Better Auth is very straightforward. First, configure the OAuth application properly in the provider's developer dashboard, such as the GitHub Developer Portal(opens in a new tab) or the Google Cloud Console(opens in a new tab). The Better Auth Documentation(opens in a new tab) provides a comprehensive guide for this setup.

Next, set up the appropriate frontend function. The author of the tutorial video created some fancy wrappers to make the social auth buttons support multiple OAuth providers dynamically. You can totally skip all that complexity. Instead, simply implement it using the main authClient.signIn.social function and pass the specific provider name like "github" or "google".

This single line makes the OAuth sign-in work perfectly. There is no need to modify the database schema because the original schema prepared by the Better Auth CLI helper is already designed to accommodate OAuth accounts automatically.

Email Verification and Password Resets

These two features are essential in modern authentication systems. Unlike the tutorial video, I am not setting up an actual email service like Postmark or Resend here. Most production applications rely on paid services to handle email delivery, ensuring strict compliance and avoiding spam folders. It is unwise for a developer to design an email delivery service from scratch.

For this local project, I will simply use the email integration functions provided by the Better Auth library to intercept the data. Instead of routing the payload to an actual inbox, I will console log the email address and the secure token URL.

To set up both the email verification and reset password features, modify the auth.ts configuration.

If you want to implement real email delivery later, simply replace these console log functions with your own customSendEmail function and follow the provider's guide.

After applying this setup, Better Auth actively prevents any unverified account from signing in. It checks the verification table in the database under the hood to determine the user's status. During local development, make sure to check your running terminal, find the mock email log, and manually click the verification link to complete the sign-up simulation.

Next, we need a frontend UI prompting users to resend the verification email if they lose it.

When building buttons that trigger emails, it is crucial to implement rate limiting to prevent malicious actors from spamming the endpoint and running up your email provider bill. Fortunately, Better Auth implicitly implements backend rate-limiting behind the authClient.sendVerificationEmail function. However, we still need to guard against impatient users mashing the button on the frontend through intentional UI throttling.

The tutorial author attached a basic 30-second countdown timer to the button. When a user first lands on the verification page, the system automatically sends the initial email and disables the resend button for 30 seconds. It works, but the timer is entirely stateless. If an impatient user refreshes the browser with 15 seconds still remaining, the component remounts and resets the countdown back to a full 30 seconds. Instead of a smooth experience, the user is forced to wait even longer. This is a minor UI flaw, but it is definitely worth fixing for a robust user experience.

Architecture Improvement: URL State as the Source of Truth

If you strictly follow the tutorial's frontend code, you might notice a strange bug. Whenever you refresh the login page, it aggressively resets back to the default "Sign In" view. This happens because the original design uses a local React state to toggle between tabs like Sign In, Sign Up, Reset Password, and Email Verification. All these views share the exact same URL path, which is a known architectural anti-pattern.

The standard practice is to make the webpage URL the single source of truth for the user's location. If a user copies a link while looking at the "Forgot Password" tab and pastes it into a new browser, it should open that exact tab. The proper way to achieve this in Next.js is by utilizing URL search parameters.

With this new design, data is no longer trapped in volatile component state. Next.js will read a URL like ?tab=email-verification&email=james@test.com(opens in a new tab) and render the correct UI immediately.

Notice that when we consume the useSearchParams hook to make a component dependent on the client's request URL, Next.js requires us to wrap that specific component in a Suspense boundary. This is a strict framework rule. Because reading search parameters happens dynamically on the client, failing to wrap the hook in a Suspense boundary forces Next.js to de-optimize the entire route and abandon static rendering at build time. By isolating the dynamic URL reader inside Suspense, the rest of the page layout remains fast and statically optimized. There is no useState hook cluttering this component anymore—the render output purely reflects the URL.

Profile Management

For simple profile management like updating a password or name, just set up a straightforward form and use the authClient.updateUser method. Changing an email address is more complex and requires verification, so we need to enable it inside auth.ts. Once again, I will route the mock email to the terminal logs where you can click the link to verify the new address.

The UI form itself is very similar to the sign-in component. The only complicated part is the update handler function because changing an email requires a completely different method than updating a name.

While reviewing the tutorial, I spent some time trying to understand why the author used Promise.all and destructured the results. I realized they were trying to run two promises concurrently—one for updating the user profile and another for changing the email. This approach makes the code unnecessarily complex and introduces a subtle bug. A simpler approach is to run the promises sequentially to avoid a swallowed state situation present in the original code. Before presenting my solution, let us look at the flaw in the author's logic.

Inside the profile update handler, the author uses multiple conditional statements to handle errors from the concurrent promises. Imagine a scenario where a user tries to update their name and change their email at the exact same time. If the name update fails but the email update succeeds, the success state of the email change gets completely swallowed. The user experiences a confusing UI state—the webpage displays a "Failed to update profile" error, yet a verification email for the new address quietly arrives in their inbox with zero frontend acknowledgement.

This pattern is a fundamental mistake because Promise.all should generally be avoided when dealing with side-effect-heavy mutations. It all comes down to whether we are reading or writing data. When fetching from multiple sources concurrently to render a dashboard, Promise.all is perfect. But when we execute promises with permanent side effects like updating a database record and triggering an email, we must run them sequentially to handle errors stage by stage.

Here is my improved version that runs the mutations sequentially. I also included a guard clause to check if the profile data was actually modified before making unnecessary database calls.

Change and Set Password

Handling password updates is straightforward. We simply provide a standard change password form to normal users and a set password form to OAuth users. OAuth users log in without a password by default, meaning the logic to set a new password is fundamentally identical to a standard password reset flow.

Modern applications allow users to log in across multiple devices simultaneously. When a user changes their password, we must provide an option to revoke all other active sessions to ensure account security. Better Auth builds this feature directly into the changePassword method—you only need to pass a boolean flag to trigger it.

For the set password form targeting OAuth users, we provide a button that triggers a password reset email. This email contains a link that redirects the user to the exact same password reset page used in the standard forgot password flow.

When you click the mock link in your terminal during development, notice that the URL contains a secure token like http://localhost:3000/api/auth/reset-password/k0BBoBPRXjI6e9ZOQY7fJPeB?callbackURL=%2Fauth%2Freset-password(opens in a new tab). The actual reset password page reads this URL token to verify the user's identity before committing the change.

Session Management

Session management is another area where Better Auth shines with simplicity. The library provides helper methods to retrieve active sessions from the database directly. This makes it trivial to list all active devices for a user and allow them to revoke access as needed.

On the actual session management page, it is crucial to separate the current active session from the others. This filtering prevents users from accidentally locking themselves out of their active window. We can then provide explicit options to either revoke all other sessions globally or target a specific device.

In the snippet above, I omitted the boilerplate UI code to focus purely on the core logic. The remaining code in my repository simply uses frontend components to display parsed device details like the browser, operating system, device name, and connection date.

Account Linking

Account linking allows a user to attach multiple external identities—like a GitHub and a Google account—to their single central profile. This architecture can sometimes cause confusion, but it simply means one user row in the database can have multiple related account rows.

Once again, I will skip the frontend rendering details. The core logic simply involves listing all accounts, filtering out standard password-based credential accounts, and hooking up the native Better Auth link and unlink methods.

Delete Account

Deleting an account is another straightforward process with Better Auth. However, since this is a highly destructive operation, we must add extra configuration inside auth.ts. This enables the feature and enforces a secure verification step to prevent accidental deletions.

For the actual account deletion page, the UI can be as simple as a button that calls the deleteUser method on the authClient and passes a callback URL to redirect the user to the home page upon success.

In the tutorial, the author uses a fancy custom button component to trigger an extra confirmation prompt before wiping the data. Adding a confirmation step is an excellent practice for any destructive action. You can easily use the Alert Dialog(opens in a new tab) component from Shadcn UI to accomplish the exact same thing, which is the approach I took in my own implementation.