DEV Community: Renan Leonel

Building a Scalable i18n System in React

Renan Leonel — Fri, 02 May 2025 11:51:39 +0000

Internationalization (i18n) is critical for applications targeting a global audience. This guide explores a modular, scalable approach to i18n in React that automatically processes translation files and persists language preferences through cookies.

By the end, you'll have a robust i18n system that automatically detects and loads translation namespaces, persists language preferences, separates translations by feature, and scales effortlessly as your application grows.

You can find the source code for this tutorial on GitHub.

Core Concepts and Setup: Understanding i18n and project initialization
Automatic Configuration: The magic of auto-detecting translations
Translation Organization and Usage: Structuring and implementing translations
Extending Your i18n System: Adding languages and scaling

Core Concepts and Setup

Internationalization involves adapting your application to different languages and regional preferences, including:

Translation of text content
Formatting of dates, numbers, and currencies
Handling of pluralization

Our implementation focuses on modularity, automation, and persistence. Let's start by setting up our project:

pnpm add i18next react-i18next i18next-browser-languagedetector js-cookie @types/js-cookie

First, define a Language enum for type safety:

// src/domain/enums/language.ts
export enum Language {
  EN = "en",
  PT_BR = "pt-br",
}

Automatic Configuration

The cornerstone of our scalable i18n system is the config.ts file that automatically discovers and loads translation files:

// src/i18n/config.ts
import i18n from "i18next";
import Cookies from "js-cookie";
import { initReactI18next } from "react-i18next";
import { Language } from "@/domain/enums/language";
import LanguageDetector from "i18next-browser-languagedetector";

type Context = Record<string, { default: Record<string, string> }>;
type Resources = Record<string, Record<string, Record<string, string>>>;

function loadTranslationFiles() {
  const resources: Resources = {};

  Object.values(Language).forEach((lang) => {
    resources[lang] = {};
  });

  const enContext: Context = import.meta.glob<{
    default: Record<string, string>;
  }>("./locales/en/**/*.json", { eager: true });

  const ptBrContext: Context = import.meta.glob<{
    default: Record<string, string>;
  }>("./locales/pt-br/**/*.json", { eager: true });

  const processContext = (context: Context, lang: Language) => {
    Object.keys(context).forEach((path) => {
      const filename = path.match(/\/([^/]+)\.json$/)?.[1];
      const module = context[path];

      resources[lang][filename] = "default" in module ? module.default : module;
    });
  };

  processContext(enContext, Language.EN);
  processContext(ptBrContext, Language.PT_BR);

  return resources;
}

const resources = loadTranslationFiles();
const cookieOptions = { expires: 365 };

i18n
  .use(LanguageDetector)
  .use(initReactI18next)
  .init({
    resources,
    fallbackLng: Language.EN,
    detection: {
      order: ["cookie", "navigator"],
      lookupCookie: "i18next",
    },
    interpolation: { escapeValue: false },
    ns: Object.keys(resources.en),
  });

export const changeLanguage = (lang: Language) => {
  i18n.changeLanguage(lang);
  Cookies.set("i18next", lang, cookieOptions);
};

export default i18n;

Breaking Down the Configuration

Let's understand how this configuration works:

a) Language Enum:
First, we define a Language enum that contains all supported languages. This provides type safety throughout the application:

   // src/domain/enums/language.ts
   export enum Language {
     EN = "en",
     PT_BR = "pt-br",
   }

b) Resource Structure:
We create TypeScript types to ensure proper typing for our translation resources:

   type Context = Record<string, { default: Record<string, string> }>;
   type Resources = Record<string, Record<string, Record<string, string>>>;

c) Automatic Resource Discovery:
The loadTranslationFiles function is where the magic happens:

   const enContext: Context = import.meta.glob<{
     default: Record<string, string>;
   }>("./locales/en/**/*.json", { eager: true });

This uses Vite's glob import to find all JSON files within the locales directory for each language. The eager: true option ensures these are loaded synchronously.

d) Resource Processing:
The processContext function extracts the namespace from each file path and organizes translations:

   const processContext = (context: Context, lang: Language) => {
     Object.keys(context).forEach((path) => {
       const filename = path.match(/\/([^/]+)\.json$/)?.[1];
       const module = context[path];

       resources[lang][filename] =
         "default" in module ? module.default : module;
     });
   };

This extracts the filename (which becomes the namespace) using regex and adds the translations to the appropriate language and namespace.

e) Language Detection and Persistence:

   detection: {
     order: ['cookie', 'navigator'],
     lookupCookie: 'i18next',
   }

This configuration:

Checks cookies first, then browser settings for language preference
Uses a cookie named 'i18next' to store the preference

f) Language Change Helper:

   export const changeLanguage = (lang: Language) => {
     i18n.changeLanguage(lang);
     Cookies.set("i18next", lang, cookieOptions);
   };

This function provides a convenient way to change languages and persist the preference in a cookie that can be used across the application

Translation Organization and Usage

With automatic configuration in place, organize translations by feature or context:

src/
└── i18n/
    ├── config.ts
    └── locales/
        ├── en/
        │   ├── common.json
        │   ├── index.json
        ├── pt-br/
        │   ├── common.json
        │   ├── index.json

Example translation files:

// src/i18n/locales/en/index.json
{
  "greeting": "Hello, World!",
  "languageSelector": "Select a language",
  "languages": {
    "en": "English",
    "pt-BR": "Portuguese"
  }
}

// src/i18n/locales/pt-BR/index.json
{
  "greeting": "Olá, Mundo!",
  "languageSelector": "Selecione um idioma",
  "languages": {
    "en": "Inglês",
    "pt-BR": "Português"
  }
}

The key advantage: any new JSON file added to these folders is automatically detected and processed without code changes.

Using translations in components is straightforward:

const App = () => {
  const { t } = useTranslation();

  return (
    <div className="min-h-screen flex flex-col bg-[#101010]">
      <Header />
      <main className="flex-1 flex items-center justify-center p-6">
        <p className="text-white text-2xl">{t("index:greeting")}</p>
      </main>
    </div>
  );
};

Extending Your i18n System

Adding a new language is simple:

a) Update the Language enum:

export enum Language {
  EN = "en",
  PT_BR = "pt-br",
  ES = "es", // New language
}

b) Modify the config.ts file:

const esContext: Context = import.meta.glob<{
  default: Record<string, string>;
}>("./locales/es/**/*.json", { eager: true });

processContext(esContext, Language.ES);

c) Create corresponding translation files in a new folder structure:

src/i18n/locales/es/
├── common.json
├── index.json

Final Thoughts

Our i18n implementation offers several key advantages:

Modularity: Translations organized by feature/context for easy maintenance
Automation: New files automatically detected and processed
Type Safety: Using TypeScript enums prevents errors
Persistence: User language preferences are remembered
Scalability: Adding new languages or namespaces is simple

This approach works particularly well for growing applications, allowing team members to work on different features without conflicts. For more information, check out the documentation for react-i18next, i18next, and js-cookie.

Mastering React Performance

Renan Leonel — Thu, 13 Mar 2025 02:12:27 +0000

Optimizing React apps isn’t always easy—I’ve dealt with slow renders, laggy interactions, and unresponsive UIs more times than I can count. Over time, I’ve learned a range of techniques, from quick fixes to advanced optimizations, that I rely on daily to keep applications fast and responsive. In this guide, I’ll share the most effective ones. By the end, you’ll have practical insights to improve your app’s performance.

We'll explore:

Smart Data Manipulation: Optimizing array operations and data structures
Strategic Rendering: Preventing unnecessary re-renders
Advanced Memoization: Using React's optimization hooks effectively
Function and Event Optimization: Writing performant event handlers
Component Virtualization: Efficiently handling large lists
Data Fetching and Caching: Optimizing API interactions with React Query
Debouncing and Throttling: Controlling high-frequency events
Suspense for Data Fetching: Managing asynchronous data efficiently

Smart Data Manipulation

The way we manipulate data can dramatically impact our application's performance. Small improvements in data handling can lead to significant performance gains, especially when dealing with large datasets.

Array Operations Order

The order of array operations can significantly impact performance. Consider the difference between map().filter() and filter().map():

// Less efficient: Transforms all items, then filters
const inefficientResult = largeArray
  .map((item) => transformExpensiveOperation(item))
  .filter((item) => item.isValid);

// More efficient: Filters first, then only transforms what's needed
const efficientResult = largeArray
  .filter((item) => isValidBeforeTransform(item))
  .map((item) => transformExpensiveOperation(item));

When filter() comes first, we avoid unnecessary transformations on items that will be filtered out. This becomes especially important with large datasets or expensive transformations. The performance impact grows with the size of the array and the complexity of the transformation function.

For example, if you have 10,000 items but only 100 meet your criteria, placing filter() first means you'll only perform the expensive transformation 100 times instead of 10,000 times. This can be the difference between a smooth experience and a frozen UI.

Maps vs. Arrays for Lookups

For frequently accessed data, using JavaScript's Map instead of arrays can provide dramatic performance improvements:

// O(n) lookup time - gets slower as array grows
const findUserInArray = (users: User[], id: string) => {
  return users.find(user => user.id === id);
};

// O(1) lookup time - consistent speed regardless of size
const findUserInMap = (usersMap: Map<string, User>, id: string) => {
  return usersMap.get(id);
};

// Transform array to Map for repeated lookups
const createUsersMap = (users: User[]) => {
  const usersMap = new Map();

  users.forEach(user => usersMap.set(user.id, user));

  return usersMap;
};

// Usage
const users = [
  /* array of user objects */
];

const usersMap = createUsersMap(users);

// Fast lookup
const user = usersMap.get("user-123");

The Map data structure offers several advantages over plain objects:

Better performance for frequent additions and removals
Keys can be any value (not just strings)
Built-in size property and iteration methods

This approach is ideal for data that's referenced multiple times throughout your application, especially in deeply nested components. The performance difference becomes exponentially larger as your dataset grows.

Consider a scenario where you frequently need to look up users by ID across multiple components. With an array, each lookup requires iterating through thousands of items, making performance degrade as the dataset grows. In contrast, using a Map enables constant-time lookups, ensuring consistent speed regardless of the number of users. For data-intensive applications, this optimization can drastically improve responsiveness and scalability.

Single-Pass Data Transformation

Combine multiple operations into a single pass when possible:

// Inefficient: Multiple array iterations
const filtered = data.filter((item) => item.active);
const transformed = filtered.map((item) => transform(item));
const total = transformed.reduce((sum, item) => sum + item.value, 0);

// Efficient: Single pass with reduce
const { filtered, transformed, total } = data.reduce(
  (result, item) => {
    if (!item.active) return result;

    const transformedItem = transform(item);

    result.filtered.push(item);
    result.transformed.push(transformedItem);
    result.total += transformedItem.value;

    return result;
  },
  { filtered: [], transformed: [], total: 0 },
);

When working with large datasets, each additional iteration through the array adds significant overhead. By using a single-pass approach with reduce(), you traverse the array just once while performing all necessary operations. This technique is particularly valuable for data processing tasks that involve multiple transformations and aggregations.

The single-pass approach becomes even more valuable when working with server data that needs to be normalized, transformed, and aggregated before being used in your application. It reduces both CPU usage and memory overhead by eliminating intermediate array allocations.

Strategic Rendering

React's rendering behavior is often the most significant performance bottleneck in complex applications. Understanding how to prevent unnecessary re-renders can dramatically improve your application's responsiveness.

Component Boundaries

One of the most effective ways to prevent cascading re-renders is to create strategic component boundaries:

// Problematic: Child re-renders when any parent state changes
const ParentComponent = () => {
  const [count, setCount] = useState(0);
  const [unrelatedState, setUnrelatedState] = useState(false);

  return (
    <div>
      <button onClick={() => setUnrelatedState(!unrelatedState)}>
        Toggle unrelated state
      </button>

      {/* This will re-render even when only unrelatedState changes */}
      <div>
        <ComplexComponent count={count} />
      </div>
    </div>
  );
};

// Improved: Isolated component only re-renders when its props change
const ParentComponentImproved = () => {
  const [count, setCount] = useState(0);
  const [unrelatedState, setUnrelatedState] = useState(false);

  return (
    <div>
      <button onClick={() => setUnrelatedState(!unrelatedState)}>
        Toggle unrelated state
      </button>

      {/* Isolate the component that depends on count */}
      <CountContainer count={count} />
    </div>
  );
};

// This only re-renders when count changes
const CountContainer = React.memo(({ count }) => {
  return <ComplexComponent count={count} />;
});

Component boundaries are crucial for performance in large React applications. Each time a component re-renders, all of its children re-render as well, unless specifically optimized. By strategically breaking your UI into smaller components and using React.memo() at key boundaries, you can prevent entire subtrees from re-rendering unnecessarily.

This becomes especially important for components that:

Have expensive rendering logic
Contain many child components
Display large amounts of data
Implement animations or visualizations

Creating these boundaries doesn't just improve performance—it also leads to more maintainable code by enforcing better separation of concerns and more focused components.

Reference Preservation

Maintaining stable references is crucial for preventing unnecessary re-renders:

// Problematic: New object and function created on every render
const Component = () => {
  const options = { sortBy: "name", limit: 10 };
  const handleClick = () => console.log("Clicked");

  return <ChildComponent options={options} onClick={handleClick} />;
};

// Improved: Stable references with useMemo and useCallback
const ComponentImproved = () => {
  // Memoize options object to keep the reference stable unless dependencies change
  const options = useMemo(
    () => ({
      sortBy: "name",
      limit: 10,
    }),
    [],
  );

  // useCallback memoizes the function to avoid re-creating it on each render
  const handleClick = useCallback(() => {
    console.log("Clicked");
  }, []); // empty dependency array ensures the function is memoized once

  return <ChildComponent options={options} onClick={handleClick} />;
};

In React, equality checks for objects and arrays are based on reference comparison, not by value. This means that even if two objects have identical properties, they are treated as distinct if they have different references. For example, {id: 1} === {id: 1} evaluates to false because each object is a separate instance, even though they contain the same data.

When passing objects or functions as props to memoized components, creating new references on every render defeats the purpose of memoization. React will treat each render as a change, triggering unnecessary re-renders, even if the data itself hasn't changed.

This issue affects several common patterns:

Passing object literals as props
Creating inline functions in render methods
Defining arrays inside components
Creating complex state transformations

By using hooks like useMemo and useCallback, you can ensure that references remain stable across renders unless dependencies actually change. useMemo helps to memoize the creation of objects or arrays, while useCallback ensures that functions are not recreated unless their dependencies change. This allows React’s memoization mechanisms (such as React.memo) to work effectively, preventing unnecessary re-renders and improving performance throughout your component tree.

Advanced Memoization

Strategic useMemo Usage

Rather than memoizing everything, focus on expensive calculations:

// Overkill: Memoizing a simple operation
const sum = useMemo(() => a + b, [a, b]);

// Appropriate: Memoizing expensive calculations
const sortedFilteredData = useMemo(() => {
  return expensiveSort(filterByMultipleConditions(largeDataset, filters));
}, [largeDataset, filters]);

When considering memoization, always evaluate the cost of the computation versus the cost of memoization itself. Memoization adds memory overhead and some performance cost for dependency comparisons. For simple operations, this overhead might exceed the benefits.

Memoization is most valuable for:

Complex sorting or filtering operations
Data transformations with multiple steps
Calculations that involve iterating over large arrays
Derived values that might trigger re-renders when recalculated

The key is to identify the expensive operations in your application and apply memoization selectively. I generally apply memoization when dealing with operations that are computationally expensive, such as mapping or filtering large datasets, or performing any operation that involves traversing through data and could require another O(n) operation.

Function and Event Optimization

Defining Functions Outside Components

One of the simplest but effective ways to optimize your React components is to define functions that don't rely on component state or props outside of the component. This prevents these functions from being recreated on every render, improving performance in large applications.

Consider the following example:

// Avoid: Creating a new function on every render
const Component = ({ data }) => {
  const formatDate = (date) => {
    return new Date(date).toLocaleDateString();
  };

  return (
    <div>
      {data.map((item) => (
        <div key={item.id}>{formatDate(item.date)}</div>
      ))}
    </div>
  );
};

// Better: Define utility functions outside component scope
const formatDate = (date) => {
  return new Date(date).toLocaleDateString();
};

const ImprovedComponent = ({ data }) => {
  return (
    <div>
      {data.map((item) => (
        <div key={item.id}>{formatDate(item.date)}</div>
      ))}
    </div>
  );
};

When you define functions inside a component, React recreates those functions every time the component re-renders, even if the function’s logic doesn’t depend on any state or props. This can lead to unnecessary memory allocations and could slow down performance, especially in components that re-render frequently.

Defining functions outside of components eliminates this issue, because the function is created once and remains the same across renders, which helps optimize performance by:

Reducing the number of new function instances: React no longer needs to recreate the function on every render.
Making the function reusable: By placing utility functions outside the component, they can be shared across multiple components, reducing code duplication.
Improving code readability: Keeping the component focused on rendering and separating logic into utility functions makes the component easier to read and maintain.
Easier to test: By moving logic outside of the component, the functions become easier to test in isolation, improving unit testing efficiency.

Sometimes, you may need to define a function that depends on state or props within the component. In these cases, you can use the useCallback hook to ensure that the function is not recreated unless its dependencies change. This ensures that the function reference remains stable across renders, preventing unnecessary re-renders in child components that depend on this function.

const Component = ({ itemId, onUpdate }) => {
  const handleClick = useCallback(() => {
    onUpdate(itemId);
  }, [itemId, onUpdate]);

  return <button onClick={handleClick}>Update</button>;
};

When to use useCallback:

When you pass a function down to a child component and want to avoid triggering a re-render of the child if the function hasn’t changed.
When a function depends on specific props or state and you want to ensure it’s only recreated when those specific values change.
When the function is part of a dependency array of other hooks (like useEffect), and you want to prevent unnecessary re-execution.

Handling Event Handlers Efficiently

Event handlers are another area where unnecessary re-creations can hurt performance. In React, handlers defined inline (inside JSX) are created every time the component re-renders, leading to a new reference being passed down to child components, which may cause unnecessary re-renders.

Consider this example:

// Avoid: Inline event handlers
const Component = ({ onClickHandler }) => {
  return <button onClick={() => onClickHandler("clicked")}>Click me</button>;
};

Here, the inline function is re-created on every render. A better approach is to define the handler outside of the JSX to ensure the function reference remains stable across renders:

// Better: Use a stable reference for event handlers
const Component = ({ onClickHandler }) => {
  const handleClick = useCallback(() => {
    onClickHandler("clicked");
  }, [onClickHandler]);

  return <button onClick={handleClick}>Click me</button>;
};

This ensures that handleClick maintains the same reference unless onClickHandler changes, reducing unnecessary re-renders in the child component.

Component Virtualization

Virtualization is an important technique for handling large datasets in React applications. Rather than rendering all items at once, virtualization maintains a "window" of rendered elements that dynamically updates as the user scrolls.

When implementing virtualization in React, you'll typically need to:

Track scroll position
Calculate which items should be visible
Render only those items
Position them correctly within the viewport

Virtualization can provide dramatic performance improvements for lists, tables, grids, and even carousels. For detailed implementation examples, refer to my Virtualizing React article.

Data Fetching and Caching

If you're not using React Query in your React applications yet, you probably should be. React Query provides an efficient, declarative approach to handling server state, managing data fetching, and optimizing network requests. Relying on useEffect for client-side data fetching might seem like a straightforward solution, but it's not the most effective, especially as your application grows in complexity.

While useEffect can work for simple fetches, it lacks built-in caching, automatic background refetching, and the ability to handle errors and retries seamlessly. React Query abstracts these concerns away, providing a robust, highly customizable solution that not only simplifies data fetching but also optimizes performance with features like caching, pagination, and synchronization.

By using React Query, you can drastically reduce boilerplate code, improve loading states, and focus more on building the features that matter, all while ensuring data consistency and efficiency.

Basic Implementation

Here's how to implement React Query for optimal data fetching:

import { useQuery, useMutation, useQueryClient } from "react-query";

// Fetch data with automatic caching
const UserProfile = ({ userId }) => {
  const { data, isLoading, error } = useQuery(
    ["user", userId],
    () => fetchUserById(userId),
    {
      staleTime: 5 * 60 * 1000, // Data considered fresh for 5 minutes
      cacheTime: 30 * 60 * 1000, // Cache retained for 30 minutes
      refetchOnWindowFocus: false, // Don't refetch when tab regains focus
    },
  );

  if (isLoading) return <Spinner />;
  if (error) return <ErrorMessage error={error} />;

  return <UserProfileContent user={data} />;
};

Advanced Caching Strategies

React Query enables sophisticated caching patterns:

// Optimistic updates
const TodoList = () => {
  const queryClient = useQueryClient();
  const { data: todos } = useQuery("todos", fetchTodos);

  const mutation = useMutation((newTodo) => createTodo(newTodo), {
    // Optimistically update the UI
    onMutate: async (newTodo) => {
      // Cancel any outgoing refetches
      await queryClient.cancelQueries("todos");

      // Snapshot the previous value
      const previousTodos = queryClient.getQueryData("todos");

      // Optimistically update to the new value
      queryClient.setQueryData("todos", (old) => [
        ...old,
        { ...newTodo, id: Date.now() },
      ]);

      // Return a context with the previous value
      return { previousTodos };
    },
    // If the mutation fails, use the context we returned above
    onError: (err, newTodo, context) => {
      queryClient.setQueryData("todos", context.previousTodos);
    },
    // Always refetch after error or success
    onSettled: () => {
      queryClient.invalidateQueries("todos");
    },
  });

  return (
    <div>
      <TodoForm onSubmit={(todo) => mutation.mutate(todo)} />
      <TodoItems items={todos} />
    </div>
  );
};

The benefits of this approach include:

Instant UI updates for better user experience
Automatic background refetching to ensure data consistency
Graceful error handling with automatic rollback
Reduced server load by minimizing unnecessary requests

Prefetching and Background Updates

React Query allows prefetching data before it's needed:

const App = () => {
  const queryClient = useQueryClient();

  // Prefetch user data when the app loads
  useEffect(() => {
    queryClient.prefetchQuery(["user", "current"], fetchCurrentUser);
  }, [queryClient]);

  return (
    <Router>
      <Routes>
        <Route path="/" element={<Home />} />
        <Route
          path="/profile"
          element={<Profile />}
          onMouseEnter={() => {
            // Prefetch when user hovers over link
            queryClient.prefetchQuery(["userSettings"], fetchUserSettings);
          }}
        />
      </Routes>
    </Router>
  );
};

Prefetching strategies can dramatically improve perceived performance by loading data before the user explicitly requests it. This works especially well for:

Navigation paths that users are likely to follow
Data that's frequently accessed across different parts of the application
Resources that are slow to load but critical for functionality

By strategically prefetching and caching data, you can create applications that feel instantaneous to users while minimizing server load and network traffic.

Debouncing and Throttling

Controlling high-frequency events is essential for smooth user experiences. Debouncing and throttling are two techniques that can significantly improve performance when dealing with rapidly firing events.

Debouncing

Debouncing ensures that a function is not invoked until a certain amount of time has passed since the last call, which is particularly useful in scenarios like search inputs, where you want to wait until the user stops typing before making an API call. Here's how you can implement debouncing with a 300ms delay:

import { useState, useCallback } from "react";
import { debounce } from "lodash";

const SearchComponent = () => {
  const [searchTerm, setSearchTerm] = useState("");
  const [results, setResults] = useState([]);

  const debouncedSearch = useCallback(
    debounce(async (term) => {
      const response = await fetchSearchResults(term);
      setResults(response.data);
    }, 300),
    [],
  );

  const handleChange = (e) => {
    setSearchTerm(e.target.value);
    debouncedSearch(e.target.value);
  };

  return (
    <div>
      <input
        type="text"
        value={searchTerm}
        onChange={handleChange}
        placeholder="Search..."
      />
      <SearchResults results={results} />
    </div>
  );
};

In this implementation, we use debounce to ensure the search function is only called 300ms after the user stops typing. If the user types quickly, the previous calls are canceled, and only the last call is executed, preventing unnecessary API requests.

Debouncing is particularly useful for:

Search inputs, where you want to wait until the user stops typing before sending requests.
Form validation that should not be triggered on every keystroke.
Handling resize events or any other event that could fire repeatedly within a short period.

Throttling

Throttling ensures that a function executes at a fixed interval, regardless of how often it's triggered. This is particularly useful for events that fire frequently, such as mouse movements, scrolling, or window resizing. By limiting the execution rate of a function, throttling helps reduce unnecessary calculations or re-renders, improving performance.

For example, when tracking the mouse position on mousemove, the event fires many times per second. By using throttling, we ensure that the function runs only once every 200 milliseconds, preventing excessive updates while still providing near-real-time feedback.

import { useState, useRef, useCallback } from "react";
import { throttle } from "lodash";

const MouseTracker = () => {
  const [mousePosition, setMousePosition] = useState({ x: 0, y: 0 });
  const containerRef = useRef(null);

  const handleMouseMove = useCallback(
    throttle((event) => {
      setMousePosition({ x: event.clientX, y: event.clientY });
    }, 200),
    [],
  );

  return (
    <div
      ref={containerRef}
      className="mouse-tracker"
      onMouseMove={handleMouseMove}
      style={{ height: "100vh", border: "1px solid black" }}
    >
      <p>
        Mouse Position: X: {mousePosition.x}, Y: {mousePosition.y}
      </p>
    </div>
  );
};

Throttling is ideal for:

Scroll events that trigger animations or calculations
Mousemove events for drag-and-drop or hover effects
Window resize handlers that update layouts
Tracking user activity at regular intervals

Suspense for Data Fetching

React Suspense provides a powerful way to handle asynchronous data fetching while improving perceived performance and user experience. Instead of manually tracking loading states, Suspense allows you to declaratively define fallbacks for your components.

When paired with a data-fetching library like React Query, Suspense makes handling asynchronous operations cleaner and more efficient.

import { Suspense } from "react";
import { useQuery } from "@tanstack/react-query";

const fetchUser = async () => {
  const res = await fetch("/api/user");
  return res.json();
};

const UserProfile = () => {
  const { data } = useQuery({ queryKey: ["user"], queryFn: fetchUser });

  return <div>User: {data.name}</div>;
};

const App = () => (
  <Suspense fallback={<div>Loading user...</div>}>
    <UserProfile />
  </Suspense>
);

React Suspense simplifies state management by removing the need to manually track loading states. It enhances the loading experience by displaying a fallback UI while data is being fetched, preventing flickering and layout shifts caused by conditional rendering. Additionally, it helps improve perceived performance by ensuring that components load seamlessly without jarring transitions.

Beyond performance, Suspense also improves code organization by keeping components focused on rendering logic rather than handling async states. This makes applications easier to maintain and scale. It is particularly useful when dealing with large datasets, streaming data, or preloading resources for a smoother user experience. As React continues to evolve, Suspense is set to become an essential tool for managing asynchronous operations efficiently.

Conclusion

Optimizing React applications requires a multi-faceted approach, addressing everything from data structures to rendering strategies. The techniques covered in this guide provide a comprehensive toolkit for improving your application's performance:

Smart Data Manipulation: Choose the right data structures and operation order to minimize processing time.
Strategic Rendering: Create component boundaries and preserve references to prevent unnecessary re-renders.
Advanced Memoization: Use React's optimization hooks strategically to avoid redundant calculations.
Function and Event Optimization: Define functions efficiently and use event delegation to reduce overhead.
Component Virtualization: Render only what's visible to handle large datasets efficiently.
Data Fetching and Caching: Implement effective caching strategies with React Query to minimize network requests.
Debouncing and Throttling: Control high-frequency events to maintain smooth user experiences.
Suspense for Data Fetching: Use React's Suspense API to manage asynchronous data loading seamlessly.

By applying these techniques selectively and measuring their impact, you can create React applications that remain responsive even as they grow in complexity. Remember that performance optimization is an iterative process—always measure before and after your changes to ensure they're having the desired effect.

Virtualizing React

Renan Leonel — Wed, 05 Mar 2025 02:50:43 +0000

Rendering large lists efficiently in React can be challenging. When dealing with hundreds or thousands of items, the browser's performance can suffer significantly. This guide explores two powerful approaches to solve this problem through virtualization: a pure implementation built from scratch and a solution using TanStack Virtual. By the end, you'll understand not only how virtualization works under the hood but also when to choose each approach for your specific needs.

We'll explore:

Understanding Virtualization: What virtualization is and why it's important
Pure Implementation: Step-by-step guide to implement virtualization from scratch
TanStack Virtual Implementation: Using a battle-tested library for virtualization
Comparing Approaches: When to use each approach

Understanding Virtualization

Virtualization is a technique that renders only the visible portion of a large list of items. Instead of rendering all items at once, it maintains a "window" of visible elements that moves as the user scrolls, significantly reducing the number of DOM elements present at any given time.

To understand how virtualization works, let's break down its four key components using a simple analogy:

Virtual Window

Imagine reading a 500-page book through a small window that shows only 20 pages at once
Just like you can only see these 20 pages, the DOM only renders the visible items
As you slide the window up or down the book, new pages come into view while others hide
In our select component, instead of rendering all 500 items, we show only what fits in view

Buffer Zones

Like keeping your thumb a few pages ahead and behind where you're reading
We keep 10 extra items rendered above and 10 below the visible area
This preparation ensures smooth transitions, just like having your thumb ready to flip the page
Example: While 20 items are visible, we actually render 40 (20 visible + 20 buffer)

Height Calculation

Similar to keeping the book's full thickness even though you're only viewing a small section
We maintain the full scroll height (500 items × 32px) using an invisible element
This preserves the natural feel of scrolling through a long list
Example: A 16,000px tall container represents our full 500-item list

Position Management
- Like numbering each page and knowing exactly where to slide the window
- Each item's position is precisely calculated based on its index
- If you're at item #100, we position it at exactly 3,200px from the top
- This creates the illusion of a complete list while managing only a few elements

This approach offers several key benefits:

Memory Efficiency: Instead of managing thousands of DOM nodes, the browser only needs to handle a few dozen
CPU Performance: Less DOM manipulation means reduced CPU usage during scrolling
Smooth Scrolling: With fewer elements to process, the browser can maintain 60fps even during rapid scrolling
Initial Load Speed: Applications load faster since they don't need to create all DOM nodes upfront
Battery Life: Reduced processing requirements lead to better battery life on mobile devices

Understanding these mechanics is crucial for implementing virtualization effectively, whether you're building it from scratch or using a library like TanStack Virtual.

Let's look at a practical comparison of resource usage between virtualized and non-virtualized lists. In this example, our virtualized implementation maintains a window of approximately 60 visible nodes at any time, regardless of the total list size:

List Size	Non-virtualized DOM Nodes	Virtualized DOM Nodes	Memory Usage Reduction
1,000	~1,000	~60	~94%
10,000	~10,000	~60	~99.4%
100,000	~100,000	~60	~99.94%

Pure Implementation

Let's start with implementing virtualization from scratch. This approach gives us complete control over the implementation and helps understand the core concepts.

First, we'll define our constants:

const ITEM_HEIGHT = 32; // Height of each item in pixels
const BUFFER_ITEMS = 20; // Number of items to render above/below viewport
const TOTAL_ITEMS = 500; // Total number of items in the list
const VIEWPORT_HEIGHT = 300; // Height of the visible area

The core logic involves three main parts:

Scroll Position Tracking: Monitor the scroll position to determine which items should be visible
Visible Items Calculation: Calculate the start and end indices of visible items
Rendering: Position the visible items correctly within the viewport

Here's the implementation:

export const Pure = () => {
  const [scrollTop, setScrollTop] = useState(0);
  const containerRef = useRef<HTMLDivElement>(null);

  // Calculate which items should be visible
  const startIndex = Math.max(
    0,
    Math.floor(scrollTop / ITEM_HEIGHT) - BUFFER_ITEMS
  );

  const endIndex = Math.min(
    ALL_ITEMS.length,
    Math.ceil((scrollTop + VIEWPORT_HEIGHT) / ITEM_HEIGHT) + BUFFER_ITEMS
  );

  const visibleItems = ALL_ITEMS.slice(startIndex, endIndex);

  return (
    <Select>
      <SelectContent>
        <div
          ref={containerRef}
          onScroll={handleScroll}
          style={{ height: VIEWPORT_HEIGHT }}
          className='relative overflow-auto'
        >
          {/* Total height placeholder */}
          <div
            className='absolute top-0 left-0 w-full'
            style={{ height: ALL_ITEMS.length * ITEM_HEIGHT }}
          />

          {/* Rendered items */}
          <div
            className='absolute right-0 left-0'
            style={{ top: startIndex * ITEM_HEIGHT }}
          >
            {visibleItems.map((item) => (
              <SelectItem key={item.value} value={item.value}>
                {item.label}
              </SelectItem>
            ))}
          </div>
        </div>
      </SelectContent>
    </Select>
  );
};

Let's break down the implementation to understand how each piece works together:

Container Setup

<div
  ref={containerRef}
  onScroll={handleScroll}
  style={{ height: VIEWPORT_HEIGHT }}
  className='relative overflow-auto'
>

This is our viewport container. It has a fixed height (VIEWPORT_HEIGHT = 300px) and enables scrolling. Think of it as the "window" through which we view our items.

Total Height Placeholder

<div
  className='absolute top-0 left-0 w-full'
  style={{ height: ALL_ITEMS.length * ITEM_HEIGHT }}
/>

This invisible div maintains the total scrollable height. For example, with 1,000 items at 32px each, it creates a 32,000px tall scrollable area. This ensures the scrollbar behaves naturally, as if all items were actually rendered.

Visible Items Container

<div
  className='absolute right-0 left-0'
  style={{ top: startIndex * ITEM_HEIGHT }}
>
  {visibleItems.map((item) => (
    <SelectItem key={item.value} value={item.value}>
      {item.label}
    </SelectItem>
  ))}
</div>

This container holds only the currently visible items. Its position is dynamically calculated based on scroll position:

If you're scrolled to item #50, startIndex = 50
The container is positioned at top: 50 * 32px = 1600px
Only items 50-70 (plus buffer) are actually rendered

Scroll Position Tracking

const startIndex = Math.max(
  0,
  Math.floor(scrollTop / ITEM_HEIGHT) - BUFFER_ITEMS,
);

const endIndex = Math.min(
  ALL_ITEMS.length,
  Math.ceil((scrollTop + VIEWPORT_HEIGHT) / ITEM_HEIGHT) + BUFFER_ITEMS,
);

This calculation determines which items should be rendered:

scrollTop tells us how far we've scrolled
We divide by ITEM_HEIGHT to get the first visible item
We add BUFFER_ITEMS (20) above and below for smooth scrolling
Math.max and Math.min ensure we stay within list bounds

The magic happens when scrolling:

User scrolls → scrollTop changes
New startIndex and endIndex are calculated
visibleItems array updates with new slice of items
Visible items container repositions using top style
Only ~60 items exist in DOM at any time (20 visible + 40 buffer)

This creates the illusion of scrolling through thousands of items while maintaining excellent performance.

TanStack Virtual Implementation

TanStack Virtual provides a more abstracted approach with additional features and optimizations out of the box. Here's how to implement the same functionality:

export const TanStack = () => {
  const parentRef = useRef<HTMLDivElement>(null);

  const virtualizer = useVirtualizer({
    count: TOTAL_ITEMS,
    getScrollElement: () => parentRef.current,
    estimateSize: () => ITEM_HEIGHT,
    overscan: BUFFER_ITEMS,
  });

  return (
    <Select>
      <SelectContent>
        <div
          ref={parentRef}
          className='relative overflow-auto'
          style={{ height: VIEWPORT_HEIGHT }}
        >
          <div
            className='relative w-full'
            style={{ height: `${virtualizer.getTotalSize()}px` }}
          >
            {virtualizer.getVirtualItems().map((virtualItem) => {
              const item = ALL_ITEMS[virtualItem.index];

              return (
                <SelectItem
                  key={item.value}
                  value={item.value}
                  className='absolute left-0 w-full'
                  style={{
                    height: `${ITEM_HEIGHT}px`,
                    transform: `translateY(${virtualItem.start}px)`,
                  }}
                >
                  {item.label}
                </SelectItem>
              );
            })}
          </div>
        </div>
      </SelectContent>
    </Select>
  );
};

Comparing Approaches

Now that we've explored both implementations, let's analyze their strengths and use cases. While both solutions effectively handle virtualization, they serve different needs and come with distinct trade-offs. Understanding these differences will help you choose the right approach for your specific requirements.

Pure Implementation

When to Use:
- Learning virtualization concepts
- Simple lists with fixed-height items
- Projects where bundle size is critical
- Need for minimal dependencies
Key Benefits:
- Full control over implementation
- Zero external dependencies
- Smaller bundle size
- Great for understanding core concepts

TanStack Virtual

When to Use:
- Production applications
- Complex virtualization needs
- Dynamic height items
- Need for advanced features
Key Benefits:
- Production-ready with edge case handling
- Dynamic size support
- Built-in optimizations
- TypeScript support
- Active maintenance

Decision Matrix

Feature Need	Pure	TanStack
Learning/Educational	✅	❌
Simple Fixed Lists	✅	✅
Dynamic Heights	❌	✅
Production-Ready	⚠️	✅
Bundle Size Priority	✅	❌
Advanced Features	❌	✅

Try It Yourself!

To fully appreciate the impact of virtualization, I encourage you to clone the demo repository and experiment with different list sizes. Try setting TOTAL_ITEMS to values like 1,000, 2,000, and even 10,000. Open your browser's DevTools (F12) and inspect the DOM elements for both implementations:

In the non-virtualized version, you'll see thousands of <SelectItem> elements being rendered at once, causing significant performance issues and potential browser freezing when the select is opened.
In contrast, both virtualized implementations (Pure and TanStack) maintain only about 60 DOM elements at any time (visible items + buffer), regardless of the total list size. You can verify this by inspecting the DOM as you scroll - elements are dynamically added and removed to maintain optimal performance.

This hands-on comparison clearly demonstrates why virtualization is crucial for handling large datasets in web applications.

Conclusion

Virtualization significantly improves application performance by rendering only what users see. We explored two ways to achieve this:

A pure implementation that gives you complete control and understanding of the virtualization process
TanStack Virtual that provides a production-ready solution with advanced features out of the box

Both approaches effectively solve the same problem: handling large lists efficiently. Choose the one that best fits your needs—whether it's learning the concepts, having full control, or quickly implementing a robust solution.

Resources

Dockerizing Next.js

Renan Leonel — Sat, 20 Apr 2024 20:35:27 +0000

This tutorial will cover the step-by-step process of containerizing a Next.js application using Docker. We will follow these steps:

Installing Necessary Tools: For this tutorial, we will need WSL, Docker, Docker Compose, and a Next.js project.
Dockerfile: We will create two Dockerfiles, one for development environment and the other for production environment.
Docker Compose: We will create a Docker Compose file to manage Docker containers.
Publishing to Docker Hub: We will publish the image to Docker Hub to make it available for others to use.
Docker Cheat Sheet: A list of useful commands for managing Docker containers.

You can find the source code for this tutorial on GitHub

Installing Necessary Tools

This tutorial assumes that you're using Windows as your operating system. If you're using a different operating system, the commands may vary.

Firstly, we need to install WSL (Windows Subsystem for Linux), which is a feature of Windows that allows you to run a Linux environment directly on your Windows computer without the need for a virtual machine. To do this, open PowerShell as an administrator and execute the following command:

wsl --install

If you encounter any issues during installation, you can refer to the official tutorial for WSL installation provided by Microsoft.

Now, we can proceed to install Docker and Docker Compose.

Docker is a virtualization platform that encapsulates applications in isolated containers, providing consistency and efficiency in development. This allows the application to run autonomously and consistently in any environment, eliminating conflicts between different software versions.

For installation, follow the comprehensive tutorials created by Digital Ocean for Docker and Docker Compose on Ubuntu.

Finally, create a Next.js application using the command: npx create-next-app@latest or use an existing project. For this tutorial, we will use this template repository that I use for all my projects, using pnpm as the package manager.

Dockerfile

The Dockerfile is a configuration file that contains all the necessary commands to build an image. For this tutorial, we will create two files: one for the development environment and another for the production environment.

First, create a Dockerfile.prod file in the root directory of your project. Then, add the following code:

FROM node:20 AS base
WORKDIR /app
RUN npm i -g pnpm
COPY package.json pnpm-lock.yaml ./

RUN pnpm install

COPY . .
RUN pnpm build

FROM node:20-alpine3.19 as release
WORKDIR /app
RUN npm i -g pnpm

COPY --from=base /app/node_modules ./node_modules
COPY --from=base /app/package.json ./package.json
COPY --from=base /app/.next ./.next

EXPOSE 3000

CMD ["pnpm", "start"]

Now, let's analyze the commands in the Dockerfile.prod file:

# Define the base image as node:20 and name it as base.
FROM node:20 AS base

# Set the working directory inside the container to /app.
# We need to set the working directory so Docker knows where to run the commands.
WORKDIR /app

# Globally install the package manager pnpm.
RUN npm i -g pnpm

# Copy the package.json and pnpm-lock.yaml files to the working directory in the container.
# This command is necessary for Docker to install project dependencies.
COPY package.json pnpm-lock.yaml ./

# Install project dependencies using pnpm.
RUN pnpm install

# Copy all files from the context directory (where the Dockerfile is located) to the working directory in the container.
COPY . .

# Run the project build command using pnpm.
RUN pnpm build

# Define a second stage of the image based on node:20-alpine3.19 and name it as release.
# Alpine image is a lighter version of node, which helps reduce the final image size.
FROM node:20-alpine3.19 as release

# Set the working directory inside the container to /app.
WORKDIR /app

# Globally install the package manager pnpm.
RUN npm i -g pnpm

# Copy the node_modules folder from the base stage to the node_modules directory in the release stage.
COPY --from=base /app/node_modules ./node_modules

# Copy the package.json file from the base stage to the current directory in the release stage.
COPY --from=base /app/package.json ./package.json

# Copy the .next folder from the base stage to the .next directory in the release stage.
COPY --from=base /app/.next ./.next


# Define the default command to be executed when the container is started with pnpm start.
CMD ["pnpm", "start"]

Next, create a Dockerfile.dev file in the root of your project.

FROM node:20 AS base
WORKDIR /app
RUN npm i -g pnpm
COPY package.json pnpm-lock.yaml ./

RUN pnpm install

COPY . .

FROM node:20-alpine3.19 as release
WORKDIR /app
RUN npm i -g pnpm

COPY --from=base /app/node_modules ./node_modules
COPY --from=base /app/package.json ./package.json
COPY --from=base /app/.next ./.next
COPY --from=base /app/src ./src
COPY --from=base /app .

EXPOSE 3000

CMD ["pnpm", "dev"]

We can test if the Dockerfile is working correctly by building our application using the command:

docker build -t nextjs:v1 -f Dockerfile.prod .

To execute, use the command:

docker run -p 3000:3000 nextjs:v1

It's worth highlighting the meaning of the flags used:

-t: This flag is used to tag an image.
-f: This flag specifies the Dockerfile to use for building an image.
-p: This flag maps ports between the Docker container and the host system.

Upon accessing http://localhost:3000, you should see the Next.js application running inside a Docker container. You can also verify if the container is running correctly by executing the command:

docker ps

If everything is working correctly, you should see something like this:

CONTAINER ID   IMAGE        COMMAND                  CREATED         STATUS         PORTS                                       NAMES
88c1975e087b   nextjs:v1   "docker-entrypoint.s…"   7 seconds ago   Up 6 seconds   0.0.0.0:3000->3000/tcp, :::3000->3000/tcp   festive_leavitt

However, hot reload isn't working when using the Dockerfile.dev because the container is not watching for changes in the files.

Furthermore, manually executing these commands every time we want to run the application is a tedious process. To address these issues, let's use Docker Compose.

Docker Compose

Docker Compose is a tool that simplifies the management of multiple Docker containers, allowing you to define and run them all with a single command, simplifying the configuration and management of multi-container applications.

Additionally, we have access to the concept of volumes, which allow data persistence between containers and the host, ensuring that data is not lost when containers are restarted or removed and allowing changes in files to be reflected in the container in real-time. Furthermore, Docker Compose allows the definition of environment variables in a .env file to facilitate the configuration of the application.

To use Docker Compose, we need to create a configuration file called docker-compose.yml. This file defines the services that will be run by Docker Compose, as well as the configurations for each service.

version: "3.7"

services:
  dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    container_name: demo-docker-nextjs-dev
    environment:
      - WATCHPACK_POLLING=true
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    ports:
      - "3000:3000"
    env_file:
      - .env.local
  prod:
    build:
      context: .
      dockerfile: Dockerfile.prod
    container_name: demo-docker-nextjs
    ports:
      - "3000:3000"
    env_file:
      - .env.local

volumes:
  node_modules:

Let's analyze the commands in the docker-compose.yml file:

# Define the version of Docker Compose.
version: "3.7"

# Define the services to be run by Docker Compose.
services:
  # Define the dev service.
  # This service will be used to run the application in the development environment.
  dev:
    # Define the build context as the current directory and the Dockerfile to be used as Dockerfile.dev.
    build:
      context: .
      dockerfile: Dockerfile.dev
    # Define the container name.
    container_name: demo-docker-nextjs-dev
    # Define the environment variable WATCHPACK_POLLING as true. This is necessary for hot reload to work correctly.
    environment:
      - WATCHPACK_POLLING=true
    # Define the volumes to be mounted in the container.
    # The volume .:/app maps the current working directory to the /app directory in the container.
    # The volume /app/node_modules is used to persist project dependencies between containers.
    # The volume /app/.next is used to persist files generated by Next.js between containers.
    volumes:
      - .:/app
      - /app/node_modules
      - /app/.next
    # Maps the ports to be exposed on the host.
    ports:
      - "3000:3000"
    # Define the environment file to be used.
    env_file:
      - .env.local
  # Define the prod service.
  # This service will be used to run the application in the production environment.
  prod:
    # Define the build context as the current directory and the Dockerfile to be used as Dockerfile.prod.
    build:
      context: .
      dockerfile: Dockerfile.prod
    # Define the container name.
    container_name: demo-docker-nextjs
    # Maps the ports to be exposed on the host.
    ports:
      - "3000:3000"
    # Define the environment file to be used.
    env_file:
      - .env.local

# Define the volumes to be used.
# The node_modules volume is used to persist project dependencies between containers.
volumes:
  node_modules:

To run the application using Docker Compose, execute the command:

docker-compose up prod

Or, in development mode:

docker-compose up dev

Now, upon accessing http://localhost:3000, you should see the Next.js application running inside a Docker container with hot reload functioning in the development environment. Try making a change to any file and observe the changes being reflected in the container in real-time.

Publishing to Docker Hub

Finally, we can upload our application to Docker Hub so that other people can use the image we created. To do this, follow the steps below:

docker login

Build the image using the command:

docker build -t <DOCKERHUB_USERNAME>/<REPOSITORY>:<TAG> -f <DOCKERFILE> .

In my case, the command would be:

docker build -t renanleonel/demo-docker-nextjs-prod:v1 -f Dockerfile.prod .

Push the image to Docker Hub using the command:

docker push <DOCKERHUB_USERNAME>/<REPOSITORY>:<TAG>

We can view the image through the link on Docker Hub. To run the image in any environment that supports Docker, we should download the image using the command:

docker push renanleonel/demo-docker-nextjs-prod:v1

and then run the container:

docker run -p 3000:3000 renanleonel/demo-docker-nextjs-prod:v1

Now your Next.js application is containerized and ready to be used in any environment that supports Docker.

Docker Cheat Sheet

Here are some useful commands for managing Docker containers:

View all running containers

docker ps

View all containers, including stopped ones

docker ps -a

To stop a container, execute the command

docker stop <CONTAINER ID>

Stop all running Docker containers

docker stop $(docker ps -a -q)

To remove a container, execute the command

docker rm <CONTAINER ID>

Remove all Docker containers

docker rm $(docker ps -a -q)

Remove all stopped Docker containers

docker container prune

To view the images on your system, execute the command

docker image ls

To remove an image, execute the command

docker image rm <REPOSITORY>:<TAG>

If the image is being used by a container, you must stop and remove the container before removing the image. Another way is to add the -f flag to force removal.

docker image rm -f <REPOSITORY>:<TAG>

To remove all images, execute the command

docker rmi $(docker images -q)

Next.js 14 authentication

Renan Leonel — Tue, 05 Mar 2024 21:13:53 +0000

This is a brief tutorial of how to create an authentication flow in Next.js 14 using NextAuth v5 using the middleware file. These are the steps we are going to follow:

Creating the project: Creating a new Next.js project with NextAuth v5.
Setting up NextAuth: Configuring NextAuth to use the credentials provider.
Protecting routes: Creating a middleware file to protect routes.

Creating the project

First, we need to create a new Next.js project. We can do that by running the following command:

npx create-next-app@latest

After that, we need to install NextAuth v5:

pnpm add next-auth@beta

If you face any issues with the installation, you can check the official documentation for Next.js and NextAuth.

Setting up NextAuth

Next, we need to create a new file called app/api/auth/[...nextauth]/route.ts and add the following code:

export { GET, POST } from "@/auth";

Inside src folder, create a file called auth.ts, where we are going to create a mock function to simulate the access to the database. This is the function that will be called whenever the signIn method from NextAuth is called.

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

async function getUser(email: string, password: string): Promise<any> {
  return {
    id: 1,
    name: "test user",
    email: email,
    password: password,
  };
}

export const {
  auth,
  signIn,
  signOut,
  handlers: { GET, POST },
} = NextAuth({
  ...authConfig,
  providers: [
    Credentials({
      name: "credentials",
      credentials: {
        email: { label: "email", type: "text" },
        password: { label: "password", type: "password" },
      },
      async authorize(credentials) {
        const user = await getUser(
          credentials.email as string,
          credentials.password as string,
        );

        return user ?? null;
      },
    }),
  ],
});

Also, create a file called auth.config.ts and add the following code:

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

export const authConfig = {
  session: {
    strategy: "jwt",
  },
  pages: {
    error: "/",
    signIn: "/",
    signOut: "/",
  },
  callbacks: {
    authorized({ auth }) {
      const isAuthenticated = !!auth?.user;

      return isAuthenticated;
    },
  },
  providers: [],
} satisfies NextAuthConfig;

Now, we need to define the routes of our application. We are going to create two pages, the root page where all users can access, and the /protected page, where only logged users can access.

First, create a file in src/lib/routes.ts. This constants will be used in the middleware verification.

export const ROOT = "/";
export const PUBLIC_ROUTES = ["/"];
export const DEFAULT_REDIRECT = "/protected";

Then, create the two pages, with a Form component

import Form from "@/components/form";

const Root = () => {
  return (
    <main className="flex items-center justify-center h-screen w-screen">
      <Form />
    </main>
  );
};

export default Root;

import { auth } from "@/auth";
import { logout } from "@/lib/actions";
import { Button } from "@/components/ui/button";

const Protected = async () => {
  const session = await auth();

  session?.user?.email;

  return (
    <form
      action={logout}
      className="h-screen w-screen flex flex-col justify-center items-center gap-10"
    >
      <div>
        <p className="text-white">{session?.user?.name}</p>
        <p className="text-white">{session?.user?.email}</p>
      </div>
      <Button type="submit" className="w-40" variant="secondary">
        logout
      </Button>
    </form>
  );
};

export default Protected;

"use client";

import { login } from "@/lib/actions";
import { useFormState } from "react-dom";
import { Input } from "@/components/ui/input";
import { Button } from "@/components/ui/button";

const loginInitialState = {
  message: "",
  errors: {
    email: "",
    password: "",
    credentials: "",
    unknown: "",
  },
};

const Form = () => {
  const [formState, formAction] = useFormState(login, loginInitialState);

  return (
    <form action={formAction} className="space-y-4 w-full max-w-sm">
      <Input required name="email" placeholder="email" />
      <Input required name="password" type="password" placeholder="password" />
      <Button variant="secondary" className="w-full" type="submit">
        submit
      </Button>
    </form>
  );
};

export default Form;

We are using zod to validate the our form with the following schema:

import { z } from "zod";

export const loginSchema = z.object({
  email: z
    .string()
    .trim()
    .min(1, { message: "Email required!" })
    .email({ message: "Invalid email!" }),
  password: z
    .string()
    .trim()
    .min(1, { message: "Password required!" })
    .min(8, { message: "Password must have at least 8 characters!" }),
});

Now, we need to create a file called actions.ts in src/lib folder. This file will contain the server action that will be used in the form.

"use server";

import { AuthError } from "next-auth";
import { signIn, signOut } from "@/auth";
import { loginSchema } from "@/types/schema";

const defaultValues = {
  email: "",
  password: "",
};

export async function login(prevState: any, formData: FormData) {
  try {
    const email = formData.get("email");
    const password = formData.get("password");

    const validatedFields = loginSchema.safeParse({
      email: email,
      password: password,
    });

    if (!validatedFields.success) {
      return {
        message: "validation error",
        errors: validatedFields.error.flatten().fieldErrors,
      };
    }

    await signIn("credentials", formData);

    return {
      message: "success",
      errors: {},
    };
  } catch (error) {
    if (error instanceof AuthError) {
      switch (error.type) {
        case "CredentialsSignin":
          return {
            message: "credentials error",
            errors: {
              ...defaultValues,
              credentials: "incorrect email or password",
            },
          };
        default:
          return {
            message: "unknown error",
            errors: {
              ...defaultValues,
              unknown: "unknown error",
            },
          };
      }
    }
    throw error;
  }
}

export async function logout() {
  await signOut();
}

Protecting routes

Finally, we need to create a middleware file to protect the routes. Create a file called middleware.ts in src/lib folder and add the following code:

import NextAuth from "next-auth";
import { authConfig } from "@/auth.config";
import { DEFAULT_REDIRECT, PUBLIC_ROUTES, ROOT } from "@/lib/routes";

const { auth } = NextAuth(authConfig);

export default auth((req) => {
  const { nextUrl } = req;

  const isAuthenticated = !!req.auth;
  const isPublicRoute = PUBLIC_ROUTES.includes(nextUrl.pathname);

  if (isPublicRoute && isAuthenticated)
    return Response.redirect(new URL(DEFAULT_REDIRECT, nextUrl));

  if (!isAuthenticated && !isPublicRoute)
    return Response.redirect(new URL(ROOT, nextUrl));
});

export const config = {
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};

Here, we are retrieving if the user is authenticated for every route in our application and verifying the current path. If the user has a current session and tried to go back to the login page, they will be redirected back to the /protected page. If the user tries to access any route that isn’t public without a session, they will be redirected to the login page. You can use any matcher suitable for your application.

Now, you have a complete authentication flow using middleware in Next.js 14 with NextAuth v5! If you face any problems, you can check the GitHub repository with the full code to help you out.

How to Customize SVGs using Next.js and Tailwind CSS

Renan Leonel — Wed, 18 Oct 2023 21:40:35 +0000

This article aims to demonstrate how to customize SVG images using Next.js and Tailwind, without the need for external configurations or the use of auxiliary libraries like svgr/webpack.

For this tutorial, we're using the following image: https://www.flaticon.com/free-icon-font/checkbox_3917076?related_id=3917076

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" id="Capa_1" x="0px" y="0px" viewBox="0 0 512 512" style="enable-background:new 0 0 512 512;" xml:space="preserve" width="512" height="512">
  <g>
    <path d="M405.333,0H106.667C47.786,0.071,0.071,47.786,0,106.667v298.667C0.071,464.214,47.786,511.93,106.667,512h298.667   C464.214,511.93,511.93,464.214,512,405.333V106.667C511.93,47.786,464.214,0.071,405.333,0z M426.667,172.352L229.248,369.771   c-16.659,16.666-43.674,16.671-60.34,0.012c-0.004-0.004-0.008-0.008-0.012-0.012l-83.563-83.541   c-8.348-8.348-8.348-21.882,0-30.229s21.882-8.348,30.229,0l83.541,83.541l197.44-197.419c8.348-8.318,21.858-8.294,30.176,0.053   C435.038,150.524,435.014,164.034,426.667,172.352z" />
  </g>
</svg>

The default behavior of Next.js with the <Image> tag does not allow changing the fill property of the SVG. This becomes an issue when we need to change the color of an SVG image during mouse hover, for example, using Tailwind CSS classes like fill-white or bg-white. This approach doesn't work because we're not directly changing the fill property of the <svg>, and as of the writing of this article (Next 13.5.4), the <Image/> tag doesn't support changes to the fill of SVGs.

import Image from 'next/image';

import checkbox from '../../public/icons/checkbox.svg';

const Home = () => {
  return (
    <main className='h-screen bg-zinc-800 flex items-center justify-center'>
      <Image
        src={checkbox}
        alt='checkbox'
        className='w-20 h-20 fill-white'
      />
    </main>
  );
}

export default Home;

To solve this issue, we need to create a component for the SVG, removing style properties from the SVG tag, such as width, height, and primarily fill. These properties will be passed to the SVG through the className property of the component. Here's how to do it:

import { twMerge } from 'tailwind-merge';

interface CheckboxProps {
  className?: string;
}

const Checkbox = ({ className }: CheckboxProps) => {
  return (
    <svg
      xmlns='http://www.w3.org/2000/svg'
      version='1.1'
      id='Capa_1'
      x='0px'
      y='0px'
      viewBox='0 0 512 512'
      width='512'
      height='512'
      className={twMerge('w-20 h-20', className)}
    >
      <g>
        <path d='M405.333,0H106.667C47.786,0.071,0.071,47.786,0,106.667v298.667C0.071,464.214,47.786,511.93,106.667,512h298.667   C464.214,511.93,511.93,464.214,512,405.333V106.667C511.93,47.786,464.214,0.071,405.333,0z M426.667,172.352L229.248,369.771   c-16.659,16.666-43.674,16.671-60.34,0.012c-0.004-0.004-0.008-0.008-0.012-0.012l-83.563-83.541   c-8.348-8.348-8.348-21.882,0-30.229s21.882-8.348,30.229,0l83.541,83.541l197.44-197.419c8.348-8.318,21.858-8.294,30.176,0.053   C435.038,150.524,435.014,164.034,426.667,172.352z' />
      </g>
    </svg>
  );
};

export default Checkbox;

Finally, our page.tsx file will look like this:

import Image from 'next/image';
import Checkbox from '@/components/svg/Checkbox';
import checkbox from '../../public/icons/checkbox.svg';

const Home = () => {
  return (
    <main className='h-screen bg-zinc-800 flex items-center justify-center gap-6'>
      <Image
        src={checkbox}
        alt='checkbox'
        className='w-20 h-20 fill-white'
      />
      <Checkbox className='fill-white hover:fill-red-600' />
    </main>
  );
};

export default Home;

Now, we can customize our SVG according to external application states and user actions, such as hover. It's a simple solution, but not very intuitive, as Next.js' <Image/> tag doesn't handle this kind of scenario effectively.

Como realizar o deploy de uma aplicação Next.js com Next Auth na Heroku

Renan Leonel — Sun, 01 Oct 2023 17:15:58 +0000

Este é um breve tutorial de como realizar o deploy no serviço cloud Heroku de uma aplicação Next.js utilizando Next Auth como método de autenticação de usuários. A versão do Next.js utilizada é a versão 13.5.1, versão mais recente até a data de publicação do artigo.

1) Primeiros passos

Primeiramente, devemos ter um projeto Next.js publicado no Github, assim como uma conta na Heroku. Ao entrar na sua conta, você irá se deparar com a opção de criar um novo aplicativo:

Insira o nome do seu projeto e a região em que seu aplicativo será hospedado. No meu caso optei por hospedar nos Estados Unidos, mas selecione a opção que melhor se encaixa nos seus requisitos.

2) Conectando com o Github

Após isso, devemos conectar a conta do Github em que o projeto se encontra.

Após conectar com o Github, selecione o repositório que deseja fazer o deploy e selecione o botão Connect. Nesta parte também é possível habilitar o deploy automático toda vez que houver alterações na branch principal (main).

3) Definir Variáveis de Ambiente

Agora, vamos para a parte mais importante deste tutorial, a definição das variáveis de ambiente. Vá nas configurações do projeto:

Na seção “Config Vars”, pressione o botão “Reveal Config Vars”.

No projeto Next.js, estou usando como exemplo as variáveis de ambiente do Next Auth da seguinte forma:

NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=123

Adicione as variáveis de ambiente na Heroku da seguinte forma:

A variável de ambiente NEXTAUTH_URL apontando para o localhost será apenas provisória enquanto não realizamos o primeiro deploy. Após o deploy, será necessário alterar o valor para o link gerado pela Heroku.

Em seguida, salve as variáveis de ambiente e realize seu primeiro deploy manual:

Este processo pode demorar um pouco, então aguarde o deploy ser realizado. Ao finalizar, clique no botão “View” para ser redirecionado para a URL do seu projeto. Parabéns, você realizou seu primeiro deploy de um projeto Next.js na Heroku! Porém, para que a autenticação funcione corretamente, devemos alterar o valor da variável de ambiente que apontava para o localhost, apontando-a agora para a sua URL da Heroku.

4) Atualizar a Variável de Ambiente para a URL da Heroku

Copie a URL do seu projeto, vá para “Settings”, na seção “Config Vars” pressione o botão “Reveal Config Vars”. Altere a variável NEXTAUTH_URL com a URL do seu projeto Heroku. Por fim, realize outro deploy manual, e seu projeto deve funcionar corretamente.

Considerações Finais

Parabéns, você realizou seu deploy com Next Auth! Caso tenha habilitado os deploys automáticos, qualquer alteração na branch main do seu projeto realizará o deploy automático para produção, portanto tenha cuidado! Caso esteja utilizando outros serviços e/ou bibliotecas que necessitem de variáveis de ambiente, não se esqueça de adicioná-las no projeto na Heroku, caso contrário as integrações podem não funcionar como esperado.

Obrigado por ler até aqui!

DEV Community: Renan Leonel

Building a Scalable i18n System in React

Table of Contents

Core Concepts and Setup

Automatic Configuration

Breaking Down the Configuration

Translation Organization and Usage

Extending Your i18n System

Final Thoughts

Mastering React Performance

Smart Data Manipulation

Array Operations Order

Maps vs. Arrays for Lookups

Single-Pass Data Transformation

Strategic Rendering

Component Boundaries

Reference Preservation

Advanced Memoization

Strategic useMemo Usage

Function and Event Optimization

Defining Functions Outside Components

Handling Event Handlers Efficiently

Component Virtualization

Data Fetching and Caching

Basic Implementation

Advanced Caching Strategies

Prefetching and Background Updates

Debouncing and Throttling

Debouncing

Throttling

Suspense for Data Fetching

Conclusion

Virtualizing React

Understanding Virtualization

Pure Implementation

TanStack Virtual Implementation

Comparing Approaches

Pure Implementation

TanStack Virtual

Decision Matrix

Try It Yourself!

Conclusion

Resources

Dockerizing Next.js

Installing Necessary Tools

Dockerfile

Docker Compose

Publishing to Docker Hub

Docker Cheat Sheet

Next.js 14 authentication

Creating the project

Setting up NextAuth

Protecting routes

How to Customize SVGs using Next.js and Tailwind CSS

Como realizar o deploy de uma aplicação Next.js com Next Auth na Heroku

1) Primeiros passos

2) Conectando com o Github

3) Definir Variáveis de Ambiente

4) Atualizar a Variável de Ambiente para a URL da Heroku

Considerações Finais