DEV Community: Sacha

Auth with Next.js+Auth.js+MongoDB, and RBAC -bonus topic: JWT

Sacha — Tue, 22 Jul 2025 11:28:46 +0000

This is a note to self on implementing authentication, using Next.js, Auth.js, and MongoDB, allowing role-based access control, and beginner's notes about JWT as a bonus topic.

Authentication and RBAC

Tools

Next.js
- Here, we use Server Actions to handle authentication.
Auth.js
- Here, we use the login method of credentials (email and password).
MongoDB
bcrypt
- This is for password hashing.
- We should install TypeScript definitions for bcrypt as well by npm install --save-dev @types/bcrypt.

Directory Structure

project
 └─ src
     └─ app
     │   └─ page.tsx  <- renders LoginForm.tsx
     └─ components
     │   └─ loginForm.tsx
     └─ lib
     │   └─ actions.ts
     │   └─ db.ts
     └─ types
     │   └─ next-auth.d.ts
     └─ auth.config.ts
     └─ auth.ts
     └─ middleware.ts

Code

Omitting the styling purpose codes.

import LoginForm from "@/components/loginForm";
import { Suspense } from "react";

export default function Home() {
  return (
    <Suspense>
      <LoginForm />
    </Suspense>
  );
}

"use client";

import { Button } from "@/components/ui/button";
import { useActionState } from "react";
import { authenticate } from "@/lib/actions";
import { useSearchParams } from "next/navigation";

export default function LoginForm() {
  const searchParams = useSearchParams();
  const callbackUrl =
    searchParams.get("callbackUrl") || "/patient-status-display";
  const [errorMessage, formAction, isPending] = useActionState(
    authenticate,
    undefined
  );

  return (
    <form action={formAction} className="space-y-3">
      <div className="w-full">
        <div>
          <label htmlFor="email">
            Email
          </label>
          <input
            id="email"
            type="email"
            name="email"
            placeholder="Enter your email address"
            required
          />
        </div>
        <div>
          <label htmlFor="password">
            Password
          </label>
          <input
            id="password"
            type="password"
            name="password"
            placeholder="Enter password"
            required
            minLength={6}
          />
        </div>
      </div>

      <input type="hidden" name="redirectTo" value={callbackUrl} />

      <Button aria-disabled={isPending}>
        Log in
      </Button>

      <div
        aria-live="polite"
        aria-atomic="true"
      >
        {errorMessage && (
          <p className="text-sm text-red-500">{errorMessage}</p>
        )}
      </div>

    </form>
  );
}

There are three inputs sent as formData here: email, password, and redirectTo, which is hidden from the UI. RedirectTo is automatically set considering the search params of the page URL, allowing the user to go back to the page that they were on after logging in.

server actions

// /lib/actions.ts

"use server";

import { signIn } from "@/auth";
import { AuthError } from "next-auth";

export async function authenticate(
  prevState: string | undefined,
  formData: FormData
) {
  console.log("from actions.ts - ", formData);

  try {
    await signIn("credentials", formData);
  } catch (error) {
    if (error instanceof AuthError) {
      switch (error.type) {
        case "CredentialsSignin":
          console.error("Invalid credentials");
          return "Invalid credentials.";
        default:
          console.error("An unexpected error occurred:", error);
          return "Something went wrong.";
      }
    }
    throw error;
  }
}

The outcome of logging formData to the console is like this:

FormData {
'$ACTION_REF_2': '',
'$ACTION_2:0': '{"id":"idconsistofrandomcharsandnumbers","bound":"$@1"}',
'$ACTION_2:1': '["$undefined"]',
'$ACTION_KEY': 'keyconsistofacharandnumbers',
email: 'admin@email.com',
password: '123456',
redirectTo: '/patient-status-display'
}

This Server Actions function authenticate() triggers the Credentials provider's authorize() function in auth.ts below.

middleware-purpose code (middleware.ts and auth.ts)

-1. middleware.ts

// /middleware.ts

import NextAuth from 'next-auth';
import { authConfig } from './auth.config';

export default NextAuth(authConfig).auth;

export const config = {
  // https://nextjs.org/docs/app/building-your-application/routing/middleware#matcher
  matcher: ['/((?!api|_next/static|_next/image|.*\\.png$).*)'],
};

-2. auth.ts (This is necessary separately from middleware.ts because bcrypt relies on Node.js APIs not available in Next.js Middleware.)

// /auth.ts

import NextAuth from "next-auth";
import Credentials from "next-auth/providers/credentials";
import { authConfig } from "./auth.config";

// MongoDB and Auth.js connection purpose things
import { MongoDBAdapter } from "@auth/mongodb-adapter";
import client from "./lib/db";

import { z } from "zod";
import { User } from "@/types/db";
import bcrypt from "bcrypt";


// helper function to get a user from db and return a user object.
async function getUser(email: string): Promise<User | undefined> {
  try {
    // specify the database name and table name
    const db = client.db("Surgery-Status");
    const users = db.collection("User");

    const user = await users.findOne({ email });
    console.log("Raw user result:", user);

    if (!user) {
      return undefined;
    }

    return {
      id: user._id.toString(),
      username: user.username,
      email: user.email,
      password: user.password,
      role: user.role,
    } as User;

  } catch (error) {
    console.error("Failed to fetch user:", error);
    throw new Error("Failed to fetch user.");
  }
}


export const { handlers, auth, signIn, signOut } = NextAuth({
  ...authConfig,
  session: {
    strategy: "jwt",
  },
  // adapter: MongoDBAdapter(client), //edit: this is for session strategy of "database", not "jwt"!
  providers: [
    Credentials({
      async authorize(credentials) {
        console.log("from auth.ts - credentials: ", credentials);

        // validation by Zod
        const parsedCredentials = z
          .object({ email: z.email(), password: z.string().min(6) })
          .safeParse(credentials);

        console.log("from auth.ts - parsedCredentials: ", parsedCredentials);

        if (!parsedCredentials.success) {
          console.log("from auth.ts - Invalid credentials");
          return null;
        }

        // call getUser helper function and retrieve the user from db.
        const { email, password } = parsedCredentials.data;
        const user = await getUser(email);
        console.log("from auth.ts - user: ", user);
        if (!user) return null;

        // check if the password input matches the user's password using bcrypt.
        const passwordsMatch = await bcrypt.compare(password, user.password);
        if (!passwordsMatch) return null;
        return user;
      },
    }),
  ],
});

Outcome of logging credentials:

{
'$ACTION_REF_2': '',
'$ACTION_2:0': '{"id":"608d2e3498577677e1980778f144b62db597e78013","bound":"$@1"}',
'$ACTION_2:1': '["$undefined"]',
'$ACTION_KEY': 'k3886862053',
email: 'admin@email.com',
password: '123456',
callbackUrl: '/patient-status-display'
}

*the same object as formData

Outcome of logging parsedCredentials:

{
success: true,
data: { email: 'admin@email.com', password: '123456' }
}

Outcome of logging raw user result in getUser:

{
_id: new ObjectId('687a1ecc6e0c2baed2f73a00'),
username: 'Admin',
email: 'admin@email.com',
password: '$2b$10$Aio9fK46uuXn5nMidbKhv.uk.Izp3V2ceQltitKWJiisbr4VpFrgq',
role: 'admin'
}

Returned valid user from this authorize() function if everything is successful:

{
id: '687a1ecc6e0c2baed2f73a00',
username: 'Admin',
email: 'admin@email.com',
password: '$2b$10$Aio9fK46uuXn5nMidbKhv.uk.Izp3V2ceQltitKWJiisbr4VpFrgq',
role: 'admin'
}
*This returned user object is just returned internally to Auth.js.
-> Then, Auth.js creates a session (JWT), sets a cookie, and redirects the user.

MongoDB client code
- taken from Auth.js docs

// /lib/db.ts

// This approach is taken from https://github.com/vercel/next.js/tree/canary/examples/with-mongodb
import { MongoClient, ServerApiVersion } from "mongodb"

if (!process.env.MONGODB_URI) {
  throw new Error('Invalid/Missing environment variable: "MONGODB_URI"')
}

const uri = process.env.MONGODB_URI
const options = {
  serverApi: {
    version: ServerApiVersion.v1,
    strict: true,
    deprecationErrors: true,
  },
}

let client: MongoClient

if (process.env.NODE_ENV === "development") {
  // In development mode, use a global variable so that the value
  // is preserved across module reloads caused by HMR (Hot Module Replacement).
  const globalWithMongo = global as typeof globalThis & {
    _mongoClient?: MongoClient
  }

  if (!globalWithMongo._mongoClient) {
    globalWithMongo._mongoClient = new MongoClient(uri, options)
  }
  client = globalWithMongo._mongoClient
} else {
  // In production mode, it's best to not use a global variable.
  client = new MongoClient(uri, options)
}

// Export a module-scoped MongoClient. By doing this in a
// separate module, the client can be shared across functions.
export default client

auth.config.ts (RBAC is set here.)

// /auth.config.ts

import type { NextAuthConfig } from "next-auth";

export const authConfig = {
  pages: {
    signIn: "/",
  },
  callbacks: {
    jwt({ token, user }) {
      console.log(token, user) //*1
      if (user) {
        token.role = user.role;
      }
      return token;
    },

    session({ session, token }) {
      console.log(sessioin, token) //*2
      if (token && session.user) {
        session.user.role = token.role as string;
        // if we omit this^, the `role` field won't be available in the session on the browser.
      }
      return session;
    },

    authorized({ auth, request: { nextUrl } }) {
      console.log("auth from authorized callback - ", auth);

      const isLoggedIn = !!auth?.user;
      const userRole = auth?.user?.role;

      // check the route that the user is trying to access.
      const isOnStatusDisplay = nextUrl.pathname.startsWith(
        "/patient-status-display"
      );
      const isOnStatusUpdate = nextUrl.pathname.startsWith(
        "/patient-status-update"
      );
      const isOnPatientInfo = nextUrl.pathname.startsWith(
        "/patient-information"
      );

      // redirect unauthenticated users to login page.
      // patient-status-display page is available for unauthenticated users, so it's not included in the condition.
      if (!isLoggedIn && (isOnStatusUpdate || isOnPatientInfo)) {
        return false;
      }

      // if already authenticated, do role-based access control.
      if (isLoggedIn) {
        // admin can access all pages
        if (userRole === "admin") {
          return true;
        }

        // member cannot access patient-information. Redirect to patient-status-display in which case.
        if (userRole === "member" && isOnPatientInfo) {
          return Response.redirect(new URL("/patient-status-display", nextUrl));
        }

        // member cannot access the unavailable pages. Redirect to patient-status-display in which case.
        if (!isOnStatusDisplay && !isOnStatusUpdate && !isOnPatientInfo) {
          return Response.redirect(new URL("/patient-status-display", nextUrl));
        }

        // member can access the pages which is outside the conditions above.
        return true;
      }

      return true;
    },
  },
  providers: [], // this is just to satisfy the specified structure.
} satisfies NextAuthConfig;

Pages option allows us to specify the route for custom sign-in, sign-out, and error pages. By setting this, the user will be redirected to our custom login page, rather than the NextAuth.js default page.

Callbacks option contains three functions.

Jwt function is necessary to take the custom fields (in this case, role) from the user object (which is returned from DB) and store them in the JWT. This runs at login, and then the JWT is stored in the cookie on the browser.

Outcome of logging token and user (*1) (if a user is logged in):

token: {
email: 'admin@email.com',
sub: '687a1ecc6e0c2baed2f73a00',
role: 'admin',
iat: 1753258099,
exp: 1755850099,
jti: 'a82b44b4-c226-4216-bba5-63100f9e134e'
}
user: undefined

Session function is necessary to define what should be returned as a session from useSession() (in the client) or getServerSession() (in the server), or auth() (for both client and server) (related part in Auth.ts docs). This runs when the client or the server asks for session data, copying the custom fields from the JWT in this case. (Here, we are talking about the case where the session strategy is JWT, not database.)

Outcome of logging session and token (*2) (if a user is logged in):

session: {
user: { name: undefined, email: 'admin@email.com', image: undefined },
expires: '2025-08-22T08:08:19.085Z'
}
token: {
email: 'admin@email.com',
sub: '687a1ecc6e0c2baed2f73a00',
role: 'admin',
iat: 1753258099,
exp: 1755850099,
jti: 'a82b44b4-c226-4216-bba5-63100f9e134e'
}

Authorized function is in charge of protecting the routes, depending on whether or not the user is authenticated, or which role the user has. The property auth contains the user's session, and the request property contains the incoming request.
Under the hood, the following steps are happening...
-1. This grabs the JWT stored in the cookie.
-2. Then, verifies and decodes it using the NEXTAUTH_SECRET.
(-3. Then, if necessary, runs jwt() callback to reconstruct the final token.)
-4. Finally, converts that decoded token into an object, which is available in the function as a variable auth.

Outcome of logging auth (if a user is logged in):

{
user: { email: 'admin@email.com', role: 'admin' },
expires: '2025-08-19T11:38:31.810Z'
}
*The expiration date comes from the format of JWT; by default, JWT includes exp claim (≒ field) when it's created.

Update the NextAuth types to avoid type errors

// /types/next-auth.d.ts

import NextAuth from "next-auth";

declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      email: string;
      role: string;
    } & DefaultSession["user"];
  }

  interface User {
    id: string;
    email: string;
    role: string;
  }
}

declare module "next-auth/jwt" {
  interface JWT {
    role: string;
  }
}

What I would like to explore further

In this case, I used Next.js Server Actions to access the database. Now I'm wondering how I can use the backend constructed with Node.js+Express.js to handle authentication with this stack, because I use the backend outside Next.js for the other APIs in this project for some reason. I also would like to know whether it's generally recommended to let the backend handle authentication as well in this case, or it's alright to use Server Actions just for authentication.

Side Note - JWT vs database as a session strategy

Session is the way we keep track of the logged-in user for authorization purposes.
There are two types of strategies how we manage sessions —database (session ID) and JWT.

database (session ID)
- This is stateful, meaning the server has the information necessary for authorization. The only thing transmitted is just session ID, and using it, the server needs to access the storage to extract the necessary info for authorization.
- When a user logs in, the server issues a session ID.
- Server stores the session ID along with the user's information in the session storage.
- Client stores the issued session ID in a cookie. Client sends this cookie every time it makes requests.
- Server accesses the stored user's info, verifies the authorization status based on the session ID contained in the cookie sent with the request.
JWT
- This is stateless, meaning the server doesn't have the information necessary for authorization. JWT itself contains it, so all the server has to do is just check it.
- When a user logs in, the server issues a JWT.
- Client stores the issued JWT in a cookie. Client adds this JWT to the header of the request when making it.
- Server verifies the JWT and its signature.

References

Combining Client and Server Components in Next.js for Better Performance

Sacha — Tue, 08 Jul 2025 07:03:44 +0000

This is to explore how we can combine client and server components for better performance. We will use a search bar functionality utilizing URL search params (not state) in an app as an example case.

Code

// Page component

import Pagination from "@/app/ui/invoices/pagination";
import Search from "@/app/ui/search";
import Table from "@/app/ui/invoices/table";
import { CreateInvoice } from "@/app/ui/invoices/buttons";
import { lusitana } from "@/app/ui/fonts";
import { InvoicesTableSkeleton } from "@/app/ui/skeletons";
import { Suspense } from "react";

export default async function Page(props: {
  searchParams?: Promise<{
    query?: string;
    page?: string;
  }>;
}) {
  const searchParams = await props.searchParams;
  const query = searchParams?.query || "";
  const currentPage = Number(searchParams?.page) || 1;

  return (
    <div className="w-full">
      <div className="flex w-full items-center justify-between">
        <h1 className={`${lusitana.className} text-2xl`}>Invoices</h1>
      </div>
      <div className="mt-4 flex items-center justify-between gap-2 md:mt-8">
        <Search placeholder="Search invoices..." />
        <CreateInvoice />
      </div>
      <Suspense key={query + currentPage} fallback={<InvoicesTableSkeleton />}>
        <Table query={query} currentPage={currentPage} />
      </Suspense>
      <div className="mt-5 flex w-full justify-center">
        {/* <Pagination totalPages={totalPages} /> */}
      </div>
    </div>
  );
}

// Search component

"use client";

import { MagnifyingGlassIcon } from "@heroicons/react/24/outline";
import { usePathname, useRouter, useSearchParams } from "next/navigation";
import { useDebouncedCallback } from "use-debounce";

export default function Search({ placeholder }: { placeholder: string }) {
  const searchParams = useSearchParams();
  const pathname = usePathname();
  const { replace } = useRouter();

  const handleSearch = useDebouncedCallback((term: string) => {
    const params = new URLSearchParams(searchParams);
    if (term) {
      params.set("query", term);
    } else {
      params.delete("query");
    }
    replace(`${pathname}?${params.toString()}`);
  }, 300);

  return (
    <div className="relative flex flex-1 flex-shrink-0">
      <label htmlFor="search" className="sr-only">
        Search
      </label>
      <input
        className="peer block w-full rounded-md border border-gray-200 py-[9px] pl-10 text-sm outline-2 placeholder:text-gray-500"
        placeholder={placeholder}
        onChange={(e) => handleSearch(e.target.value)}
        defaultValue={searchParams.get("query")?.toString()}
      />
      <MagnifyingGlassIcon className="absolute left-3 top-1/2 h-[18px] w-[18px] -translate-y-1/2 text-gray-500 peer-focus:text-gray-900" />
    </div>
  );
}

// InvoicesTable component

import Image from 'next/image';
import { UpdateInvoice, DeleteInvoice } from '@/app/ui/invoices/buttons';
import InvoiceStatus from '@/app/ui/invoices/status';
import { formatDateToLocal, formatCurrency } from '@/app/lib/utils';
import { fetchFilteredInvoices } from '@/app/lib/data';

export default async function InvoicesTable({
  query,
  currentPage,
}: {
  query: string;
  currentPage: number;
}) {
  const invoices = await fetchFilteredInvoices(query, currentPage);

  return (
    <div className="mt-6 flow-root">
      <div className="inline-block min-w-full align-middle">
        <div className="rounded-lg bg-gray-50 p-2 md:pt-0">
          <div className="md:hidden">
            {invoices?.map((invoice) => (
              <div
                key={invoice.id}
                className="mb-2 w-full rounded-md bg-white p-4"
              >
              . . .

How this search bar functionality with URL search params works

The key to understanding what's happening is how Next.js App Router handles URL search parameters and passes them to page components.
The overview of the complete flow looks like this:

1. User types in search box
         ↓
2. Search component calls handleSearch()
         ↓
3. URL gets updated to /dashboard/invoices?query=searchTerm
         ↓
4. Next.js detects URL change, re-renders Page component with new searchParams
         ↓
5. Page component extracts query and currentPage
         ↓
6. These get passed to Table component
         ↓
7. Table component fetches filtered data

Here is the breakdown of each step.

-1. User types in search box
Nothing to say here. Just let them type whatever!

-2. Search component calls handleSearch()
The handleSearch function in the Search component gets called, creates searchParams for the URL and updates it.

  const handleSearch = useDebouncedCallback((term: string) => {
    // Creates a new URLSearchParams object
    const params = new URLSearchParams(searchParams);

    // Sets ?query=searchTerm or delete the parameter
    if (term) {
      params.set("query", term);
    } else {
      params.delete("query");
    }

    // Updates the URL without a page refresh
    replace(`${pathname}?${params.toString()}`);
  }, 300);

-3. URL gets updated to /dashboard/invoices?query=searchTerm
Thanks to the previous step!

-4. Next.js detects URL change, re-renders Page component with new searchParams
This occurs without a full page reload thanks to the Next.js App Router feature.

-5. Page component extracts query and currentPage
This is the Next.js App Router's nature. When we have a Page component, Next.js App Router automatically passes certain props to it based on the URL and route structure. This includes searchParams.
SearchParams has a JavaScript object-like structure.
E.g.) the search params for the URL /dashboard/invoices?query=john&page=2 would look like this: {query: 'john', page: '2'}.

Here, Next.js automatically extracts the search parameters from the URL and passes them to the page component as the searchParams prop.
When the URL is /dashboard/invoices?query=john&page=2, the extracted search params will look like this:

{
  searchParams: Promise<{
    query: "john",
    page: "2"
  }>
}

-6. These get passed to Table component in the Page component

  const searchParams = await props.searchParams;
  const query = searchParams?.query || "";
  const currentPage = Number(searchParams?.page) || 1;

  return (
    . . .
      <Table query={query} currentPage={currentPage} />
    . . .
  )

-7. Table component fetches filtered data
It calls fetchFilteredInvoices() function passing query and currentPage as the arguments.

Side Note

Notice that the Search component is a client component, whereas the Page and the Table components are server components. The Search component has to interact with the user input and manipulate the URL, so it must be a client component.
Notice that, in order to extract the URL search parameters, we use useSearchParams() in the Search component (which is a client component) because accessing the URL directly with this method on the client is faster than waiting for Next.js to send the info from the server to the client.

// if it's on the client 
const searchParams = useSearchParams();
const query = searchParams.get('query'); // <- Instant, no network ◎

// if it's on the server
const { searchParams } = props;
const query = searchParams?.query; // <- Needs server rendering △

Notice that, in order to fetch the data and show the table according to the URL search parameters, we use searchParams prop in the Page component (which is a server component) and then pass them to the Table component (also a server component) because this way takes fewer network trips than doing everything from the client.

// if it's on the client
"use client";
function ClientComponent () {
  const searchParams = useSearchParams();
  const query = searchParams.get('query');

  const [data, setData] = useState(null);
  useEffect(() => {
    fetch(`/api/invoices?query=${query}`)
      .then(res => res.json())
      .then(setData);
  }, [query]);

  return <div>{data?.map(...)}</div>;
}
// ^ Needs to call the data fetching API using the search params AFTER loading the page structure (empty placeholder) with JS code, resulting in double network trips △

// if it's on the server
async function ServerComponent ({ searchParams }) {
  const query = searchParams?.query;
  const data = await fetchFilteredInvoices(query); // <- Direct DB access
  return <div>{data.map(...)}</div>;
}
// ^ This approach can get the page structure AND the data at the same time, resulting in only one network trip ◎
// Server does this BEFORE sending a response on the first request:
// 1. Next.js extracts searchParams from URL
// 2. Page component receives searchParams  
// 3. Table component gets query prop
// 4. fetchFilteredInvoices() runs on server
// 5. Server gets data from database
// 6. Server renders complete HTML with data

The key difference is when the URL search parameters are available.

Client-Side Flow:

1. Server sends HTML (searchParams not available yet)
2. JavaScript loads in browser
3. useSearchParams() can now read URL
4. Now make API request with parameters
visualized:
Browser                              Server
   │                                    │
   │ ──── GET /invoices?query=john ───> │
   │                                    │ (can't access searchParams until JS runs in browser)
   │ <────── HTML + JS (no data) ────── │
   │                                    │
   │        (JS runs, reads URL)        │
   │                                    │
   │ ── GET /api/invoices?query=john ─→ │
   │ <────────── JSON data ──────────── │

Server-Side Flow:

1. Next.js extracts searchParams from URL immediately
2. Server components can use searchParams right away
3. Server fetches data and renders complete HTML
4. Send everything together
visualized:
Browser                          Server
   │                                │
   │ ── GET /invoices?query=john ─> │
   │                                │ (Next.js immediately extracts searchParams)
   │                                │     ↓
   │                                │ fetchFilteredInvoices(query)
   │                                │     ↓
   │ <─ Complete HTML with data ─── │

References:
Learn Next.js Chapter 11

📖 Course Menu - Efficient Data Fetching in Next.js

Sacha — Mon, 07 Jul 2025 05:35:37 +0000

Note: I'm always talking about server components here.

🍸 Aperitif - Waterfall vs Parallel Data Fetching

Waterfall Data Fetching

Sequence of await usages
- Wait until the previous fetch is complete.

Parallel Data Fetching

Promise.all()
- When one of the fetches is slower than the others,

🥗 Hors d'oeuvres - Static vs Dynamic Rendering

Static Rendering

Data fetching and rendering happen only when
- building the application (during deployment)
- revalidating data
The cached data is served whenever a user visits the application.
Pros:
- Pre-rendered content can be cached when deploying, resulting in faster websites.
- The server doesn't have to send the content because it's already cached, resulting in reduced server load.
- Search engines can read the pre-rendered content, resulting in improved SEO.
Suitable for webpages with no data or data that is common for the users, such as a static blog post or a product page. Not a good fit for data-heavy pages.

Dynamic Rendering

Data fetching and rendering happen when a user visits the page (at request time).
Pros:
- Allows us to show real-time and up-to-date data.
- Makes it easier to deal with personalized content, from showing it to updating it based on user interactions.
- Allows us to access the information that we can only know at the request time, such as cookies or the URL search parameters.
If one of the requests is slow, the app is only as fast as the slowest request.

🥘 Main - Streaming

Streaming

A data transfer technique that allows us to break down a route into smaller chunks and progressively stream them from the server to the client as they become ready.
Pros:
- Slow data requests don't block the entire page from showing. The user can interact with the ready parts of the page.

How to implement this with Next.js:

At the page level, with the loading.tsx file (which creates <Suspense>)
- We can just have a loading.tsx file in the route, then Next.js presents it while the content is loading.
At the component level, with <Suspense>
- Move the data fetching logic to the child component that we wanna stream.
- In the parent component, wrap the child component with <Suspense> and pass props of a fallback component.
- We can also have a component to wrap multiple components to load them at the same time. (streaming for the section)

☕️ Dessert - Partial Prerendering (PPR)

Experimental in Next.js 14.

Combination of static rendering, dynamic rendering, and streaming on one route.
When the user visits the PPR route,
- a static route shell containing static content is served first. (Static content is actually prerendered during build time or revalidation.)
- the shell leaves holes where dynamic content will load asynchronously.
- the async holes are streamed in parallel.
<Suspense> plays a role as a boundary between the static and dynamic content. When we wrap a component with <Suspense>, we are telling Next.js to treat the wrapped content dynamically.

References:
Learn Next.js Chapter 8 - 10

Git Rebase 101 (What, Why, When, and How)

Sacha — Fri, 27 Sep 2024 13:20:13 +0000

The other day, I had an invaluable opportunity to learn about git rebase. It took me some time to fully understand the command's behaviour and its benefits. This article is kind of my learning note, but I hope this will also help fellow developers out there deepen their knowledge! Also, if you find anything incorrect or have something to say, please feel free to leave comments or reach out to me on any platform!

What is Git Rebase?

Git rebase is a git command that lets you integrate a history in one branch to another, without creating additional merge commits. In other words, when using it, all the commit history appears on one branch linearly without additional merge commits, resulting in looking as if all the changes were made on the branch upfront and there was no other working branch in the first place.

Visualized Example

The initial state: A feature branch is created from the commit A. Then, three new commits are created on the main branch (B, C, D), and two commits are created on the feature branch (X, Y).

   main: A -- B -- C -- D
feature: A -- X -- Y

Before merging the feature branch to the main branch, we have to reflect the new commits on the main branch (B, C, D) to the feature branch. This is the case where git rebase comes in handy. We can run git rebase on the feature branch. The histories will look like below:

   main: A -- B -- C -- D
feature: A -- B -- C -- D -- X -- Y

As you can see, the three commits on the main branch (B, C, D) are inserted into the feature branch before the commits X and Y. (Potentially, we might see some conflicts here, in which case we should solve them manually.)

Now, we can peacefully merge the feature branch to the main. The histories after the merge will look like below:

   main: A -- B -- C -- D -- X -- Y
feature: A -- B -- C -- D -- X -- Y

💡 Technically, the commits X and Y after rebasing are not the same as the ones before rebasing. In this example case, the rebase command performed on the feature branch rewinds the commit history to the root commit (A), places the commits to be integrated (B, C, D), and re-creates the commits rewinded (X, Y) again (we can call them X' and Y'). So, the commit X' and Y' are different commits from X and Y that contain the same information as X and Y.
   main: A -- B -- C -- D
feature: A -- X -- Y

  ↓ rebase main to feature

   main: A -- B -- C -- D
feature: A -- B -- C -- D -- X' -- Y'

  ↓ merge feature to main

   main: A -- B -- C -- D -- X' -- Y'
feature: A -- B -- C -- D -- X' -- Y'

Why Git Rebase?

One thing to notice from the example above is there's no merge commit on either the main or feature branches. This is the main reason why we want to use this command.

To appreciate this more clearly, let me take a look at the case where we use git pull and merge on the example above.

   main: A -- B -- C -- D
feature: A -- X -- Y

  ↓ pull and merge main to feature

   main: A -- B -- C -- D
feature: A -- X -- Y -- M(B--C--D)

  ↓ merge feature to main

   main: A -- B -- C -- D -- M(X--Y--M(B--C--D))
feature: A -- X -- Y -- M(B--C--D)

We can obviously see that the histories are getting complex because of the merge commits. Git rebase is a powerful way to avoid this.

💡 Why do we want to keep the histories simple? There could be a lot of answers to this question, but the main idea is to make it easier to understand who did what and when. This would be beneficial for code reviewers, project managers, and newly joined team members who are trying to catch up with the team.

When to Git Rebase?

We should use git rebase when...

we want to integrate some commits from one branch into another, keeping the histories simple.
- Basically, when we want to perform git pull + merge, rebase could be an alternative.

When NOT to?

We should not use git rebase when...

the branch whose history we want to add changes to is shared with others.
- Since git rebase changes the commit history (as seen on the feature branch from the example case above,) if we perform git rebase on a shared branch, it will cause confusion and conflicts with the branch in the others' environment.
the commits are already pushed to GitHub.
- This is actually prohibited. If you perform git rebase on such commits and try to push them to GitHub again, GitHub doesn't accept this push.
we can expect a lot of conflicts.
- Because the command checks every commit to find whether there are conflicts and stops the process if found till the conflict is resolved, it would be troublesome to use this when too many conflicts are expected.
we want to keep merge and branch integration histories.
- If we intentionally want to keep them, of course we should not use rebase. Git pull + merge would be the way.

How to Git Rebase?

Let me re-follow the example case with the actual commands we should run.

Initial state:
   main: A -- B -- C -- D
feature: A -- X -- Y

1.Checkout to the feature branch (git checkout feature)
2.Perform git rebase (git rebase main)

Result of step #2:
   main: A -- B -- C -- D
feature: A -- B -- C -- D -- X' -- Y'

3.Checkout to the main branch and merge feature to main (git checkout main then git merge feature)

Result of step #3:
   main: A -- B -- C -- D -- X' -- Y'
feature: A -- B -- C -- D -- X' -- Y'

💡 In the real-world scenario, step #3 is most likely to be replaced by pushing the feature branch to GitHub and creating a PR to merge it to the main.