With the release of v0.3.x-(athar), the library has undergone a massive architectural shift to prioritize speed, scalability, and developer experience. If you are currently using v0.1.5 (or v0.2.x), you will notice significant breaking changes designed to make your application much faster.

In this article, we will break down what's new in version 0.3.x-(athar) and provide a comprehensive, step-by-step guide on how to migrate your codebase from v0.1.5 to v0.3.x-(athar).

What is quran-search-engine?

For those new to the library, quran-search-engine is a deterministic, client/server-side search engine for the Quran. Unlike traditional solutions that tie you to a specific UI or require a dedicated backend server, this library runs anywhere JavaScript runs (vanilla JavaScript, React, Vue, React Native, Node.js ... etc).

It features:

• Advanced Linguistic Search*: Lemma and root matching.
• Semantic Search*: Concept-based mapping (e.g., searching for English concepts to find Arabic verses).
• Boolean Operators*: AND(+), OR(|), NOT(-), and grouped queries.
• Regex Search*: Pattern-based queries with built-in ReDoS safety validation.
• Range Queries*: Verse-coordinate lookups like 2:255 or 1:1-7.
• Phonetic Search (Pronunciation)*: Latin-to-Arabic transliteration for non-Arabic queries (e.g., searching "Alhamdulillah" to find "الحمد لله").
• Cross-Language Search*: English-to-Arabic search out of the box, which can be easily extended or replaced with other languages (e.g., French, Urdu).
• Fuzzy Search*: Fallback matching for misspelled words.
• UI-Agnostic Highlighting*: Returns precise match offsets (HighlightRanges) instead of raw HTML, pushing the display responsibility to your framework (React, Next.js, React Native, Terminals, etc.).
• Stateless Architecture*: You control the data loading, caching, and state management.

The New Layered Search Architecture

To ensure the engine remains highly performant, maintainable, and extensible, the search logic has been refactored into a Layered Search Pipeline. The orchestrator (search()) routes each query through a strict priority cascade, where each layer is an isolated, independently testable module located in core/layers/:

1. Range Layer: Verse-coordinate queries (2:255) short-circuit all linguistic processing.
2. Boolean Layer: Parses complex logic (AND, OR, NOT, ()) into an AST.
3. Regex Layer: Executes pattern queries in isolation (skipping linguistic layers).
4. Simple Layer: Exact token matching in normalized Arabic text.
5. Linguistic Layer: Lemma and root matching via morphology data.
6. Fuse Layer: Fuzzy fallback matching (Fuse.js) for unmatched tokens.
7. Semantic Layer: Concept expansion and cross-language mappings.
8. Phonetic Layer: Latin→Arabic transliteration processing.

This modular structure means that managing, adding, or updating new search features is now as simple as inserting a new isolated layer into the pipeline without breaking existing functionality or risking monolithic complexity.

## What’s New in Version 0.3.x(athar)?

The jump from v0.1.5 to v0.3.x-(athar) brings game-changing performance optimizations. Here are the major highlights:

### 1. Architectural Shift: Arrays to Maps for O(1) Performance

In previous versions, the Quran data was stored and searched as an Array (QuranText[]). As queries grew more complex, array iterations became a bottleneck. In v0.3.x, data structures have been migrated to Maps (Map<number, QuranText>). This shift enables O(1) access time, drastically reducing the latency of verse lookups and filtering.

### 2. The Context Object Pattern

The search() function signature has been revamped. Instead of passing an endless list of positional arguments, v0.3.x-(athar) introduces a clean Search Context object. This makes your code more readable and future-proof.

### 3. Mandatory Inverted Index

To achieve lightning-fast lookups for morphological and semantic searches, v0.3.x-(athar) introduces a mandatory Inverted Index. Instead of computing search paths on the fly, you now build an inverted index once during initialization (buildInvertedIndex) and pass it into the search context.

### 4. Enhanced Web Worker Support & Error Handling

Moving search operations off the main thread is crucial for a smooth UI. Version 0.3.x-(athar) simplifies worker initialization and introduces the WorkerError class. This provides structured, type-safe error codes when dealing with web workers.

### 5. Deprecations and Cleanups

To keep the library lightweight and focused, several legacy features and data files from previous versions have been removed:

• Pre-built Index Files*: Static JSON files (e.g., lemma-index.json, root-index.json, word-index.json) are no longer distributed. Instead, these indices are now built dynamically in-memory via buildInvertedIndex(), reducing bundle size and ensuring data consistency.

Data Modularity

One of the most powerful aspects of quran-search-engine is how it handles data ingestion. The library does not force heavy data files into your bundle; instead, it empowers you with dynamic loading and strict validation.

1. Dynamic Data Loading

All core datasets—including the Quran text, morphology maps, semantic words, and phonetic transliterations—can be dynamically loaded from the package on demand. This ensures your initial application bundle size remains incredibly small. You only load the datasets (like English semantic data or Latin transliteration data) when the user actually requests those features.

2. "Bring Your Own Language"

You are not locked into our default English semantic indices. The engine allows you to easily load another language by replacing the default English semantic map with your own (e.g., French, Urdu, or Turkish mappings). This gives you complete flexibility to build multi-lingual Quran applications without being bound to English as the only bridge for semantic search.

3. Custom Data Validation

Beyond just semantics, you can also inject custom datasets. The library exposes robust data validation functions to ensure your custom payloads are correctly structured.

As long as your custom dataset passes the engine's rigorous validation schema, the library guarantees the search engine won't crash when running advanced queries on them.

Highly Typed (TypeScript First)

The library is written entirely in TypeScript and is strictly typed from the ground up. Every data model, search context, configuration object, and search response (like HighlightRanges) is backed by explicit interfaces.

This robust typing provides:

• Excellent IDE autocomplete: Discover available search options and response fields seamlessly.
• Runtime safety: Prevents errors during data hydration by enforcing strict contracts on custom datasets.
• Absolute confidence: Know exactly what properties exist on a verse or search result when manipulating them in your UI.

Production Ready & Heavily Tested

quran-search-engine is not just an experimental library; it is heavily tested in production environments. It powers the search infrastructure behind Open Mushaf Native, a modern, fully-featured offline Quran application built with React Native and Expo. The library handles complex morphological queries seamlessly on mobile devices without relying on any backend API.

Included Playground & Examples

To help you get started quickly, the repository ships with a comprehensive playground featuring multiple real-world integration examples. These examples demonstrate how to architect stateless searching across different frameworks:

• Vanilla TypeScript (examples/vanilla-ts): Pure browser implementation without any VDOM overhead.
• React + Vite (examples/vite-react): A feature-rich web app showcasing a full search UI with highlighted components.
• Node.js (examples/nodejs): Bare-metal server-side searching via CLI.
• Angular (examples/angular): Dedicated Angular component highlighting implementation.

You can easily spin up these examples locally using the provided yarn scripts (e.g., yarn playground:react or yarn playground:node).

Offline & AI-Friendly Documentation

We understand that modern development workflows often involve AI pair programmers. That is why quran-search-engine ships with a comprehensive docs/ folder directly inside the package.

This offline documentation is split into practical Guides and deep-dive References covering everything from search syntax to the core API. Whether you are reading it locally in your IDE or providing it as context to an AI agent (like GitHub Copilot or Trae), the markdown files are structured to be easily digestible and highly accessible without needing an internet connection.

Powered by the ITQAN Community

The architectural leap in version 0.3.x-(athar) was heavily inspired and shaped by the brilliant developers in the ITQAN Community.

Their participation in the Athar Initiative (a collaborative effort to build advanced, open-source Quranic technologies) directly influenced the strict typings, the dynamic data loading approach, and the robust layered search architecture you see today. The name of this release, athar (meaning "impact" or "trace"), is dedicated to their ongoing contributions to the Quran technology ecosystem.

You can read more about the initial ideas and discussions that led to this release in the official Athar Initiative article on the ITQAN Community Forum.

Step-by-Step Migration Guide: From v0.1.5 to v0.3.x-(athar)

Because v0.3.x introduces breaking changes, your v0.1.5 code will not work out of the box. Follow these steps to migrate your application safely.

Step 1: Update Your State Definitions

Since quranData is now a Map, and you need to store the new Inverted Index and Semantic Map, update your state hooks (if using React).

• Before (v0.1.5):*

const [quranData, setQuranData] = useState<QuranText[]>([]);

• After (v0.3.x):*

import { InvertedIndex, QuranText } from 'quran-search-engine';

const [quranData, setQuranData] = useState<Map<number, QuranText> | null>(null);

const [invertedIndex, setInvertedIndex] = useState<InvertedIndex | null>(null);

const [semanticMap, setSemanticMap] = useState<Map<string, string[]> | null>(null);

const [phoneticMap, setPhoneticMap] = useState<Map<string, string[]> | null>(null);

Step 2: Load Data and Build the Inverted Index

You must now load the semantic data and explicitly build the inverted index before allowing users to search.

• Before (v0.1.5):*

const [data, morphology, dictionary] = await Promise.all([

loadQuranData(),

loadMorphology(),

loadWordMap(),

]);

• After (v0.3.x-(athar)):*

import { loadQuranData, loadMorphology, loadWordMap, loadSemanticData, loadPhoneticData, buildInvertedIndex } from 'quran-search-engine';

const [data, morphology, dictionary, semantic, phonetic] = await Promise.all([

loadQuranData(),

loadMorphology(),

loadWordMap(),

loadSemanticData(), // New requirement for v0.3.x

loadPhoneticData(), // New requirement for phonetic search

]);

setQuranData(data);

setMorphologyMap(morphology);

setWordMap(dictionary);

setSemanticMap(semantic);

setPhoneticMap(phonetic);

// Build the inverted index synchronously

const index = buildInvertedIndex(morphology, data, semantic);

setInvertedIndex(index);

Step 3: Refactor the Search Function Call

The search() function no longer accepts quranData, morphologyMap, and wordMap as separate positional arguments. They must be grouped into a context object alongside the invertedIndex.

• Before (v0.1.5):*

const response = search(

query,

quranData,

morphologyMap,

wordMap,

options,

{ page: 1, limit: 10 },

undefined,

searchCache

);

• After (v0.3.x-(athar)):*

const response = search(
  query,
  {
    quranData,
    morphologyMap,
    wordMap,
    invertedIndex,
    semanticMap, // Used for semantic search (cross-language)
    transliterationMap, // Used for phonetic search (pronunciation)
  },
  {
    ...options,
    isRegex: false, // New regex layer option
    isBoolean: false, // New boolean parsing option
    phonetic: false, // New phonetic matching option
  },
  { page: 1, limit: 10 },
  undefined,
  searchCache
);

Step 4: Update Web Worker Initialization (If Applicable)

If you were offloading search to a Web Worker, the initialization path has been simplified using Vite/Webpack dynamic URL imports.

• Before (v0.1.5):*

const client = createSearchWorker({

workerUrl: new URL('quran-search-engine/worker', import.meta.url),

});

await client.initData();

• After (v0.3.x):*

// Dynamically import the worker URL

const mod = await import('quran-search-engine/worker?url');

const client = createSearchWorker({ workerUrl: mod.default });

await client.initData();

You can now also gracefully catch worker errors:

import { WorkerError } from 'quran-search-engine';

try {

await client.runSearch(query, options, pagination);

} catch (error) {

if (error instanceof WorkerError) {

console.error(`Worker failed with code: ${error.code}`);

}

}

Complete Before & After Comparison

To see the big picture, here is how a standard React component initialization looks before and after the migration.

❌ The Old Way (v0.1.5)

useEffect(() => {

async function init() {

const [data, morphology, dictionary] = await Promise.all([

loadQuranData(),

loadMorphology(),

loadWordMap(),

]);

setQuranData(data);

setMorphologyMap(morphology);

setWordMap(dictionary);

}

init();

}, []);

// Later in the search handler...

search(query, quranData, morphologyMap, wordMap, options, pagination);

✅ The New Way (v0.3.x-(athar))

useEffect(() => {

async function init() {

const [data, morphology, dictionary, semantic, phonetic] = await Promise.all([

loadQuranData(),

loadMorphology(),

loadWordMap(),

loadSemanticData(),

loadPhoneticData(),

]);

setQuranData(data);

setMorphologyMap(morphology);

setWordMap(dictionary);

setSemanticMap(semantic);

setPhoneticMap(phonetic);

// Build the inverted index once

const index = buildInvertedIndex(morphology, data, semantic);

setInvertedIndex(index);

}

init();

}, []);

// Later in the search handler...

search(query, { quranData, morphologyMap, wordMap, invertedIndex, semanticMap, phoneticMap }, options, pagination);

Conclusion

The release of v0.3.x marks a maturity milestone for the quran-search-engine. By shifting from Arrays to Maps and enforcing an Inverted Index, the library now guarantees O(1) access times, allowing for instant, complex searches across the entire Quran text without freezing the main thread.

While migrating from v0.1.5 requires adjusting your data loading logic and function signatures, the performance gains are well worth the effort.

Ready to upgrade? Run yarn add quran-search-engine@latest today! If you encounter any issues during your migration, feel free to check out the official repository and open an issue. Happy coding!

I was tired of paying for multiple AI subscriptions just to handle different writing tasks. So I built Lubb Writer — an open-source tool that gives you 13 different text enhancement modes through a single interface.

Home page: https://lubb-writer.adelpro.us.kg/

The Problem

Most AI writing tools are:

• Expensive ($20-50/month)

• Single-provider (you're locked in)

• Desktop-only or require copy-pasting

I wanted something that:

• Works with any AI provider

• Integrates into my browser

• Costs nothing if I already have API keys

• Can be self-hosted

The Solution

Lubb Writer — a full-stack project with:

lubb-writer/
├── api/           # Express + TypeScript REST API
├── extension/     # Plasmo framework (Chrome, Firefox, Edge)
└── docker-compose.yml

Key Technical Features

Multi-Provider Abstraction

// provider-adapter.ts (simplified)
interface AIProvider {
  enhance(text: string, mode: WritingMode): Promise<EnhancedText>;
}

class ProviderFactory {
  static create(provider: ProviderType): AIProvider {
    switch (provider) {
      case 'openai': return new OpenAIAdapter();
      case 'anthropic': return new ClaudeAdapter();
      case 'gemini': return new GeminiAdapter();
      case 'custom': return new CustomAdapter();
    }
  }
}

Each adapter handles:

• API authentication

• Request/response transformation

• Error handling

• Token counting

Browser Extension with Plasmo

Plasmo makes cross-browser extensions painless:

// popup.tsx
function Popup() {
  const [text, setText] = useState('');
  
  return (
    <div className="w-80 p-4">
      <textarea 
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder="Enter text to enhance..."
      />
      <ModeSelector onSelect={handleMode} />
      <EnhanceButton onClick={() => enhance(text)} />
    </div>
  );
}

One-Command Deployment

# Deploy the API
git clone https://github.com/YOUR_USERNAME/lubb-writer.git
cd lubb-writer/api
cp .env.example .env
# Add your API keys
docker compose up -d

# Install the extension
# Chrome: Load from build/chrome directory
# Firefox: Load from build/firefox directory

13 Writing Modes

What I Learned

1. Provider abstraction is 60% of the work — each AI has different quirks

2. Keyboard shortcuts > click paths — Ctrl+Shift+Y is much faster than navigating menus

3. Docker is non-negotiable for easy self-hosting

4. Plasmo > vanilla extension APIs — cross-browser support without the headache

Try It

GitHub: https://github.com/adelpro/lubb-writer

Clone it, run it, break it, improve it. PRs welcome!

What's Next?

• [ ] Streaming responses for longer texts

• [ ] Team collaboration features

• [ ] API key management dashboard

• [ ] More writing modes

What features would you want to see? Drop a comment!

Progressive Web Apps (PWAs) combine the reach of the web with the capabilities of native applications.

They load instantly, work offline, send notifications, and can be installed on any device — all using standard web technologies: HTML, CSS, and JavaScript.

In 2025, PWAs are no longer an experiment. They are deployed in production by global brands such as Twitter, Starbucks, Uber, and Pinterest.

They solve the complexity of maintaining multiple native apps while offering near-native performance and usability.

2. Definition and Browser Support

A Progressive Web App (PWA) is a web application that:

• Uses a Web App Manifest for metadata.

• Registers a Service Worker for caching, offline, and background tasks.

• Served over HTTPS.

• Is installable and behaves like a native app.

Browser support (2025):

Browser Support Level Notes Chromium (Chrome, Edge, Brave) Full Install prompt, push, background sync Firefox Partial No native installation prompt Safari (iOS / macOS) Partial → improving Offline & push supported since iOS 16.4

3. Real-World Adoption

According to PWA Stats:

Company Impact Key Metric Twitter Lite Lightweight version +65% pages/session Starbucks Works offline 2× faster checkout Uber Web <50 KB core bundle Loads in <3 s on 2G Pinterest Rebuilt as a PWA +60% engagement Trivago Offline-ready hotel search +150% engagement time

Insight: PWAs deliver app-store quality performance without app-store friction.

4. Core Building Blocks

4.1 Web App Manifest

The Web App Manifest is a JSON file that defines your app’s metadata and tells the browser how to install and display it.

It connects your web experience to native-like behavior — title, icons, splash screens, colors, and launch parameters.

Example:

{
  "name": "PWA App",
  "short_name": "PWA",
  "id": "com.app.pwa",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#1a1a1a",
  "icons": [
    { "src": "/images/favicon/icon-192.png", "sizes": "192x192", "type": "image/png" },
    { "src": "/images/favicon/icon-512.png", "sizes": "512x512", "type": "image/png" }
  ],
  "screenshots": [
    { "src": "/images/screenshots/mobile.png", "sizes": "1080x1920" },
    { "src": "/images/screenshots/desktop.png", "sizes": "1920x1080" }
  ],
  "shortcuts": [
    { "name": "About", "url": "/about" },
    { "name": "Contact", "url": "/contact" }
  ]
}

Manifest Field Overview

• name — Full app name shown in the install interface. Example: "App PWA"

• short_name — Label displayed on the home screen or dock. Example: "App"

• id — Unique identifier used for store packaging. Example: "com.quran.pwa"

• start_url — URL the app loads when opened. Example: "/"

• scope — Navigation boundary defining what the PWA controls. Example: "/"

• display — Display mode such as fullscreen, standalone, minimal-ui, or browser. Example: "standalone"

• orientation — Locks the screen orientation on launch. Example: "portrait"

• background_color — Background color shown on the splash screen. Example: "#ffffff"

• theme_color — Browser UI theme color. Example: "#1a1a1a"

• description — Short text shown in install dialogs. Example: "Offline-ready Quran reader"

• lang — Application language code. Example: "ar"

• dir — Text direction (ltr or rtl). Example: "rtl"

• icons — App icons in multiple sizes (required: 192×192 and 512×512). Example: "/icons/512x512.png"

• screenshots — Images shown in install banners (Android). Example: "/images/screenshot-1.png"

• shortcuts — Quick access actions from long press or context menu. Example: "About"

• categories — Used for app store classification. Example: "education"

Minimum Installable Manifest

To qualify as installable across modern browsers, your manifest must include:

• name

• short_name

• icons (must include 192×192 and 512×512 PNGs)

• start_url

• display

• theme_color

• Served over HTTPS

Additional fields like id, shortcuts, and screenshots enhance install banners and store packaging (e.g., with PWA Builder)

4.2 Service Worker

A Service Worker is a background script that sits between your web app and the network.

It intercepts requests, caches assets, and enables offline behavior, background sync, and push notifications — all without user interaction.

Core Concepts

Feature Description Typical Use Lifecycle Independent thread with install → activate → fetch phases Controls app updates Caching Stores static and dynamic assets using the Cache API Offline access, faster reloads Intercepting Fetch Handles every network request Choose when to serve cache or fetch fresh Offline Fallback Returns a predefined HTML when the user is offline fallback.html or custom error UI Background Sync / Push Queues updates or sends notifications when reconnected Messaging, analytics, reminders

Lifecycle Events

1. Install Event – Pre-caches essential assets (app shell).

2. Activate Event – Cleans old caches and takes control of open tabs.

3. Fetch Event – Intercepts requests and applies a caching strategy.

4. Message / Sync Events – Used for background tasks or two-way communication.

Registration in Your App

Register the Service Worker once from your main script:

if ('serviceWorker' in navigator) {
  window.addEventListener('load', () => {
    navigator.serviceWorker
      .register('/serviceWorker.js')
      .then(() => console.log('Service Worker registered'))
      .catch((error) => console.error('SW registration failed:', error));
  });
}

4.3 Cache Types, Management, and Purging

The Cache Storage API gives PWAs full control over how files, data, and network responses are stored locally.

Proper cache design determines performance, offline reliability, and update frequency.

Types of Cache in PWAs

Cache Type Description Typical Contents Lifetime Static Cache Preloaded during the install event (the “App Shell”) HTML, CSS, JS, icons Until next version release Dynamic Cache Created at runtime as users navigate API responses, images, user content Controlled manually or by quota Runtime Cache Short-lived cache for frequently updated assets Feeds, news, live data Regularly revalidated Third-Party Cache Assets fetched from CDNs or APIs Fonts, analytics scripts Managed by browser

Cache Versioning and Naming

Use versioned cache names to differentiate builds and safely purge old assets:

const STATIC_CACHE = 'quran-cache-v1';
const DYNAMIC_CACHE = 'quran-dynamic-v1';

When deploying a new version:

• Increment the cache name.

• In the activate event, delete outdated caches.

self.addEventListener('activate', (event) => {
  const allowList = [STATIC_CACHE, DYNAMIC_CACHE];
  event.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((key) => !allowList.includes(key)).map((key) => caches.delete(key)))
    )
  );
});

Cache Purging and Size Limiting

To prevent uncontrolled growth:

• Set a maximum cache size.

• Remove the oldest entries when exceeding the limit.

const limitCacheSize = async (name, size) => {
  const cache = await caches.open(name);
  const keys = await cache.keys();
  if (keys.length > size) {
    await cache.delete(keys[0]);
    await limitCacheSize(name, size);
  }
};

Combine this with runtime caching (e.g., API responses) to ensure performance without bloating storage.

Best Practices

• Precache only essentials: HTML, JS, CSS, icons, manifest.

• Separate dynamic data into its own cache.

• Purge old caches during activation to avoid conflicts.

• Use Workbox for declarative caching and automatic cleanup.

• Test offline via Chrome DevTools → Application → Service Workers → Offline.

Effective cache management balances speed, storage efficiency, and update reliability, ensuring users always receive fresh yet instantly loadable experiences.

5. Progressive Web Application — Full Example (step-by-step)

production-ready vanilla JavaScript PWA, providing offline access, caching, installability, and a graceful fallback page.

You can generate icons and screenshots for your manifest via pwabuilder.com/imageGenerator

Project structure (recommended)

/index.html
/fallback.html
/manifest.json
/serviceWorker.js
/js/app.js
/css/style.css
/images/icons/192x192.png
/images/icons/512x512.png

Everything lives at the root so the Service Worker can control all routes.

Step 1 – index.html

The main page registers the Service Worker and links the manifest.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>PWA</title>
  <link rel="manifest" href="/manifest.json" />
  <meta name="theme-color" content="#1a1a1a" />
  <link rel="icon" href="/images/icons/192x192.png" />
  <link rel="stylesheet" href="/css/style.css" />
</head>
<body>
  <h1>PWA</h1>
  <p>Offline-ready Application.</p>

  <button id="installBtn" hidden>Install App</button>

  <script src="/js/app.js" defer></script>
</body>
</html>

Explanation

• <link rel="manifest"> → enables installability.

• <meta name="theme-color"> → sets system UI color.

• The install button is hidden until beforeinstallprompt fires.

Step 3 – manifest.json

(Already detailed earlier; skip duplication)

Contains app metadata, icons 192×192 + 512×512, shortcuts, screenshots, etc.

Step 4 – fallback.html

Displayed when offline navigation fails, Keep it lightweight and self-contained so it loads instantly even when offline.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>Offline Mode</title>
  <style>
    body {
      background: #eceff1;
      font-family: Roboto, Arial, sans-serif;
      margin: 0;
    }
    #msg {
      max-width: 360px;
      margin: 100px auto;
      padding: 32px;
      background: #fff;
      border-radius: 6px;
      text-align: center;
    }
    a {
      display: block;
      margin-top: 20px;
      background: #039be5;
      color: #fff;
      text-decoration: none;
      padding: 12px;
      border-radius: 4px;
    }
  </style>
</head>
<body>
  <div id="msg">
    <h1>You’re Offline</h1>
    <p>This page can’t be displayed without an internet connection.</p>
    <a href="/index.html">Return to Home</a>
  </div>
</body>
</html>

Keep it lightweight and self-contained so it loads instantly even when offline.

Step 5 – serviceWorker.js

Handles caching and offline logic.

/* serviceWorker.js */
const STATIC_CACHE = 'quran-static-v1';
const DYNAMIC_CACHE = 'quran-dynamic-v1';
const MAX_DYNAMIC_ITEMS = 30;

const ASSETS = [
  '/',
  '/index.html',
  '/fallback.html',
  '/css/style.css',
  '/images/icons/192x192.png',
  '/images/icons/512x512.png',
  '/js/app.js'
];

async function limitCacheSize(name, max) {
  const cache = await caches.open(name);
  const keys = await cache.keys();
  if (keys.length > max) {
    await cache.delete(keys[0]);
    await limitCacheSize(name, max);
  }
}

self.addEventListener('install', (evt) => {
  evt.waitUntil(caches.open(STATIC_CACHE).then((c) => c.addAll(ASSETS)));
  self.skipWaiting();
});

self.addEventListener('activate', (evt) => {
  evt.waitUntil(
    caches.keys().then((keys) =>
      Promise.all(keys.filter((k) =>
        k !== STATIC_CACHE && k !== DYNAMIC_CACHE).map((k) => caches.delete(k))
      )
    ).then(() => self.clients.claim())
  );
});

self.addEventListener('fetch', (evt) => {
  const { request } = evt;
  if (request.method !== 'GET') return;

  if (request.mode === 'navigate') {
    evt.respondWith(
      (async () => {
        try {
          const res = await fetch(request);
          const cache = await caches.open(DYNAMIC_CACHE);
          cache.put(request, res.clone());
          return res;
        } catch {
          return caches.match('/fallback.html');
        }
      })()
    );
    return;
  }

  evt.respondWith(
    caches.match(request).then((cached) => {
      return (
        cached ||
        fetch(request)
          .then((res) => {
            return caches.open(DYNAMIC_CACHE).then((cache) => {
              if (request.url.startsWith(self.location.origin)) {
                cache.put(request, res.clone());
                limitCacheSize(DYNAMIC_CACHE, MAX_DYNAMIC_ITEMS);
              }
              return res;
            });
          })
          .catch(() => cached)
      );
    })
  );
});

Explanation

1. Install → Precache core assets.

2. Activate → Clean old versions.

3. Fetch → Cache-first for static, Network-first for navigation.

4. limitCacheSize prevents unlimited growth.

Step 6 – js/app.js

Registers the Service Worker and handles installation UI.

// js/app.js
if ('serviceWorker' in navigator) {
  window.addEventListener('load', async () => {
    try {
      const reg = await navigator.serviceWorker.register('/serviceWorker.js');
      console.log('Service Worker registered', reg);
    } catch (err) {
      console.error('SW registration failed:', err);
    }
  });
}

// Custom install prompt
window.addEventListener('beforeinstallprompt', (e) => {
  e.preventDefault();
  window.deferredPrompt = e;
  const btn = document.getElementById('installBtn');
  btn.hidden = false;
  btn.addEventListener('click', async () => {
    btn.hidden = true;
    const prompt = window.deferredPrompt;
    prompt.prompt();
    await prompt.userChoice;
    window.deferredPrompt = null;
  });
});

Explanation

• Registers /serviceWorker.js once on load.

• Listens for beforeinstallprompt and shows the custom Install App button.

Step 7 – css/style.css

Simple theme styling.

body{font-family:system-ui,Arial,sans-serif;margin:0;padding:2rem;background:#fff;color:#222}
h1{color:#1a1a1a}
button{background:#039be5;color:#fff;border:none;padding:.8rem 1.2rem;border-radius:4px;cursor:pointer}
button:hover{background:#0277bd}

Step 8 – Testing Checklist

Test Tool Expected Lighthouse → PWA Audit Chrome DevTools Score > 90 Offline mode DevTools → Network → Offline Fallback shown Install prompt Chromium Android/Desktop “Install App” visible iOS Add to Home Screen Safari Share Menu App icon added Cache inspection DevTools → Application → Cache Storage Static + dynamic entries

Step 9 – Result

You now have a fully functional Progressive Web App that:

• Works offline.

• Installs on desktop + mobile.

• Caches intelligently.

This ipfs.quran.us.kg build demonstrates how far a vanilla PWA can go without any framework or dependency.

Modern frameworks automate manifest injection, SW registration, and caching strategies.

6. Modern Frameworks in Practice

Modern frameworks make building PWAs easier by automating manifest injection, service worker setup, and offline caching.

Framework PWA Support Package Notes Next.js next-pwa Generates manifest, caches routes Expo (React Native) Built-in PWA export One codebase → iOS, Android, Web Angular @angular/pwa schematic Adds manifest, SW, and icons automatically Vite / React vite-plugin-pwa Runtime caching and auto-update SvelteKit / Nuxt 3 Native manifest + SW support File-based configuration

These frameworks hide most low-level details while maintaining flexibility for custom caching and install behavior.

7. Native Packaging and Distribution

PWAs can be wrapped as native apps for app stores using modern tooling.

Tool Platform Output Description Bubblewrap (Google) Android APK / TWA Packages PWAs as Trusted Web Activities PWA Builder (Microsoft) Windows, Android, iOS MSIX / APK / IPA GUI + CLI packaging Capacitor (Ionic) Android, iOS Native wrapper Adds native APIs + store deployment Google Unified Web (UW) Experimental Universal package Future standard bridging PWA + Play Store

Recommended Flow

1. Validate your PWA’s manifest, service worker, and installability using Lighthouse or Chrome DevTools.

2. Generate assets and installers with PWA Builder — including icons, screenshots, and store metadata.

3. Package for app stores using Bubblewrap, Capacitor, or PWA Builder to create ready-to-publish builds for Google Play, Apple App Store, and Microsoft Store.

4. Submit your packaged PWA through the appropriate store submission process for distribution across platforms.

8. Pros and Cons

Pros Cons Cross-platform single codebase Limited access to native APIs Offline-ready & installable iOS storage and background limits Auto-update via Service Worker Limited monetization channels Lower cost than native apps Discoverability mainly via web, not app stores

9. Conclusion

PWAs are mature, production-ready, and here to stay.

They empower developers to build fast, installable, secure, and cross-platform apps — using only the web stack.

With tools like PWA Builder, Bubblewrap, and Capacitor, PWAs can reach Google Play, Microsoft Store, and even iOS users.

Modern frameworks like Next.js and Expo make this integration seamless.

Start small:

Add a manifest.json, register a serviceWorker.js, and test offline.

Your next web app can be installable in under an hour.

Attribution: cover photo from athree23

The React Compiler (formerly React Forget) is an optimizing compiler that analyzes your React components and automatically memoizes computations, props, and state transitions, the same things you’ve been manually optimizing with useMemo, useCallback, and React.memo.

But here’s the kicker: you don’t have to write any of that boilerplate anymore. The compiler does it for you at build time.

The compiler uses static analysis to understand your component’s data flow, then rewrites your code to eliminate unnecessary re-renders and redundant calculations. It’s like having a senior React performance engineer silently refactoring your entire codebase while you sleep.

Why This Matters

Let’s be honest: React performance optimization has always been a manual, error-prone chore.

You’ve probably written code like this countless times:

const expensiveValue = useMemo(() => computeExpensiveThing(data), [data]);
const handleClick = useCallback(() => doSomething(id), [id]);

Yet inevitably, dependency arrays get missed. Or unnecessary ones get added. Sometimes you wrap components in React.memo when they don’t need it, or fail to wrap the ones that genuinely would benefit. These mistakes are practically unavoidable. This mental overhead is significant and decreases your productivity.

How It Works (Simplified)

The compiler doesn’t use magic. It uses math.

It builds a control-flow graph of your component, tracks how values derive from props and state, and identifies which values remain “stable” across renders. If a value hasn’t changed, the compiler ensures it’s reused, no re-computation, no re-render.

It even handles tricky cases:

• Functions passed as props? Automatically stabilized.

• Objects and arrays? Memoized if their contents haven’t changed.

• Complex hooks and context? Tracked and optimized.

And if your code is too dynamic for static analysis? The compiler gracefully falls back. Your app still works, just without the optimizations.

No breaking changes. No migration headaches.

The Developer Experience

One of the most exciting aspects is the DX improvement.

Imagine:

✓ No more dependency arrays

✓ No more “why is this re-rendering?” debugging sessions

✓ No more premature optimization debates in PRs

✓ No more useMemo/useCallback fatigue

You write code naturally, declaratively, functionally, without worrying about performance traps. The compiler handles the rest.

You should be able to write React like it’s 2015 — and still get 2024 performance.

First: Check Your App’s Health (Don’t Skip This!)

Before you install the compiler — run a compatibility check. The React Compiler only works if your components follow React’s “Rules of React”, immutability, no side effects in render, etc.

If your code violates these rules, the compiler will silently skip optimization — and you’ll have no idea why your app still re-renders like crazy.

How to Check Compatibility

Step 1: Use Health Check package from react team

First Check how compatible your project is with the React Compiler.

npx react-compiler-health-check

This will generally verify if your app is following the rules of React and will highlight any issues

Step 2: Use the Official React Compiler ESLint Plugin (Recommended)

Install the plugin:

npm install eslint-plugin-react-compiler --save-dev

Add it to your .eslintrc:

{
  "plugins": ["react-compiler"],
  "rules": {
    "react-compiler/react-compiler": "error"
  }
}

Then run:

npx eslint .

It will flag components that are unsafe for compilation — e.g.:

• Mutating refs during render

• Using eval or dynamic keys

• Breaking hook rules

• Passing unstable props via spread ({...props})

Fix these first. The compiler can’t optimize around them. You don’t need to rewrite your app, but you do need to understand what breaks the compiler’s assumptions.

Compatibility ≠ Optimization. Even “100% compatible” code may not be optimized unless you adjust patterns like useMutation, dynamic keys, or inline JSX children.

How to Try It Today (Step-by-Step)

Step 1: Install the Experimental Build

You need React 19 experimental builds. In your project:

npm install react@experimental react-dom@experimental

The compiler is opt-in and only works with the experimental channel for now.

Step 2: Enable the Compiler

If you’re using Vite + TypeScript

Install the Babel plugin:

npm install babel-plugin-react-compiler --save-dev

Then, in your babel.config.js:

module.exports = {
plugins: [
["babel-plugin-react-compiler", {
compilationMode: "infer"
}]
]
};

compilationMode: "infer" tells the compiler to auto-detect which components are safe to optimize.

If You’re Using Next.js (Recommended Setup):

Next.js includes built-in, optimized support for the React Compiler — using SWC under the hood for faster builds.

Install the babel plugin:

npm install babel-plugin-react-compiler

Then, in your next.config.js:

import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
experimental: {
reactCompiler: true,
},
}
export default nextConfig

Next.js only compiles files that actually use JSX or React Hooks — so builds stay fast.

For Expo, you need to install the babel plugin (not needed for SDK54 and above)

npx expo install babel-plugin-react-compiler@beta

Then update App.json

{
  "expo": {
    "experiments": {
      "reactCompiler": true
    }
  }
}

Then update your eslint, first install the react compiler plugin

npx expo install eslint-plugin-react-compiler -D

Then update the eslint configuration

// <https://docs.expo.dev/guides/using-eslint/>
const { defineConfig } = require('eslint/config');
const expoConfig = require('eslint-config-expo/flat');
const reactCompiler = require('eslint-plugin-react-compiler');

module.exports = defineConfig([
  expoConfig,
  reactCompiler.configs.recommended,
  {
    ignores: ['dist/*'],
  },
]);

Optional: Opt-In Mode

reactCompiler: {
compilationMode: 'annotation',
},
}

Then, in any component:

export default function MyComponent() {
"use memo"
// ... your code
}

Or to opt-out:

"use no memo"

Step 3: Write “Naive” Code — Let the Compiler Do the Work

Take a look at this component written without any useMemo or useCallback:

// Before: “Naive” version — no manual memoization
function Counter() {
const [counter, setCounter] = useState(0);
const [name, setName] = useState("Mohamed");
const handleButtonClick = () => {
setCounter(value => value + 1);
};
const welcomeMessage = Welcome, Mr. ${name}!; // This gets auto-memoized!
return (
<div>
<h1>{welcomeMessage}</h1>
<p>Counter value: {counter}</p>
<button onClick={handleButtonClick}>Increment</button>
<input
value={name}
onChange={event => setName(event.target.value)}
/>
</div>
);
}

When you edit the input (name), the welcome string and handleButtonClick function are automatically memoized by the compiler — even though you didn’t write useMemo or useCallback.

You can verify this in React DevTools → “Highlight updates when components render.” You’ll see only the necessary parts re-render.

Step 4: Check Compiler Output (Optional — for the Curious)

The compiler rewrites your code behind the scenes. You can see the output by:

1. Running your dev server

2. Opening DevTools → Sources

3. Looking for .hot-update.js or compiled component files

You’ll see generated code like:

const $ = useMemo(() => Welcome, Mr. ${name}!, [name]);
const handleButtonClick = useCallback(() => { ... }, []);

inserted automatically. You didn’t write it. The compiler did.

Gotchas & Limitations

These limitations are based on real-world testing (see: I Tried React Compiler ) and React Summit 2024 demos. Even if your app is “compatible,” the compiler may not optimize everything unless you adjust patterns like useMutation, dynamic keys, or inline JSX children.

✗ The compiler can’t optimize components that use eval, new Function, or highly dynamic patterns.

✗ Avoid useRef mutations in render — the compiler can’t track those.

✗ Spread props ({...props}) may limit optimization — prefer explicit props when possible.

✗ Libraries returning non-memoized objects from hooks (e.g., react-query’s useMutation) can break memoization. Extract .mutate or .data before passing to callbacks.

✓ Safe patterns: useState, useEffect, simple derived values, inline functions — all optimized automatically.

If the compiler can’t optimize it, it leaves your code as-is. No breakage. Just missed opportunities.

I'm Already Using It in Production

I don't wait for "stable" to test real tools.

I've implemented the React Compiler in two production apps:

1. Open Tarteel — Next.js Web App

A Quran recitation and correction platform built with Next.js App Router.

• Compiler enabled via next.config.js

• ESLint plugin running in CI

2. Open Mushaf Native — Expo (React Native) App

A mobile Quran reader.

• Compiler enabled via Babel plugin in babel.config.js

• Running on Android in internal builds and in production

• Zero crashes. Zero state bugs.

Yes, the React Compiler works in React Native. It doesn't care if you're rendering to DOM or native views. If it's JSX and hooks, it optimizes it.

Tip: In Expo, make sure you're on SDK 49+ and React 18.3+ experimental. Clear your Metro cache after enabling: npx expo start -c

This isn't a lab experiment. This is live, user-facing code.

The compiler isn't magic, but it's real. When paired with a health check and minor pattern tweaks, it delivers results.

You don't need permission to try it.

Just don't skip the audit.

Final Thoughts

The React Compiler isn’t just an incremental improvement. It’s a paradigm shift.

It takes one of React’s biggest pain points, performance optimization — and automates it. Completely.

20% faster apps. Zero extra code. Zero extra effort.

If that doesn’t get you excited, you’re not paying attention.

But, and this is critical, it’s not magic. It’s math. And math needs clean inputs.

Run the health check. Fix the gotchas. Then let the compiler fly.

Attribution: cover photo from ClickerHappy

You know that feeling? You’re scrolling through a feed, lost in the content, new content keeps appearing, No clunky “Load More” button. No jarring page refreshes. Just… more. That’s infinite scroll. And today, we’re wiring it up in React using the browser’s built-in API: the Intersection Observer API.

We’ll be pulling in real product data from dummyjson.com/products, this endpoint is perfect for testing and prototyping, and it uses limit and skip parameters for pagination. We’ll use exactly that to fetch our data in neat, manageable chunks.

You’re on Part 3 of our series on the Intersection Observer API.

Here we’ll build infinite scroll, but first, check out Parts 1 and 2 to get familiar with the API.

1. Part 1: JavaScript Intersection Observer API — Master Scroll-Triggered Animations

2. Part 2: How to Use the Intersection Observer API in React — Lazy Load Images & Components

   ---

   Let’s start by creating a reusable Hook: useInfiniteScroll.

   First, we create a custom hook. Why? Because you’ll want to reuse this magic everywhere. This hook watches an element. When that element scrolls into view, it triggers a function to fetch more data.

   Here’s the goods:

import React from "react";
type Props = { fetchData: () => void, hasMore: boolean };
export const useInfiniteScroll = ({ fetchData, hasMore }: Props) => {
 const loadMoreRef = (React.useRef < HTMLDivElement) | (null > null);
 const handleIntersection = React.useCallback(
 (entries: IntersectionObserverEntry[]) => {
 const isIntersecting = entries[0]?.isIntersecting;
 if (isIntersecting && hasMore) {
 fetchData();
 }
 },
 [fetchData, hasMore]
 );
 React.useEffect(() => {
 const observer = new IntersectionObserver(handleIntersection);
 if (loadMoreRef.current) {
 observer.observe(loadMoreRef.current);
 }
 return () => observer.disconnect();
 }, [handleIntersection]);
 return { loadMoreRef };
};

What's happening here?

• fetchData: The function that fetches your next batch of data (like our products from dummyjson.com).

• hasMore: A simple boolean flag. Are there more items to load from the server? If not, we stop fetching.

• loadMoreRef: This is our sentinel element. We attach it to the bottom of our list. When this element becomes visible in the viewport, our Intersection Observer triggers the "Fetch more!" action.

• The useEffect creates the IntersectionObserver when the component mounts and cleans it up when it unmounts, keeping everything tidy.

  ---

  Implementing the Product card and the Products List

  Let’s start by creating the Product type:

    export type ProductType = {
     id: number,
     thumbnail: string,
     title: string,
     price: number,
    };
  

  Then create a reusable component Product Card, to display each item (product) we pull from the API:

import React from "react";
import type { ProductType } from "../types";

type ProductCardProps = Pick<ProductType, "thumbnail" | "title" | "price">;

export default function ProductCard({
 thumbnail,
 title,
 price,
}: ProductCardProps) {
 return (
 <div className="product-card">
 <img
 src={thumbnail}
 alt={title}
 loading="lazy"
 className="product-card__image"
 />
 <h3 className="product-card__title" itemProp="name">
 {title}
 </h3>
 <p
 className="product-card__price"
 itemProp="offers"
 itemScope
 itemType="https://schema.org/Offer"
 >
 <strong itemProp="priceCurrency" content="USD">
 $
 </strong>
 <strong itemProp="price">{price.toFixed(2)}</strong>
 </p>
 </div>
 );
}

For the CSS, add these CSS to styles.css file in the route of our project

.product-card {  height: 350px;  padding: 20px;  background-color: #f8f9fa;  border-radius: 8px;  border: 2px solid #a29a9c;  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);  display: flex;  flex-direction: column;  align-items: center;  justify-content: space-between;}
.product-card__image {  width: 100%;  height: 200px;  object-fit: cover;  border-radius: 4px;  margin-bottom: 10px;}
.product-card__title {  margin: 10px 0;  font-size: 1rem;  text-align: center;}
.product-card__price {  margin: 0;  font-size: 1.2rem;  color: #e91e63;}

Now, let's put our hook to work. We'll build a Products component that fetches items from the dummyjson.com/products

API and renders them in a list. Each product is rendered in a card with a title, thumbnail, price, and reviews, perfect for a rich, engaging feed.

import React from "react";
import { ProductType } from "../types";
import { useInfiniteScroll } from "../hooks/use-infinite-scroll";
import ProductCard from "./product-card";
import LoadMoreElement from "./load-more-element";
import { delay } from "../types/utils/delay";

const ITEMS_PER_PAGE = 6;

export default function Products() {
 const [products, setProducts] = React.useState<ProductType[]>([]);
 const [hasMore, setHasMore] = React.useState<boolean>(true);
 const [page, setPage] = React.useState<number>(0);

 const fetchProducts = React.useCallback(async () => {
 const response = await fetch(
 `https://dummyjson.com/products?limit=${ITEMS_PER_PAGE}&skip=${
 page * ITEMS_PER_PAGE
 }`
 );
 const data = await response.json();

 await delay(2000); //delay for 2sec

 // Slowdown timer

 if (data.products.length === 0) {
 setHasMore(false);
 } else {
 setProducts((prevProducts) => [...prevProducts, ...data.products]);
 setPage((prevPage) => prevPage + 1);
 }
 }, [page]);

 // Plug in our custom hook.
 const { loadMoreRef } = useInfiniteScroll(fetchProducts, hasMore);

 return (
 <>
 <div className="products">
 {products.map((product: ProductType) => (
 <ProductCard
 key={product.id}
 thumbnail={product.thumbnail}
 title={product.title}
 price={product.price}
 />
 ))}
 </div>
 {/* This is our sentinel. The hook watches this div. */}
 {hasMore && <LoadMoreElement loadMoreRef={loadMoreRef} />}
 </>
 );
}

Update the styles.css, add these CSS

.products {  margin: 20px;  display: grid;  gap: 20px;  grid-template-columns: repeat(auto-fill, minmax(250px, 1fr));}

Breaking it down:

• We manage three essential state variables: the products array to store our items, the hasMore flag to track if additional data exists, and the current page for pagination.

• The fetchProducts function handles our data retrieval. It calculates the skip parameter (page * ITEMS_PER_PAGE) for the API request, pulling the next set of products from dummyjson.com. When it receives an empty array, it sets hasMore to false to stop further requests.

• We feed fetchProducts and hasMore into our custom useInfiniteScroll hook.

• The hook returns loadMoreRef, which we attach to a small <div> at the bottom of our product list. When this sentinel element becomes visible as the user scrolls down, it automatically triggers fetchProducts—creating that seamless infinite scroll experience.

• We have added a slowdown function: delay() just to slow down the loading process, so we can see the load more element in action, you can disable it.

Implementing the Load-more component

Now let’s create a dedicated, reusable component to handle our loading state. This isn’t just a blank <div> anymore, it’s a visual signal to the user that magic is happening.

Create a new file: components/Load-more-element.tsx

import React from "react";

type Props = {
 loadMoreRef: React.MutableRefObject<HTMLDivElement | null>;
};

export default function LoadMoreElement({ loadMoreRef }: Props) {
 return (
 <div className="load-more__container">
 <div ref={loadMoreRef} className="load-more">
 <span>Loading more</span>
 <div className="load-more__dots">
 <span />
 <span />
 <span />
 </div>
 </div>
 </div>
 );
}

Add some CSS to our styles.css file

/* Load more styles */.load-more {  display: flex;  flex-direction: row;  gap: 10px;  align-items: center;  justify-content: center;  padding: 16px;  margin: 10px auto;  width: 180px;  background: #e0e0e0;  color: #555;  border-radius: 6px;  cursor: default;  font-weight: normal;  transition: none;}
.load-more:hover {  background: #e0e0e0;  transform: none;}
.load-more__dots {  display: flex;  justify-content: center;  margin-top: 8px;  gap: 5px;}
.load-more__dots span {  width: 5px;  height: 5px;  background: #999;  border-radius: 50%;  display: inline-block;  animation: bounce 1s infinite;}
.load-more__dots span:nth-child(2) {  animation-delay: 0.2s;}
.load-more__dots span:nth-child(3) {  animation-delay: 0.4s;}
@keyframes bounce {  0%,  80%,  100% {    transform: translateY(0);  }  40% {    transform: translateY(-6px);  }}

Live Demo & Source Code

Live demo: https://dn6nv4-5173.csb.app/

Source code: https://github.com/adelpro/products-infinite-scroll

Conclusion: Infinite Scroll, the Native Way

And that’s it—you’ve just built a fully working infinite scroll in React using nothing but the browser’s built-in Intersection Observer API. No heavy libraries, no hacks, just smooth, native performance.

This technique isn’t just for product feeds. You can apply it to:

• Blog posts: load article previews endlessly, keeping readers engaged.

• Social feeds: keep the timeline alive without page reloads.

• Image galleries: stream in photos as users scroll.

• Dashboards: fetch logs, analytics, or messages chunk by chunk.

• E-commerce: show products, reviews, or search results without friction.

Next time you’re tempted to reach for another dependency, remember: the browser already has your back. Keep scrolling, keep it smooth.

Cover image credit: Marten Bjork

Expo’s DOM Components, introduced around SDK 52, let you embed web React components directly in your mobile app by simply adding the use dom directive at the top of your file. It’s like running a mini-web app inside your native UI—no rewrite required.

Why this matters

• One codebase for web + mobile: Share components across platforms, cut maintenance, enforce consistency.

• Fast prototyping & incremental migration: Wrap your web app in Expo, ship quickly, then gradually swap in native bits where it matters.

Example: Embedding a Rich Text Editor using Expo DOM Components

'use dom';
import React from 'react';

export default function Welcome() {
 return (
 <div style={{ padding: 20, textAlign: 'center' }}>
 <h1>Welcome to the App!</h1>
 <p>We’re glad to have you here.</p>
 </div>
 );
}

Drop this into your Expo app, and it runs just like on the web—inside your mobile shell.

Expo DOM Components (since SDK 52) let you plug in your web UI into mobile apps with minimal friction. Think “web within native”—ship faster, stay unified, and improve incrementally.

Why it matters:

• Multiple CPU cores? Fast SSD? You’ll see big gains.

• Early tests show 1.3x–3x faster linting, especially on large projects with hundreds or thousands of files.

How to

Update your eslint package in your package.json to v9.34.0 to take advantage of multithread linting.

Then, update your scripts:

"scripts": {
 "lint": "eslint --fix --cache --concurrency=auto"
}

If you’re using lint-staged for pre-commit linting, configure it like this:

"lint-staged": {
 "*.{js,jsx,ts,tsx}": [

 "prettier --write",

 "eslint --fix --cache --concurrency=auto"

 ],

 "*.{json,md,css}": "prettier --write"

}

This will dramatically speed up linting on large projects by running multiple files in parallel. Perfect for faster pre-commit hooks and CI pipelines!

Loading a gallery of large, high-resolution images can cripple your React application's performance, leading to slow initial load times, a poor Largest Contentful Paint (LCP) score, and a frustrating user experience. The solution isn't to reduce image quality, but to be smarter about when you load them.

In our previous article , we explored the fundamentals of the Intersection Observer API in vanilla JavaScript, learning how it provides a performant, asynchronous way to detect when elements enter the viewport—without the jank of traditional scroll listeners.

Now, we're going to apply that powerful native browser API directly within a React and Next.js application. We'll build a real-world example: a heavy image gallery that uses the Intersection Observer to implement lazy loading and infinite scroll from the ground up, using only React's core hooks (useRef, useEffect, useState) and no third-party libraries.

By the end of this guide, you'll know how to integrate the Intersection Observer API into your React components to dramatically improve performance, reduce bandwidth usage, and create a seamless, professional user experience. This is the essential technique for building fast, scalable React applications that handle large amounts of content.

👉 This article is part 2 of Intersection Observer series. If you haven’t yet, start with [JavaScript Intersection Observer API: Master Scroll-Triggered Animations...] before continuing

How the Intersection Observer API Works in React: Core Concepts

To effectively use the Intersection Observer API in React, it's crucial to understand its core mechanics, as detailed in our previous guide . The API provides an asynchronous way to monitor when a target element intersects with the browser's viewport (or a specified root element), firing a callback function when the visibility changes.

The API is created with the new IntersectionObserver(callback, options) constructor. The callback function is executed whenever the intersection state of a target element changes. It receives an array of IntersectionObserverEntry objects, each containing vital properties:

• isIntersecting: A boolean that is true when the element is visible in the viewport.

• intersectionRatio: A number between 0 and 1 indicating the percentage of the element that is visible.

The options object allows you to fine-tune the observation:

• threshold: Defines at what percentage of visibility the callback should fire. A value of 0 triggers on the first visible pixel, 1 requires the entire element to be visible, and an array like [0, 0.25, 0.5, 0.75, 1] triggers at multiple points.

• rootMargin: Applies a margin (like CSS) around the viewport. A positive value like '50px' triggers the callback before the element enters the viewport, which is perfect for pre-loading content. A negative value like '-50px' requires the element to be deeper inside the viewport to trigger.

The key to using this in React is the second parameter of the callback: a reference to the IntersectionObserver instance itself. This is essential for cleanup and is the foundation of our custom hook. As the Medium article explains, this allows us to call unobserve() on a specific element or disconnect() on the entire observer, which is critical for preventing memory leaks when components unmount.

Real-World Example: Building a Performant Image Gallery in React

Imagine a portfolio site or a stock photo app. A page with 50 large images (each 1-2MB) could easily exceed 100MB of data. This leads to:

• Poor LCP (Largest Contentful Paint): The main content takes forever to appear.

• High Bandwidth Usage: Wastes data for mobile users.

• Janky Scrolling: The browser struggles to render so many heavy elements.

Our solution is a lazy-loading image with hashed light placeholder. We'll use the Intersection Observer to ensure images are only fetched and rendered when they're about to enter the viewport.

Creating a Reusable useInViewClass Hook in React and TypeScript

To integrate the Intersection Observer API seamlessly into our React components, we can encapsulate its logic into a custom hook. This promotes reusability, adheres to the DRY (Don't Repeat Yourself) principle, and keeps our component code clean and declarative.

The useInViewClass hook provided in your CodeSandbox is a perfect example of this. Let's break it down:

import { useEffect, useRef } from "react";

export function useInViewClass(className = "show", threshold = 0.5) {
 const ref = useRef<HTMLDivElement | null>(null);

 useEffect(() => {
 // Guard clause: Exit if the ref is not attached to a DOM element
 if (!ref.current) return;

 // Create a new Intersection Observer
 const observer = new IntersectionObserver(
 ([entry]) => {
 // Use destructuring to get the first (and only) entry
 // Toggle the specified class based on visibility
 entry.target.classList.toggle(className, entry.isIntersecting);
 },
 { threshold } // Configuration object
 );

 // Start observing the DOM element referenced by `ref`
 observer.observe(ref.current);

 // Cleanup function: Disconnect the observer when the component unmounts
 return () => observer.disconnect();
 }, [className, threshold]); // Re-run the effect if these dependencies change

 // Return the ref so it can be attached to a JSX element
 return ref;
}

How It Works:

1. useRef: Creates a mutable ref object (ref) that will hold a reference to the actual DOM element we want to observe.

2. useEffect: This hook runs after the component renders. It sets up the imperative logic for creating and managing the IntersectionObserver.

3. Observer Creation: Inside the effect, a new IntersectionObserver is instantiated. Its callback uses array destructuring ([entry]) to get the first IntersectionObserverEntry from the entries array.

4. Class Toggling: The callback uses classList.toggle(className, entry.isIntersecting) to add the class (e.g., show) when the element is visible and remove it when it's not. This directly links the element's visibility to its visual state.

5. Configuration: The threshold option is passed in, allowing the hook to be configured for different use cases (e.g., trigger at 50% visibility).

6. Cleanup: The return () => observer.disconnect(); line is critical. It ensures the observer stops all observation when the component is unmounted, preventing memory leaks—a best practice emphasized in the Medium article .

This hook perfectly demonstrates how to bridge the imperative nature of the DOM API with React's declarative paradigm, providing a simple, reusable tool for scroll-triggered effects. In the next section, we'll use this hook to build our heavy image gallery.

Let's apply the useInViewClass hook to a real-world performance challenge: a gallery of large, high-resolution images. Loading all these images at once can cause a massive initial payload, slow down your app, and waste bandwidth for users who may never scroll to see them all.

The Recipe Card Component

Here is a LazyRecipe component that uses our useInViewClass hook to create a smooth, professional loading experience:

import { useState } from "react";
import { BlurhashCanvas } from "react-blurhash";
import { useInViewClass } from "./useViewClass";

export default function LazyRecipe({ recipe }) {
 const [imageLoading, setImageLoading] = useState(true);
 const ref = useInViewClass(); // Observe this card's visibility

 const { 
 Image_4_3_BlurHash, 
 imageUrl, 
 Short_Title, 
 imageWidth, 
 imageHeight 
 } = recipe;

 return (
 <div className="relative h-48 w-full overflow-hidden" ref={ref}>
 {/* 1. BlurHash Placeholder */}
 {imageLoading && (
 <BlurhashCanvas
 hash={Image_4_3_BlurHash}
 width={imageWidth}
 height={imageHeight}
 punch={1} // Increases contrast
 className="absolute inset-0 h-full w-full object-cover"
 style={{
 transition: "opacity 1.2s ease-out",
 willChange: "transform, opacity",
 }}
 />
 )}

 {/* 2. The Actual Image */}
 {imageUrl && (
 <img
 src={imageUrl}
 alt={Short_Title}
 onLoad={() => setImageLoading(false)} // Hide placeholder when image loads
 className={`absolute inset-0 h-full w-full object-cover transition-all duration-700 ease-out ${
 imageLoading
 ? "scale-105 opacity-60 blur-md" // Slightly zoomed and blurred while loading
 : "scale-100 opacity-100 blur-0" // Crisp and full size when loaded
 }`}
 loading="lazy"
 decoding="async"
 fetchPriority="low"
 sizes="(max-width: 768px) 100vw, (max-width: 1024px) 50vw, 33vw"
 style={{
 willChange: "transform, opacity, filter",
 }}
 />
 )}
 </div>
 );
}

How It Works:

1. useInViewClass Hook: The ref from our custom hook is attached to the card's container. When the card enters the viewport, the show class is added, triggering any CSS animations (e.g., a fade-in).

2. BlurHash Placeholder: While the high-resolution image is loading, a BlurhashCanvas displays a compact, low-bandwidth representation of the image. This provides immediate visual feedback and prevents layout shifts.

3. Image Loading State: The useState hook manages the imageLoading state. The onLoad event of the <img> tag triggers setImageLoading(false), which removes the BlurHash and reveals the final image.

4. Smooth Transitions: CSS classes and will-change are used to create a beautiful transition from the blurred placeholder to the sharp final image, enhancing the perceived performance.

This component is a prime example of combining the Intersection Observer API with modern web techniques to build a fast, user-friendly, and visually appealing application.

The Recipes List: Our Data Source

RECIPES is powered by a static array of recipe data, containing objects, each representing a single recipe with the following properties:

• Short_Title: The name of the dish.

• imageWidth & imageHeight: The dimensions of the image.

• Image_4_3_BlurHash: A compact string representation of the image's placeholder (BlurHash).

• imageUrl: The URL to the high-resolution image.

This structure allows the LazyRecipe component to know exactly what placeholder to show and what image to load. The consistent use of BlurHash strings ensures that every card has a fast-loading, visually representative preview, creating a cohesive and high-performance user experience across the entire recipes' gallery.

const RECIPES = [
 {
 Short_Title: "Pasta Delight",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://images.unsplash.com/photo-1600891964599-f61ba0e24092?w=500&auto=format&fit=crop&q=60",
 },

 {
 Short_Title: "Avocado Toast",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://images.unsplash.com/photo-1551183053-bf91a1d81141?w=500&auto=format&fit=crop&q=60",
 },
 {
 Short_Title: "Steak Perfection",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://images.unsplash.com/photo-1543353071-873f17a7a088?w=500&auto=format&fit=crop&q=60",
 },

 {
 Short_Title: "Pasta Delight",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://images.unsplash.com/photo-1511690656952-34342bb7c2f2?q=80&w=764&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
 },
 {
 Short_Title: "Fresh Salad",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LKO2?U%2Tw=^]-;C,ogD9ZNH$j[}",
 imageUrl:
 "https://images.unsplash.com/photo-1555939594-58d7cb561ad1?q=80&w=687&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
 },
 {
 Short_Title: "Fruit Bowl",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LGF5]+Yk^6#M@-5c,1J5@[or[Q6.",
 imageUrl:
 "https://images.unsplash.com/photo-1565299624946-b28f40a0ae38?q=80&w=781&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
 },
 {
 Short_Title: "Grilled Chicken",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://images.unsplash.com/photo-1484723091739-30a097e8f929?q=80&w=749&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
 },
 {
 Short_Title: "Burger Stack",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://plus.unsplash.com/premium_photo-1663858367001-89e5c92d1e0e?q=80&w=715&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
 },
 {
 Short_Title: "Berry Smoothie",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://images.unsplash.com/photo-1504754524776-8f4f37790ca0?q=80&w=1170&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
 },
 {
 Short_Title: "Avocado Toast",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://images.unsplash.com/photo-1432139555190-58524dae6a55?q=80&w=1176&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
 },
 {
 Short_Title: "Steak Perfection",
 imageWidth: 500,
 imageHeight: 300,
 Image_4_3_BlurHash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
 imageUrl:
 "https://images.unsplash.com/photo-1540189549336-e6e99c3679fe?q=80&w=687&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
 },
];

export default RECIPES;

The Entry Point: Bringing It All Together

The final piece of our application is the App component, which serves as the entry point and orchestrates all the parts we've built. It imports the RECIPES data and the LazyRecipe component, then renders a responsive grid of recipe cards.

import LazyRecipe from "./lazy-recipe";
import "./styles.css";
import RECIPES from "./RECIPES";

export default function App() {
 return (
 <div className="App p-4 space-y-6">
 <h1 className="text-2xl font-bold">Lazy Image</h1>
 <h2 className="text-lg text-gray-600">Lazy image loading</h2>

 <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
 {RECIPES.map((recipe, index) => (
 <LazyRecipe key={index} recipe={recipe} />
 ))}
 </div>
 </div>
 );
}

Live Demo & Source Code

Live demo: https://s2lwx4.csb.app/

Source code: https://github.com/adelpro/react-lazy-images-with-blurhash

Conclusion: Mastering Performance with Native APIs

The Intersection Observer API is a powerful tool for building performant web applications. As shown in the First guide , it allows you to detect when elements enter the viewport—enabling lazy loading, infinite scroll, and scroll animations—without causing jank or layout thrashing.

By integrating this native API into React with a custom hook, we can create smooth, efficient experiences like our lazy-loading recipe gallery. The key is combining the Observer's efficiency with techniques like BlurHash to provide instant visual feedback.

Remember to prevent memory leaks by using unobserve() or disconnect() when elements are no longer needed. This simple practice ensures your app stays fast and responsive.

This pattern—using native APIs within React—is a powerful way to solve complex frontend challenges. In the next article, we'll explore more ways to optimize performance for heavy DOM loads and other resources.

What's Next: Implementing Infinite Scroll

In this article, we focused on lazy loading individual images as they come into view. In the next part of this series, we'll build upon this foundation to implement infinite scroll. We'll learn how to use a "sentinel" element at the end of our list, observe it with the Intersection Observer, and automatically load the next batch of recipes when it enters the viewport, creating a seamless, endless browsing experience.

If you’d like a ready-to-use version with these optimizations already applied, you can find it here → Next.js Starter Me Portfolio on Gumroad.

Cover image credit: StockSnap

For years, developers relied on the window.onscroll event to detect when elements entered the viewport, enabling features like lazy loading and scroll animations. However, this approach is a major performance killer. Since the scroll event fires constantly, any DOM queries inside its listener (like getBoundingClientRect()) trigger layout thrashing, blocking the main thread and causing janky, unresponsive scrolling.

The Intersection Observer API solves this problem with an elegant, asynchronous solution. Instead of actively checking positions, you create an observer that passively watches your elements. The browser efficiently handles all intersection calculations in the background and only calls your callback when an element's visibility changes, keeping the main thread free for smooth interactions.

This makes it the ideal tool for performance-critical tasks like:

• Lazy Loading images and videos.

• Scroll-Triggered Animations (e.g., "reveal" effects).

• Infinite Scrolling.

• Ad Impression Tracking.

With excellent browser support (over 95% globally), the Intersection Observer API is a modern, native JavaScript essential for building fast, engaging web experiences. Let's dive into how it works with a practical example. (source: caniuse)

This is part (1) of my series. You can read the next part (2) here → [link].

How the Intersection Observer API Works: Core Concepts

Now that we understand why the Intersection Observer API exists—to replace janky scroll listeners with a performant, asynchronous alternative—let's break down how it actually works.

The API revolves around three key components: the Observer, the Target Element, and the Callback Function.

You create an observer by instantiating a new IntersectionObserver object. Its constructor takes two arguments:

1. A callback function that fires whenever the visibility of a target element changes.

2. An optional options object to configure when the callback should fire.

The callback function receives two parameters:

• entries: An array of IntersectionObserverEntry objects, each representing a target element being observed.

• observer: A reference to the IntersectionObserver instance itself (useful for cleanup).

The IntersectionObserverEntry object contains all the data you need about the intersection state. The most important properties are:

• isIntersecting: A boolean that is true when the target element is intersecting with the root (viewport).

• intersectionRatio: A number between 0 and 1 representing the percentage of the target element that is visible (e.g., 0.5 means 50% visible).

Building Scroll-Triggered Animations: A Real-World Example

Scroll-triggered animations, often called "scroll-reveal" effects, are one of the most visually impactful uses of the Intersection Observer API. They create a dynamic and engaging user experience by animating content as it enters the viewport. The key to doing this efficiently is to separate concerns: use JavaScript to detect visibility, and CSS to handle the animation itself. This ensures smooth, 60fps performance.

Let's break down a real-world example based directly on this CodeSandbox project. This code smoothly animates cards into view as the user scrolls down the page.

How It Works: The HTML & CSS Foundation

The magic starts with CSS. We define two classes:

• .hidden: The initial, "out-of-view" state of the element.

• .show: The final, "revealed" state of the element.

/* Initial state: Hidden and off-screen */
.hidden {
 opacity: 0;
 transform: translateX(-100%);
 filter: blur(5px);
 transition: all 1s ease-out; /* Smooth transition for all properties */
}

/* Optional: Respect user preferences for reduced motion */
@media (prefers-reduced-motion) {
 .hidden {
 transition: none;
 }
}

/* Final state: Fully visible and in place */
.show {
 opacity: 1;
 transform: translateX(0);
 filter: blur(0);
}

The transition property on .hidden is crucial. It tells the browser to animate any changes to opacity, transform, and filter over one second. This means when we add the .show class, the element will glide into place.

The JavaScript Logic: Detecting Visibility

The JavaScript uses the Intersection Observer to listen for when an element becomes visible and then applies the .show class.

// 1. Select all elements you want to animate (e.g., cards with class '.hidden')
const hiddenElements = document.querySelectorAll(".hidden");

// 2. Create the Intersection Observer
const observer = new IntersectionObserver(
 (entries) => {
 entries.forEach((entry) => {
 // 3. Check if the element is currently intersecting with the viewport
 if (entry.isIntersecting) {
 // 4. Add the 'show' class to trigger the CSS animation
 entry.target.classList.add("show");

 // 5. (Optional) Stop observing after the animation starts
 // This prevents the animation from re-triggering and saves resources
 // observer.unobserve(entry.target);
 }
 // Note: Removing the 'show' class on exit is often unnecessary for one-time reveals
 });
 },
 {
 // Trigger the callback when 50% of the element is visible
 threshold: 0.5
 // rootMargin: '0px' // You can also use this to trigger earlier or later
 }
);

// 6. Start observing every element in the 'hiddenElements' collection
hiddenElements.forEach((el) => {
 observer.observe(el);
});

Key Points of This Real-World Implementation:

• Performance First: The animation runs on the GPU (thanks to transform and opacity), ensuring it doesn't block the main thread.

• User-Centric: The prefers-reduced-motion media query respects users who have requested less animation.

• Configurable: The threshold: 0.5 means the animation starts when half of the card is visible, creating a natural feel. You can adjust this to 0 (on first pixel) or 1 (only when fully visible). You can also fine-tune when the animation starts by using the rootMargin option. Think of rootMargin as padding around the viewport. By setting a positive margin, like { rootMargin: '100px' }, you tell the observer to trigger the callback when the target element is still 100 pixels away from entering the viewport. This is perfect for pre-loading content or starting an animation just before the user sees it, ensuring a seamless experience.

• Scalable: A single observer watches multiple elements, making it efficient for long pages with many animated sections.

This pattern, as demonstrated in your CodeSandbox, is a professional standard for creating smooth, performant scroll animations on modern websites.

Live Demo & Source Code

Live demo: https://y4riim.csb.app/

Source code: https://github.com/adelpro/intersection-observer-reveal-cards

What's Next: Master Lazy Loading & Performance

In this article, we've focused on using the Intersection Observer API to create smooth, performant scroll-triggered animations.

In the next article of this series, we'll shift gears to performance optimization. We'll dive into lazy loading images and videos, implementing infinite scroll, and managing heavy DOM loads—all with step-by-step examples.

Finally, we'll wrap up the series by bringing it all into the modern world of React and Next.js.

👉 Continue with [How to Boost React App Performance ...] to see the full results.

Credit: Cover image by real-napser

I tried every common performance tweak:

• Optimizing next.config.js

• Profiling heavy components and splitting code

• Using dynamic() with suspense for lazy loading

• Applying Next.js Image Optimization

And still, my app hovered around 82/88 performance score.

The real breakthrough came when I discovered the experimental inlineCss feature in Next.js.

What is inlineCss in Next.js?

According to the Next.js documentation

• Definition: inlineCss inlines CSS directly into the rendered HTML instead of linking to external .css files.

• Benefit: Eliminates extra network requests for CSS, which reduces render-blocking resources.

• Performance Gains: Improves First Contentful Paint (FCP) and Largest Contentful Paint (LCP) — two critical Core Web Vitals.

• Best Use Cases:

  • Small-to-medium apps (e.g., portfolios, landing pages, dashboards)

  • Projects where fast initial render is more important than keeping HTML payload smaller

• Caution: For apps with huge global stylesheets, HTML size may increase.

How to Enable inlineCss in Next.js

Add the following to your next.config.js (or next.config.ts):

// next.config.js
const nextConfig = {
 experimental: {
 inlineCss: true,
 },
}
export default nextConfig

After enabling inlineCss, my Next.js app finally broke through into the green zone (90+ score) on Google PageSpeed Insights 🎉.

Before:

• Score: 88–89 (orange)

• FCP/LCP: slowed by CSS request

After:

• Score: 90+ (green)

• Faster First Contentful Paint (FCP)

• Improved Largest Contentful Paint (LCP)

• More stable rendering, reduced layout shift
  After enabling this, my app jumped into the green zone (90+).

Why This Matters

For developers aiming to improve Next.js performance and optimize Core Web Vitals, CSS delivery is often an overlooked bottleneck.

My application: Me Portfolio, get if from Gumroad

Key Takeaways

1. Don’t stop at image optimization and dynamic imports.

2. Test experimental features—sometimes they solve the exact bottleneck.

3. inlineCss is especially powerful for smaller apps, where CSS size isn’t huge.

4. Always re-test with Google PageSpeed Insights after each change.

Sometimes it’s not about piling more optimizations, but finding that one bottleneck and in my case, it was CSS delivery.

Open Quran

An open-source Quran app built with Next.js and hosted on Vercel. It’s designed to provide an optimal Quran audio streaming experience across platforms. Audio content is distributed via WebTorrent in the browser, meaning it relies on WebRTC peers or web seeds—traditional TCP/UDP torrent seeds are not supported.

Open Quran Tracker & Seeder

This repo includes two Dockerized services:

1. Tracker: A self-hosted WebTorrent tracker acting as a private WebRTC bridge to connect browser peers.

2. Seeder: A torrent seeder that continuously seeds all Quran audio files to speed up availability and streaming.

The issue

While streaming works perfectly with public torrents like the Ubuntu ISO (plenty of seeds), Quran audio streaming fails or stalls. I suspect it's due to insufficient WebRTC-compatible peers or missing web seeds. Since WebTorrent in the browser can't connect to traditional torrent clients, the network needs more compatible peers (like other browsers or my custom seeder).

How you can help

• Test the Open Quran app

• Check if the torrents load for you

• Suggest improvements for peer seeding or WebRTC connectivity

• Help debug the seeder or tracker setup

Any help from those familiar with WebTorrent, browser P2P, or decentralized distribution is appreciated. Let’s push forward a censorship-resistant and scalable way to share Islamic content.

Thanks in advance!

MCP is an open, client-server protocol designed to break down data silos: it provides a universal interface so that AI models can query databases, code repos, APIs, and other systems via lightweight “servers”​, In effect, MCP is like a USB-C port for AI – a standardized way for applications to plug in context and capabilities. This post explains what MCP servers do, what’s new in Trae’s MCP implementation, the technical underpinnings (performance, architecture, transports), and a hands-on example of configuring an MCP server in Trae.

What Are MCP Servers (Model Context Protocol)?

The Model Context Protocol (MCP) is a recently released open standard (open-sourced by Anthropic in late 2024) that standardizes how AI models access data and tools.​

An MCP server is a lightweight program that exposes a specific capability – for example, fetching documents from a database, running code queries, or interfacing with GitHub – over a well-defined protocol. An MCP server implements a set of "commands" or tools that an LLM can invoke. From the LLM’s perspective, all MCP servers look the same: the protocol abstracts away the details of each data source.

MCP solves the problem of fragmented, one-off integrations. Traditionally, each AI assistant or agent needs a custom connector (for Slack, for Google Drive, for company APIs, etc.). MCP replaces that with a single client-server architecture: a host application (like Trae) connects to one or more MCP servers, and the servers connect to local or remote data sources​.

Key benefits of MCP include:

• Unified integrations: Use pre-built MCP servers (GitHub, Supabase, Postgres, etc.) or write your own, all conforming to one spec​.

• Flexible deployment: MCP servers can run locally or remotely over HTTP.

• Model-agnostic: The same MCP server can be used with different LLMs or AI assistants, so you’re not locked into one platform​.

• Secure and consistent: The protocol encourages security best practices (auth, origin checks) and consistent command schemas across tools​.

In summary, MCP servers let an AI IDE or agent call external tools as if they were built-in functions. Trae’s new support for MCP means developers can seamlessly extend the IDE’s AI with whatever services they need.

Trae v1.3.0: New MCP Integration

In Trae 1.3.0, ByteDance has integrated MCP in several ways to streamline external tool access and automation. The highlights include:

• Standardized MCP plugin system: Trae can now connect to any external tool via the MCP protocol. Developers can wire up services like Supabase, GitHub, custom REST APIs, or any local tool by adding it as an MCP server​, This expands Trae’s “contextual capabilities”.

• Project and global configuration: You define MCP servers in JSON config files. Trae supports both global and project-level settings. Global MCP servers live in a user-wide file (e.g. ~/.trae/mcp.json), while a project can include its own .trae/mcp.json or mcp_settings.json in the root. Either way, you list servers under an "mcpServers" key and provide the command to run them​. This makes integration repeatable and shareable.

• Built-in MCP Marketplace: Trae includes a searchable MCP marketplace in the IDE, where developers can browse and add pre-made MCP server definitions (for services like GitHub, Postgres, etc.) without manual config​, This one-click deployment lowers the barrier: if you need GitHub integration, simply select the GitHub MCP server and authenticate, and Trae handles the rest.

• Agent and builder integration: The new Builder Agent mode in Trae can dynamically call MCP servers as part of AI-driven tasks​, For example, an automated agent can use an MCP server to fetch repo data, call external APIs, or even manipulate the filesystem. This means more complex workflows (multi-step builds, testing, deployment, etc.) can be handled by the AI.

• Cross-platform support: Trae’s MCP features work on macOS, Windows, and Linux​, It supports advanced LLMs like Claude 3.5 Sonnet and GPT-4o, either locally or via cloud APIs. According to the release notes, Trae’s AI engine is accelerated with Intel’s OpenVINO for on-device inference, so many LLM tasks and MCP calls run efficiently even without a GPU​.

Taken together, Trae 1.3.0 treats MCP as a first-class citizen: it not only adds a configuration mechanism, but also a marketplace and UI for MCP servers, and the underlying ability for its AI agents to use any connected service.

Example 1: Setting Up puppeteer, a build in MCP Server in Trae

In this example we will setup a built in MCP server: puppeteer that let`s us search the internet.

First go to the MCP tab and click on the ADD button:

Then search for: puppeteer

Click on the (+) button

Then click on confirm (This MCP server needs no configuration)

If all goes Ok, you will see this in your MCP servers list:

Now to use it, i tried this prompt, after selecting the option “@Builder with MCP” from you “@Agents” list:

“explore quran.us.kg and extract the list of quran surahs“

Or you can explicitly run a predefined command from the puppeteer MCP list:

Run the prompt “/puppeteer_navigate explore quran.us.kg and extract the list of quran surahs“

Example 2: Setting Up lighthouse-mcp server, a custom MCP Server in Trae

As a second example, we will add lighthouse-mcp server to our Trae editor, first go to the MCP tab and click on the ADD button:

Then select the “Configure Manually” link.

Then click on the “Row Config (JSON)” button

Then past this config at the bottom of the new opened file in your editor:

    "lighthouse": {
      "command": "npx",
      "args": ["lighthouse-mcp"],
      "disabled": false,
      "autoApprove": []
    },

If all goes Ok, you will see this in the MCP servers list:

Now let’s see how it work, first select the option “@Builder with MCP” from you “@Agents” list, Then enter this example prompt: “analyze my lighthouse scores for quran.us.kg“ Trae will use Chrome on the background and make a lighthouse test over the given website ( https://quran.us.kg in my case) then will return this:

Conclusion

In conclusion, the integration of MCP servers in Trae version 1.3.0 marks a significant advancement in how AI models interact with external data and tools. By adopting the Model Context Protocol, Trae provides a unified, flexible, and secure way to extend its capabilities, allowing developers to seamlessly connect to a wide range of services. The introduction of features like the MCP marketplace, standardized plugin system, and cross-platform support enhances the IDE's functionality, making it easier for developers to automate complex workflows and leverage AI-driven tasks. With practical examples like setting up the puppeteer and lighthouse-mcp servers, Trae demonstrates the practical benefits of MCP integration, empowering developers to efficiently access and utilize external resources within their projects.

Trae (/treɪ/) is your helpful coding partner. It offers features like AI Q&A, code auto-completion, and agent-based AI programming capabilities. When developing projects with Trae, you can collaborate with AI to enhance your development efficiency.​

What is OpenRouter?

OpenRouter provides a unified API that gives you access to hundreds of AI models through a single endpoint, while automatically handling fallbacks and selecting the most cost-effective options. Get started with just a few lines of code using your preferred SDK or framework.

With OpenRouter, we can access the most powerful AI available today for free, with no extra costs, no need for self-hosting, and no requirement for a powerful PC.

Why Combine Trae + OpenRouter?

By integrating OpenRouter into Trae, you unlock access to cutting-edge AI models directly in your code editor—for free. No overhead, just productivity.

Step-by-Step: Use OpenRouter in Trae

• Open Trae, then click on the AI Model Selection button at the bottom-right corner.

• Click + Add Model.

• In the modal:

  • Choose OpenRouter from the provider dropdown.

  • Select Other models in the second dropdown.

• Now fill in:

  • Model ID (choose one below).

  • API Key (generate one here).

Recommended Free Models

You can use any model labeled as free on OpenRouter Models or Rankings. Here are a few top picks:

🧠 Gemini 2.0 Flash Thinking Experimental

ID: google/gemini-2.0-flash-thinking-exp:free An experimental version of Gemini 2.0 Flash with enhanced reasoning and "thinking process" generation.

🚀 Gemini 2.5 Pro

ID: google/gemini-2.5-pro-exp-03-25:free
Google’s most advanced AI—excels at coding, reasoning, scientific queries, and ranked #1 on the LMArena leaderboard.

🧩 Llama-3.1-Nemotron-Ultra-253B-v1

ID: nvidia/llama-3.1-nemotron-ultra-253b-v1:free
Optimized for reasoning, RAG, and tool use. Designed for large-context, low-latency inference.

Note: Add detailed reasoning instructions in the system prompt to unlock full capabilities.

📊 Qwen2.5-VL

ID: qwen/qwen2.5-vl-72b-instruct:free
Great for visual tasks—recognizes objects, charts, graphics, and layouts within images.

Conclusion

By connecting Trae with OpenRouter, you bring the world’s best free AI models into your editor. Whether you’re coding, debugging, or experimenting, this integration levels up your development flow—without extra cost or complexity.

What is the View Transitions API

View Transitions API provides a way to create an animated transition between two documents (Views), without creating an overlap in the transition.

View Transitions make this process easy and strait-full, by allowing you to make your DOM change without any overlap between states, by creating a transition animation between the states using snap-shotted views.

The current implementation of this API targets single page applications (SPAs), In this tutorial, we will explain how to do that using NextJS 13 with the new App folder.

Read more about View Transitions API here.

Is View Transitions API wildly adopted by modern browsers?

At the time when this article is written, View Transitions API is adopted by Chrome (v 111+), Edge browser (v 111+) and Opera browser (v 97+) all in the production versions, and on Android system : on android browser and Chrome for android.

Before going with this tutorial

We have talked about View Transitions API before in these articles:

We had explained what this API, how to enable it in all supported browsers and how to use it, All that in a step-by-step guide, with a working application (MPA: multipage application), with full source code, all using only Vanilla JavaScript.

You must carefully read the CSS implementation before going on with this tutorial, because we will not explain the View Transitions API again.

Then in a second article, in the same subject, we have talked about using the same View Transitions API, but we had used ReactJS.

Now we will continue in the same approach, but now using the new NextJS 13 with app router and without using any extra third parties libraries, all of that using CSS.

What we are building

In this article, we will create a multipage application, using NextJS 13 and the App Router structure, we will use the new View Transitions API to create animations when we navigate between different views (pages) all of that using only CSS.

In our application, we have three different animations:

• View animation (grow up)

• Header Animation (slide from the right)

• Content Animation (slide from the left)

This is an animated GIF, showing our final application in action:

Let’s code

First, we will create a new NextJS 13 app with the App router enabled:

npx create-next-app@latest

Be sure to choose “Yes” for the App router:

Now we should clean up the code:

For src/app/global.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

And for src/app/page.tsx

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

We will start par extending the default document type in NextJS, to add the new experimental View Transinions API:

In the src folder, Create a new folder: types, and in it create a file with the name: extendedDocument.ts

export interface ExtendedDocument extends Document {
  startViewTransition?: any;
}

We will use this new extendedDocument type to replace the default document in our NextJS code.

With the same logic, we will extend the useRouter hook from NextJS to make it support the new View Transitions API:

useAnimatedRouter hook:

In the src folder create a new folder: hook, and in it create a file named: useAnimatedRouter.ts

    "use client";
    import { ExtendedDocument } from "@/types/extendedDocument";
    import { useRouter } from "next/navigation";

    export default function useAnimatedRouter() {
      const router = useRouter();
      const viewTransitionsStatus = () => {
        const extendedDocument = document as ExtendedDocument;
        let status = "Opss, Your browser doesn't support View Transitions API";
        if (extendedDocument?.startViewTransition) {
          status = "Yess, Your browser support View Transitions API";
        }
        return status;
      };
      // Navigate to the new route
      const animatedRoute = (url: string) => {
        const extendedDocument = document as ExtendedDocument;
        if (!extendedDocument.startViewTransition) {
          return router.push(url);
        } else {
          extendedDocument.startViewTransition(() => {
            router.push(url);
          });
        }
      };
      return { animatedRoute, viewTransitionsStatus };
    }

This hook exports two functions:

• viewTansitionsStatus : Check if the browser support the new View Transitions API.

• animatedRoute: Encapsulate the default router.push() method and changes its behavior, if the browser support our API, it encapsulates it with the startViewTransition() function (please see the previous articles for more detail about this function), if not it will return with default behavior of router.push()

animatedLink component

Now we will overwrite the default bahavior of NextJS Link component, to make it support the new View Transitions API:

In the src folder create a new folder: components, and in it create a file: animatedLink.tsx

"use client";
import useAnimatedRouter from "@/hooks/useAnimatedRouter";
import Link from "next/link";
import React from "react";

type Props = {
  href: string,
  children: React.ReactNode,
};
export default function AnimatedLink({ href, children }: Props) {
  const { animatedRoute } = useAnimatedRouter();
  return (
    <Link
      href={href}
      onClick={() => {
        animatedRoute(href);
      }}
      passHref
    >
      {children}
    </Link>
  );
}

As you can see, we are using the animatedRoute() function from our newly created hook to overwrite the default onClick behavior of the Link component.

We are using “use client” here, to make this component client only.

And we are passing the passHref props here, this will allow the Link component to pass the href prop to the children.

Header component:

import Link from "next/link";
import React from "react";
import AnimatedLink from "./animatedLink";

export default function Header() {
  return (
    <div className="bg-slate-700 text-slate-50 py-4 ">
      <div className="container mx-auto flex gap-2">
        <AnimatedLink href="/">Home</AnimatedLink>
        <AnimatedLink href="/about">About</AnimatedLink>
        <AnimatedLink href="/contact">Contact</AnimatedLink>
      </div>
    </div>
  );
}

We are using the AnimatedLink component here like the default Link component. To point the three pages: Home, About and Contact.

Footer component:

"use client";
import useAnimatedRouter from "@/hooks/useAnimatedRouter";
import React from "react";

export default function Footer() {
  const { viewTransitionsStatus } = useAnimatedRouter();
  return (
    <footer className="bg-gray-800 opacity-75 text-white p-1 text-center fixed bottom-0 left-0 right-0">
      <span>{viewTransitionsStatus()}</span>
    </footer>
  );
}

We are using the viewTransitionsStatus() function from our new created hook: useAnimatedRouter to show a message in the bottom of our application.

Layout File

Now in the Layout.tsx file in the src/app folder, modify the code to include the <Header/> and the <Footer/> components

import Header from "@/components/header";
import "./globals.css";
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import Footer from "@/components/footer";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode,
}) {
  return (
    <html lang="en">
      <body className={inter.className}>
        <Header />
        {children}
        <Footer />
      </body>
    </html>
  );
}

Our three pages:

Modify the page.tsx in the src/app folder like this:

export default function Home() {
  return (
    <div className="flex flex-col h-screen items-center justify-center bg-amber-100 gap-10">
      <h1 className="text-4xl pageHeader">Home Page</h1>
      <p className="mx-10 pageContent text-center line-clamp-3">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ac urna
        auctor, viverra sapien. Donec euismod turpis eget massa lobortis, eget
        scelerisque justo.
      </p>
    </div>
  );
}

This is our Home page.

The same for the About page in the folder: src/app/about, create a new file named: page.tsx

export default function About() {
  return (
    <div className="flex flex-col h-screen items-center justify-center bg-amber-200 gap-10">
      <h1 className="text-4xl pageHeader">About Page</h1>
      <p className="mx-10 pageContent text-center line-clamp-3">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ac urna
        auctor, viverra sapien. Donec euismod turpis eget massa lobortis, eget
        scelerisque justo.
      </p>
    </div>
  );
}

In the folder: src/app/contact, create a new file named: page.tsx

export default function Contact() {
  return (
    <div className="flex flex-col h-screen items-center justify-center bg-amber-300 gap-10">
      <h1 className="text-4xl pageHeader">Contact Page</h1>
      <p className="mx-10 pageContent text-center line-clamp-3">
        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed ac urna
        auctor, viverra sapien. Donec euismod turpis eget massa lobortis, eget
        scelerisque justo.
      </p>
    </div>
  );
}

Take a close look at the <h1> and <p> tags in the three pages:

• <h1> contain the class: pageHeader

• <p> contain the class: pageContent

We will use these CSS classes to animate these section later

globals.css

Now we will use the magic of View Transitions API to animate our application using only CSS.

All the magic happen in this file: globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

/* Animate the page header separatly */
.pageHeader {
  view-transition-name: page-header;
}

/* Animate the page content separatly */
.pageContent {
  view-transition-name: page-content;
}

::view-transition-old(root) {
  animation: fade-and-scale-out 0.5s ease-in-out 1 forwards;
}

::view-transition-new(root) {
  animation: fade-and-scale-in 1s ease-in-out 1 forwards;
}

::view-transition-old(page-header) {
  animation: hide 1s ease-in-out 1 forwards;
}

::view-transition-new(page-header) {
  animation: slide-right 2s ease-in-out 1 forwards;
}

::view-transition-old(page-content) {
  animation: hide 1s ease-in-out 1 forwards;
}

::view-transition-new(page-content) {
  animation: slide-left 2.5s ease-in-out 1 forwards;
}

/* First Animation */

@keyframes fade-and-scale-in {
  from {
    opacity: 0;
    transform: scale(0);
  }

  to {
    opacity: 1;
    transform: scale(1);
  }
}

@keyframes fade-and-scale-out {
  from {
    opacity: 1;
    transform: scale(1);
  }

  to {
    opacity: 0;
    transform: scale(0);
  }
}

/* Second Animation */

@keyframes hide {
  from {
    opacity: 1;
  }

  to {
    opacity: 0;
  }
}

@keyframes slide-left {
  from {
    opacity: 0;
    transform: translateX(-100%);
  }

  to {
    opacity: 1;
    transform: translateX(0);
  }
}

@keyframes slide-right {
  from {
    opacity: 0;
    transform: translateX(100%);
  }

  to {
    opacity: 1;
    transform: translateX(0);
  }
}

We will explain every part of this file:

@tailwind base;
@tailwind components;
@tailwind utilities;

This is a part of TailwindCSS default configuration, it's present by default in our globals.css file.

/* ... */

::view-transition-old(root) {
  animation: fade-and-scale-out 0.5s ease-in-out 1 forwards;
}

::view-transition-new(root) {
  animation: fade-and-scale-in 1s ease-in-out 1 forwards;
}

/* ... */

@keyframes fade-and-scale-in {
  from {
    opacity: 0;
    transform: scale(0);
  }

  to {
    opacity: 1;
    transform: scale(1);
  }
}

@keyframes fade-and-scale-out {
  from {
    opacity: 1;
    transform: scale(1);
  }

  to {
    opacity: 0;
    transform: scale(0);
  }
}

This part of the code will animate the root element of the views (our pages), and the state of the animation changes between the old and the new state, for that we have two CSS keyframe animations:

-
  fade-and-scale-in
  -
  fade-and-scale-out.../\*
  Animate
  the
  page
  header
  separatly
  \*/
  .pageHeader {
  view-transition-name: page-header;
}
...::view-transition-old(page-header) {
  animation: hide 1s ease-in-out 1 forwards;
}
::view-transition-new(page-header) {
  animation: slide-right 2s ease-in-out 1 forwards;
}
.../\* Second Animation \*/@keyframes hide {
  from {
    opacity: 1;
  }
  to {
    opacity: 0;
  }
}
@keyframes slide-right {
  from {
    opacity: 0;
    transform: translateX(100%);
  }
  to {
    opacity: 1;
    transform: translateX(0);
  }
}

In this part of the code, we had created a new view-transition container, with the using: view-transition-name: page-header, with is assigned to the CSS class: pageHeader

We will use this name: “page-header” to assign a new animation (hide and slide-right).

/* ... */

/* Animate the page header separatly */
.pageContent {
  view-transition-name: page-content;
}

/* ... */

::view-transition-old(page-content) {
  animation: hide 1s ease-in-out 1 forwards;
}

::view-transition-new(page-header) {
  animation: slide-left 2.5s ease-in-out 1 forwards;
}

/* ... */

/* Second Animation */

@keyframes hide {
  from {
    opacity: 1;
  }

  to {
    opacity: 0;
  }
}

@keyframes slide-left {
  from {
    opacity: 0;
    transform: translateX(-100%);
  }

  to {
    opacity: 1;
    transform: translateX(0);
  }
}

With the same logic, we had created a new view-transition container, with the using: view-transition-name: page-content, with is assigned to the CSS class: pageContent.

We will use this name: “page-content” to assign a new animation (hide and slide-left).

Full complete source code (on GitHub)

Live Demo with source code (on Codesandbox)

Page Transitions In Next.js

Conclusion

Using view-transition containers in CSS allows for smooth animations of page elements, like headers and content. By defining custom animations such as "hide" and "slide-left," you can enhance user experience in applications like Next.js. The full implementation can be explored through the provided GitHub and CodeSandbox links.

What is the View Transitions API

View Transitions API provides a way to create an animated transition between two documents (Views), without creating an overlap in the transition.

View Transitions make this process easy and strait-full , by allowing you to make your DOM change without any overlap between states, by creating a transition animation between the states using snap-shotted views.

The current implementation of this API targets single page applications (SPAs), In this tutorial we will explain how to do that using ReactJS.

View Transitions API browser support?

• The View transition API should be on by default for Chrome 111 beta users.

• You can enable it by accessing the experiment flag: chrome://flags/#view-transition in Chrome 109 and above.

• The same process for Chromium based browsers (Microsoft Edge, Brave, Opera …).

• For Mozilla Firefox, The View transitions API is not implemented yet.

Before going with this tutorial

We have talked about View Transitions API before (In this tutorial).

We explained what this API is, how to enable it in supported browsers and how to use it, a step by step guide, with a final working example application (MPA: multi page application), with full source code, all using only Vanilla JavaScript.

You must carefully read the CSS implementation, because we will go on with the same logic in this tutorial.

But To apply that to a ReactJS application we have to do that with a different approach.

What we are building

This is an animated GIF, showing our final application in action

Let’s code

Let’s see what we are building

In our Application, we will use create-react-app to create a starting project, that let’s as navigate between three pages or views: home, download and about.

First

npx create-react-app reactjs-react-router-view-transitions-api 
&& cd reactjs-react-router-view-transitions-api

Second

npm install react-router-dom

To install React Router V6 package.

Our application will contain these files:

ReactJs - React Router - View Transitions API

└─ src
   └─ img
      ├─ home.png
      ├─ about.png
      └─ download.png
   ├─ About.js
   ├─ App.js
   ├─ Download.js
   ├─ Header.js
   ├─ Home.js
   ├─ PageNotFound.js
   ├─ Index.js
   ├─ styles.css
   └─ ...

- The “/img” folder

contain the images used in our project.

- Index.js

It’s the entry point of our project

import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter, Route, Routes } from "react-router-dom";
import App from "./App";

const rootElement = document.getElementById("root");
const root = createRoot(rootElement);

root.render(
  <StrictMode>
    <BrowserRouter>
      <Routes>
        <Route path="/*" element={<App />} />
      </Routes>
    </BrowserRouter>
  </StrictMode>
);

As you can see, we are routing all pages to the <App/> component, using the “/*” in the path prop.

In React Router v6, All routes : <Route> must be contained in the <BrowserRouter> and <Routes>

<BrowserRouter>
  <Routes>
    <Route path="/*" element={<App />} />
  </Routes>
</BrowserRouter>

- App.js

import { Routes, Route } from "react-router-dom";
import "./styles.css";

import Home from "./Home";
import Header from "./Header";
import PageNotFound from "./PageNotFound";
import About from "./About";
import Download from "./Download";

export default function App() {
  let isViewTransition = "Opss, Your browser doesn't support View Transitions API";
  if (document.startViewTransition) {
    isViewTransition = "Yess, Your browser support View Transitions API";
  }

  return (
    <>
      <Header />
      <Routes>
        {/* Routes */}
        <Route index element={<Home />} />
        <Route path="About" element={<About />} />
        <Route path="download" element={<Download />} />

        {/* 404 page */}
        <Route path="*" element={<PageNotFound />} />
      </Routes>

      <footer>
        <a href="/">Complete tutorial on Medium</a>
        <p>{isViewTransition}</p>
      </footer>
    </>
  );
}

After routing all page to our <App> component, we will point each page to to corresponding component, All contained in <Routes>…</Routes>

{/* Routes */}
<Route index element={<Home />} />
<Route path="about" element={<About />} />
<Route path="download" element={<Download />} />

{/* 404 page */}
<Route path="*" element={<PageNotFound />} />

• Route “index” point to “/”, will show the <Home> component.

• path about and download point to <About> and <Download> components respectively.

• All the other paths “*” will point to <PageNotFound>c component.

Now, we did a check to show if our browser supports or not Our View Transitions API, and show the result at the bottom of every page, in our footer, By checking the “document.startViewTransition”.

let isViewTransition = "Oops, Your browser doesn't support View Transitions API";

if (document.startViewTransition) {
  isViewTransition = "Yes, Your browser supports View Transitions API";
}

...

<footer>
  <p>{isViewTransition}</p>
</footer>

...

return (
  <>
    <Header />
    ...

It’s here were we will implement our View Transitions API

- Header.js

import { useNavigate } from "react-router-dom";
import "./styles.css";

export default function Header() {
  const navigate = useNavigate();

  const viewNavigate = (newRoute) => {
    // Navigate to the new route
    if (!document.startViewTransition) {
      return navigate(newRoute);
    } else {
      return document.startViewTransition(() => {
        navigate(newRoute);
      });
    }
  };

  return (
    <div className="header__container">
      <span>ReactJs - React Router - View Transitions API</span>
      <div className="link__container">
        <button
          onClick={() => {
            viewNavigate("/");
          }}
        >
          Home
        </button>
        <button
          onClick={() => {
            viewNavigate("/download");
          }}
        >
          Download
        </button>
        <button
          onClick={() => {
            viewNavigate("/about");
          }}
        >
          About
        </button>
      </div>
    </div>
  );
}

The main function in this tutorial is viewNavigate()

const navigate = useNavigate();

const viewNavigate = (newRoute) => {
  // Navigate to the new route
  if (!document.startViewTransition) {
    return navigate(newRoute);
  } else {
    return document.startViewTransition(() => {
      navigate(newRoute);
    });
  }
};

This function will encapsulate the ReactJS build-in navigate() function imported from useNavigate hook

If the browser do not support our View Transitions API, it will return a simple navigate() function with the parameter: newRoute

But when our browser supports our View transitions api, we will encapsulate our navigate(newRoute) with: document.startViewTransition() with one parameter; an arrow function.

return document.startViewTransition(() => {
  navigate(newRoute);
});

When document.startViewTransitionis called:

→ The API captures the current state of the page including a screenshot. This includes taking a screenshot, which is async as it happens in the render steps of the event loop.

→ the API constructs a pseudo-element tree:

view-transition

└─ ::view-transition-group(root)

 └─ ::view-transition-image-pair(root)

   ├─ ::view-transition-old(root)

   └─ ::view-transition-new(root)

→ Then the call-back function is called: ”() => {navigate(newRoute)}”.

→ Capture the new state of our page.

→ Reconstruct the DOM to include the new elements.

→ All that happens asynchronously, the Rendering is paused, so the user doesn’t see a flash of the new content.

View Transitions flow

→ view-transition: sits on top of the animation as an overlay.

→ view-transition-group: Responsible for animating the size and position between the old and the new stats.

→ view-transition-image-pair: hold the current state of the animation.

→ The animation transits from the starting view (view-transition-image-old) to the new view (view-transition-image-new).

→ By default The animation is a cross-fade CSS transition.

→ The animation is done with CSS animations, both stats render as CSS ( the new CSS style will replace the old one), From opacity:1 to opacity:0 for the old view, then from opacity:0 to opacity:1 for the new view.

→ The root key means that the animation i’ll be applied to the entire page.

We can easily customise these transitions with CSS, we will talk about that in the next part of the tutorial, and will explain the style.css.

- Style.css

→ We will start by changing the default animation timing, the outgoing View go out fast and the incoming View come in slow

::view-transition-old(root) {
  animation-duration: 0.5s;
}

::view-transition-new(root) {
  animation-duration: 10s;
}

→ Then change the default animation, by creating two CSS keyframes; one for the old stat exit animation and the second for the new stat entrance.

@keyframes fade-and-scale-in {
  from {
    opacity: 0;
    transform: scale(0);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

@keyframes fade-and-scale-out {
  from {
    opacity: 1;
    transform: scale(1);
  }
  to {
    opacity: 0;
    transform: scale(0);
  }
}

→ Now grouping all these properties using CSS Shorthand to have less code

/* Views Animation */

::view-transition-old(root) {
  animation: fade-and-scale-out 0.5s ease-in-out 1 forwards;
}

::view-transition-new(root) {
  animation: fade-and-scale-in 10s ease-in-out 1 forwards;
}

@keyframes fade-and-scale-in {
  from {
    opacity: 0;
    transform: scale(0);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

@keyframes fade-and-scale-out {
  from {
    opacity: 1;
    transform: scale(1);
  }
  to {
    opacity: 0;
    transform: scale(0);
  }
}

/* Explanation of this line of CSS code */
{
  animation: fade-and-scale-out 1s ease-in-out 1 forwards;
}

• .fade-and-scale-out: This is the name of the animation. It's also used as the class name for the element that will be animated.

• 1s: This is the duration of the animation, which is set to 1 second.

• ease-in-out: This is the timing function of the animation. In this case, it starts slowly, accelerates through the middle, and slows down at the end.

• 1: This is the number of times the animation will repeat. In this case, it will only run once.

• forwards: This is the value of the animation-fill-mode property, which determines what styles are applied to the element before and after the animation runs. In this case, forwards means that the element will retain the styles from the last keyframe of the animation after the animation ends.

And this line too

{
  animation: fade-and-scale-in 1s ease-in-out 1 forwards;
}

• .fade-and-scale-in: This is the name of the animation. It's also used as the class name for the element that will be animated.

• 1s: This is the duration of the animation, which is set to 1 second.

• ease-in-out: This is the timing function of the animation. In this case, it starts slowly, accelerates through the middle, and slows down at the end.

• 1: This is the number of times the animation will repeat. In this case, it will only run once.

• forwards: This is the value of the animation-fill-mode property, which determines what styles are applied to the element before and after the animation runs. In this case, forwards means that the element will retain the styles from the last keyframe of the animation after the animation ends.

- Our Views or pages

We have three pages: Home, About and Download, all linked to their respective components.

The code is identical for these pages, will will take Home as example

import home from "./img/home.png";

export default function Home() {
  return (
    <main>
      <h1>Home</h1>
      <p>
        Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
        tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim
        veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea
        commodo consequat. Duis aute irure dolor in reprehenderit in voluptate
        velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint
        occaecat cupidatat non proident, sunt in culpa qui officia deserunt
        mollit anim id est laborum
      </p>
      <img className="img" src={home} alt="Home" />
    </main>
  );
}

We have a <main> section with a <h1> title and paragraph <p> with a “lorem ipsum…” random text, and an image <img> imported as variable: home at the beginning of the file.

.header__container {
  display: flex;
  justify-content: space-between;
}

.link__container a {
  margin-right: 10px;
}

.main__container {
  width: 90%;
  padding: 3px;
  max-width: 600px;
  margin: auto;
  display: flex;
  justify-content: center;
  align-items: center;
  flex-direction: column;
}

.img {
  width: 300px;
  height: 400px;
  margin: auto;
  width: 100%;
}

/* Views Animation */
::view-transition-old(root) {
  animation: fade-and-scale-out 0.5s ease-in-out 1 forwards;
}

::view-transition-new(root) {
  animation: fade-and-scale-in 10s ease-in-out 1 forwards;
}

@keyframes fade-and-scale-in {
  from {
    opacity: 0;
    transform: scale(0);
  }
  to {
    opacity: 1;
    transform: scale(1);
  }
}

@keyframes fade-and-scale-out {
  from {
    opacity: 1;
    transform: scale(1);
  }
  to {
    opacity: 0;
    transform: scale(0);
  }
}

/* Second animation */
@keyframes slide-in {
  from {
    opacity: 0;
    transform: translateX(100%);
  }
  to {
    opacity: 1;
    transform: translateX(0);
  }
}

@keyframes slide-out {
  from {
    opacity: 1;
    transform: translateX(0);
  }
  to {
    opacity: 0;
    transform: translateX(-100%);
  }
}

We have added a second CSS animation that you can try as a practice, go on try it and tell us what animation is best.

Full complete source code

https://codesandbox.io/p/sandbox/efbc5s