DEV Community: Salva Torrubia

The Complete Guide to Capacitor Push Notifications: iOS, Android & Firebase

Salva Torrubia — Mon, 26 Jan 2026 08:13:26 +0000

Prerequisites: read this before you start

Unlike Android development, where you can test almost everything for free, Apple puts Push Notifications behind a paywall. Before trying to follow this guide, ensure you meet these requirements:

The "Entry Fee"

Apple: You MUST have an active Apple Developer Program membership ($99/year). You cannot implement Push Notifications with a free Apple ID. The "Push Notifications" capability will simply not appear in your provisioning profiles.

Android: Totally free to develop. You only pay the $25 (one-time fee) when you are ready to upload the app to the Google Play Store.

Required Roles

To create the necessary Certificates, Identifiers, and Keys (.p8), you need the right permissions in your team:

Apple Developer Portal: You need to be the Account Holder or have the Admin role. (Sometimes the "App Manager" role works, but "Developer" accounts often have restrictions on creating new Identifiers or Keys).

Firebase Console: You need Editor or Owner permissions to upload the keys and change project settings.

System Requirements:

Mac User: You need a Mac with Xcode installed to configure the iOS capabilities properly.

Physical iPhone: As mentioned later, you cannot test APNs on a Simulator.

Introduction

Stop struggling with APNs tokens and UNIMPLEMENTED errors. Here is the definitive guide to integrating @capacitor-firebase/messaging correctly, covering the basics you might have missed.

The Problem: When the Standard Plugin Just Isn't Enough

If you have ever tried to implement Push Notifications in Capacitor following the official documentation, you might have hit the "iOS Wall."

On Android, everything usually works fine. But on iOS, the standard plugin returns a native APNs Token (hexadecimal). When you try to use this token in the Firebase Console... silence. This is because Firebase Cloud Messaging (FCM) expects an FCM Token, not Apple's native one.

The robust solution in 2026 is to use the community-maintained plugin: @capacitor-firebase/messaging. It handles the native swizzling (intercepting the token) and gives you a unified FCM token for both platforms.

In this guide, I will walk you through the mandatory basics and the friction points that usually break production builds.

Step 1: Firebase Project Setup

Before touching the code, we need to tell Google and Apple who we are.

Android Setup

Go to Firebase Console > Project Settings.
Add an Android App using your Package Name (e.g., com.yourcompany.app).
Download google-services.json and place it inside android/app/.
Check your Gradle files: Ensure com.google.gms.google-services is included in your build.gradle dependencies.

iOS Setup (The Tricky Part)

Add an iOS App in Firebase Console using your Bundle ID.
Download GoogleService-Info.plist.
Crucial: Add this file to your project using Xcode (drag and drop into App/App).
The "Silent" Error Fix: Click on the file in Xcode. In the right panel, ensure "Target Membership" is checked for "App".
Double Check: Go to Build Phases > Copy Bundle Resources. Ensure the plist file is listed there. If it's missing, the app will crash or fail silently at runtime.

Step 2: The "Boring" But Mandatory Apple Config

Enable Capabilities in Xcode

Open your project: npx cap open ios.
Select App (Root) > Target App > Signing & Capabilities.
Add Push Notifications.
Add Background Modes and check Remote notifications.

Provisioning Profiles (Regenerate!)
If you added the "Push" capability to your App ID after generating your provisioning profiles, they are invalid. You must go to the Apple Developer Portal, regenerate the profiles, and download them again in Xcode (or let Xcode manage signing automatically).

One Key to Rule Them All (.p8)

Use an APNs Authentication Key (.p8) instead of old certificates.
Go to Apple Developer Portal > Keys. Create a key with APNs enabled.
Download the .p8 file (Save it!).
Upload it to Firebase Console > Project Settings > Cloud Messaging.

Tip: Ensure you upload it to the exact Firebase project linked to your app. Mixing up Team IDs or Key IDs will stop messages dead in their tracks.

Step 3: Installation & Migration

Let's switch engines.

** 1. Remove legacy plugin (if installed)**
npm uninstall @capacitor/push-notifications
rm -rf ios/App/Pods 
rm ios/App/Podfile.lock

** 2. Install Community Plugin**
npm install @capacitor-firebase/messaging firebase
npx cap sync

Step 4: Critical iOS Configuration

1. Update the Podfile (iOS 15.0+)
Open ios/App/Podfile. Bump the platform version to at least 15.0.

# ios/App/Podfile
platform :ios, '15.0' # <--- CRITICAL
use_frameworks! 
# Note: If 'use_frameworks!' causes conflicts with other plugins, 
# try 'use_modular_headers!' instead.

target 'App' do
  capacitor_pods
  pod 'Firebase/Messaging'
end

2. Simplify the AppDelegate
We need to initialize Firebase. The plugin handles the rest via Swizzling (make sure FirebaseAppDelegateProxyEnabled is NOT set to NO in your Info.plist, or you'll have to handle methods manually).

Open ios/App/App/AppDelegate.swift:

import UIKit
import Capacitor
import FirebaseCore
import FirebaseMessaging

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, 
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        FirebaseApp.configure()
        return true
    }
}

Step 5: Android 13+ Permissions

Open android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS"/>

Step 6: The Code (React/TypeScript)

import { FirebaseMessaging } from '@capacitor-firebase/messaging';

const setupNotifications = async () => {
  try {
    // 1. Request permission
    const { receive } = await FirebaseMessaging.requestPermissions();

    if (receive === 'granted') {
      // 2. Get the FCM Token (Unified for iOS & Android!)
      const { token } = await FirebaseMessaging.getToken();
      console.log('My FCM Token:', token);
    } else {
      console.warn('Permission denied');
    }

    // 3. Listen for notifications
    await FirebaseMessaging.addListener('notificationReceived', (event) => {
      console.log('Notification:', event);
    });

  } catch (error) {
    console.error('Error:', error);
  }
};

The "iOS Wall": Pre-Flight Checklist

If one of these is red, it won't work.

Are you using a Simulator? Push Notifications DO NOT work on iOS Simulators for APNs. You must use a physical iPhone.
App ID Capabilities: Does your App ID in the Apple Portal have "Push Notifications" enabled?
Provisioning Profile: Did you regenerate the profile after enabling Push capabilities?
Build Phases: Is GoogleService-Info.plist in "Copy Bundle Resources"?
Firebase Project: Did you upload the .p8 key to the correct Firebase project?

Conclusion

Migrating to @capacitor-firebase/messaging provides a production-ready architecture. You get unified FCM tokens, rich notifications support, and you stop fighting with APNs quirks.

From Monolith to Monorepo: Building Faster with Turborepo, pnpm and Capacitor

Salva Torrubia — Tue, 30 Sep 2025 08:07:13 +0000

The Challenge

I had a React web application already in production with a configured UI library, ESLint setup, and reusable components. Everything was working smoothly until the project requirements expanded: I needed to build a lightweight version of the web app and native applications for both Android and iOS.

As a solo developer, I faced a critical decision: should I create two separate repositories for these new applications, or integrate everything into a single repository?

The idea of managing multiple repositories didn't appeal to me. The project wasn't massive, and I saw real value in keeping everything together while sharing common tools and configurations. Module Federation was on the table, colleagues had used it successfully but I wanted to explore other options first.

That's when I discovered the monorepo approach and decided to give Turborepo a try.

Why Turborepo?

Several monorepo solutions existed (Nx and Lerna being the most popular) but Turborepo stood out for a few reasons. I'd heard excellent things about its performance, and knowing that Vercel backed it gave me additional confidence in its long-term viability.

More importantly, Turborepo paired perfectly with pnpm, a package manager I'd been eager to try. The combination promised shared dependencies across workspaces, dramatically reducing installation times while ensuring version alignment across all applications. This was huge for preventing future dependency conflicts.

The Architecture

I restructured my repository from having everything dumped in the root to a clean, organized structure. A simple text diagram helps visualize it instantly:

my-monorepo/

├── apps/
│   ├── web             # Main web app
│   ├── web-light       # Lightweight version
│   └── mobile          # Capacitor app
├── packages/
│   ├── ui              # Shared React components
│   ├── tsconfig        # Shared TypeScript config
│   └── vite.config.ts  # Shared ESLint config
└── package.json        # Root package.json

The apps/ folder contains the final applications, while the packages/ folder holds all shared code. This includes the UI library with common components, theme, hooks, types or locales. This architecture gave me consistency across all three applications. The look and feel would be perfectly aligned, and any component with reuse potential could be moved to packages/ui and instantly become available everywhere.

The Perfect Stack

Three tools formed the backbone of this transformation.

Turborepo
Turborepo acts as the orchestrator with its impressive caching system that tracks task outputs and only rebuilds what's changed. Build times dropped dramatically after the initial run, tasks execute in parallel across workspaces, and the dependency graph management is intelligent enough to handle complex scenarios.

Pnpm
pnpm is an excellent choice for managing a monorepo because it optimizes dependency handling by reusing packages instead of duplicating them. This not only saves a significant amount of disk space but also reduces installation times, making the overall development process more efficient. For these reasons, moving from npm to pnpm at this point was a natural and logical step.

Capacitor
Capacitor turned out to be the most practical choice for mobile development because it allowed me to maximize code reuse without adding unnecessary complexity. Unlike React Native, which requires a separate set of components and often an abstraction layer to bridge the gap with web-based libraries, Capacitor runs the app inside a modern WebView, meaning my existing UI package built with React and CSS Modules worked immediately with no adjustments. This direct compatibility saved significant development effort, kept the architecture simple, and still delivered performance more than sufficient for a small-to-medium application focused on data display and user interaction. Backed by the Ionic team, Capacitor offered the right balance of reliability, efficiency, and simplicity, making it the natural choice for my project.

Smart Dependency Management

I moved all development dependencies (TypeScript, ESLint, Vite, etc.) to the root package.json since they are shared across all workspaces:

{
  "devDependencies": {
    "@types/react": "^18.2.0",
    "@typescript-eslint/eslint-plugin": "^6.0.0",
    "@vitejs/plugin-react": "^4.0.0",
    "eslint": "^8.45.0",
    "typescript": "^5.1.0",
    "vite": "^4.4.0",
    "vitest": "^0.34.0"
  }
}

Each individual app only declares its runtime dependencies. This keeps package.json files clean and ensures everyone uses the same tooling versions.

Configuration Excellence

Turborepo's strength lies in allowing base configurations that extend to specific applications. Here's my TypeScript setup from one of the apps:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "incremental": true,
    "tsBuildInfoFile": ".tsbuildinfo",
    "types": ["vite/client", "vitest/globals"],
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["src", ".eslintrc.cjs", "vite.config.ts", "vitest.config.ts"],
  "exclude": ["node_modules", "dist"]
}

This same pattern extended to ESLint, Prettier, and other tooling configurations.

The Game-Changer: Cached CI/CD

The most impressive benefit came when integrating Turborepo with Husky for pre-push hooks. Running automated tests and linting across multiple applications used to be painful, often taking over 3 minutes.

With Turborepo's caching, my pre-push hook went from 3 minutes to 5 seconds when iterating on a single app. The configuration in turbo.json was straightforward:

{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", "build/**"]
    },
    "lint": {
      "outputs": [".eslintcache"]
    },
    "test": {
      "dependsOn": ["typecheck"],
      "outputs": ["coverage/**"]
    }
  }
}

The key is "dependsOn": ["^build"]. The ^ prefix tells Turborepo that this task depends on the build task of all its internal package dependencies, allowing it to intelligently cache and re-run only what's necessary.

The One Hiccup (and Its Elegant Solution)

The transition wasn't entirely smooth. I encountered an issue when building CSS Modules in the packages/ui workspace. The solution was integrating Vite as the build tool for the UI package itself. Vite's native support for CSS Modules resolved the issue immediately.

Keeping the Package Lightweight

I didn't want to bloat the UI package with bundled dependencies. The trick was using peerDependencies in its package.json and marking them as external in Rollup's configuration via Vite. This makes each consuming application responsible for providing them.

Here's the packages/ui/package.json structure:

{
  "name": "@package/ui",
  "version": "1.0.0",
  "main": "./dist/index.cjs",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "peerDependencies": {
    "react": "^18.0.0",
    "react-dom": "^18.0.0",
    "@mantine/core": "^7.0.0"
  }
}

Libraries like React, Mantine, or React Router, which depend on a global context or need to exist as a single instance (singleton) in the application, must be peerDependencies. This avoids conflicts and subtle bugs caused by having multiple versions of the same library in the final bundle.

And the corresponding Vite configuration:

  // Prod
  return {
    plugins: [
      react(),
      dts({
        insertTypesEntry: true,
        include: ['src/**/*'],
        exclude: ['**/*.test.*', '**/*.stories.*'],
        outDir: 'dist',
      }),
    ],
    resolve: {
      alias: {
        '@package/ui': resolve(__dirname, 'src'),
      },
    },
    build: {
      lib: {
        entry: resolve(__dirname, 'src/index.ts'),
        name: 'PackageUI',
        fileName: 'index',
        formats: ['es', 'cjs'],
      },
      rollupOptions: {
        external: [
          // React ecosystem
          'react',
          'react-dom',
          'react/jsx-runtime',
          'react/jsx-dev-runtime',
          // Rest of main dependencies

This approach kept the UI package minimal, avoided duplicate React instances, and reduced the final bundle size significantly.

Bonus Tip: Unlock HMR

The development configuration (command === 'serve') is the secret sauce for achieving lightning-fast Hot Module Replacement across your entire monorepo. By setting the alias 'package/ui': resolve(__dirname, 'src'), we're telling Vite to resolve imports directly to the source code instead of compiled bundles. This creates an instantaneous development experience where any change to a UI component automatically reflects across all applications that use it, without page reloads or state loss. You can edit a Button component in your UI package and watch it update simultaneously in any app in real-time, making monorepo development feel as smooth as working with a single application. This setup is strictly for local development; in production, applications consume the compiled packages instead.


export default defineConfig(({ command }) => {
  // local
  if (command === 'serve') {
    return {
      plugins: [react()],
      resolve: {
        alias: {
          '@package/ui': resolve(__dirname, 'src'),
        },
      },
      server: {
        hmr: {
          overlay: true,
        },
      },
      mode: 'development',
    }
  }

Results

The development velocity improvement was exponential. For solo developers or small teams managing multiple related applications, the Turborepo + pnpm + Capacitor combination offers an incredibly powerful workflow. The initial setup investment its crucial, faster iterations, better code sharing, and a dramatically improved developer experience.

Avoid These Common Email Template Mistakes (and What to Do Instead)

Salva Torrubia — Fri, 04 Jul 2025 13:19:58 +0000

Email design can be tricky. Different email services (Gmail, Outlook, Yahoo, Apple Mail) show HTML in their own way. Working on this template took me back to the early web days, when grids didn’t exist, divs weren’t standard, and every layout depended on inline CSS. At the start, I read documentation recommending inline styles over external or embedded CSS, which proved invaluable throughout the build. In this post, I explain simple practices I follow and give tips to make emails look good everywhere.

Character Encoding Meta Tag

Make sure to include this meta tag in the head section of your email HTML to guarantee proper rendering of characters and emojis across all clients. This tag helps prevent garbled text and ensures consistent character encoding:
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

Choosing Emojis Over Custom Icons

I once used an icon font for bullet points and checkmarks. But some clients blocked the font, showing empty boxes. Today, I use simple Unicode emojis (✅, 🚀). They display correctly and need no extra files.
<span style="font-size:20px;">🚀 Fast Loading</span>

When 700px Broke on Mobile

During a test send, a coworker and I discovered the email didn’t display correctly in a specific email client version on his mobile device. Instead of allowing a scrollbar, the client simply reduced the visible content area without any warning, breaking our original design. We had set the template width to 700px to show more content, but this unexpected resizing hid key sections and disrupted the visual flow.

Now I always use 600px, a width that fits most mobile screens and still looks great on desktop.

PNG Images for Consistency

SVG logos look sharp, but many Outlook versions and older Android apps ignore SVG. Switching to PNG images at 2× resolution (e.g., logo@2x.png) ensures crisp display. I also compress images with TinyPNG to keep file sizes small.
<img src="logo@2x.png" width="150" height="50" style="display:block;" alt="Logo">

Bulletproof Backgrounds for Outlook

Standard CSS backgrounds work in most clients, but Outlook uses Word’s engine and ignores them. The bulletproof method uses VML for Outlook and CSS for others.

<!--[if gte mso 9]>
<v:rect xmlns:v="urn:schemas-microsoft-com:vml" fill="true" stroke="false" style="width:600px;height:300px;">
  <v:fill type="frame" src="hero-bg.png" color="#ffffff" />
  <v:textbox inset="0,0,0,0">
<![endif]-->
  <div style="background-image:url('hero-bg.png');background-size:cover;">
    <!-- Content -->
  </div>
<!--[if gte mso 9]>
  </v:textbox>
</v:rect>
<![endif]-->

Inline CSS vs. External Stylesheets

At the beginning of this project, I wondered whether to keep my styles in an external .css file or to inline them directly on each element. After reading multiple guides and official email platform documentation, it became clear that inline CSS is the safer choice. Inline styles carry the highest priority in the cascade, so they are less likely to be overridden or removed by email clients like Gmail or older Outlook versions.

Additional Recommendations

Here are some extra tips to make your templates even more reliable:

Avoid Flash and JavaScript: Most email clients disable scripts or have no Flash support. If you need motion or animation, use a simple animated gif instead.
Set Table Roles: Add role="presentation" to your tables to improve accessibility for screen readers and assistive technology.
Fallbacks for Background Images: Provide a solid background-color in inline styles so that if the image fails to load, the email still looks intentional:

<div style="background-color:#333333; background-image:url('bg.png');">
  <!-- Content -->
</div>

Custom Font Fallbacks: When using custom fonts, always declare web-safe alternatives and include inline font-family stack: font-family: 'MyCustomFont', Arial, sans-serif;

Tools for Testing

Postdrop: Inline CSS, send tests, and store templates.
Htmlemailcheck: check best practices for html templates.
Mail-tester: Test the Spammyness of your Emails
validator.w3: This validator checks the markup validity of Web documents in HTML

Summary

Following these steps will help your emails look great and work smoothly for all readers. This project truly reminded me of those old-school coding times, reinforcing that sometimes the simplest, most manual methods are still the most reliable. Happy emailing!

Why I Chose Mantine as my React UI Library

Salva Torrubia — Wed, 18 Jun 2025 11:54:54 +0000

At the outset of any new software project, front-end developers face a critical decision: should we construct the user interface from the ground up to achieve maximum control, or should we utilize a pre-built component library to accelerate the development timeline? For a recent project, the path forward was evident. Our team was tasked with delivering a smallscale application under a tight deadline, where the primary objectives were development speed, interface consistency, and a frictionless workflow, rather than a fully customized, bespoke design.

Decisions

This context guided our evaluation of various UI libraries. A key stakeholder was our UX/UI designer, who had several firm requirements. Chief among them was the availability of a comprehensive Figma kit, either official or community-driven. This was a critical prerequisite, as it would establish a single source of truth, bridge the gap between design and engineering, and spare us the significant effort of building a design system from scratch. The ability for the designer to customize components to align with our brand identity was equally important. Moreover, native support for a dark theme and a foundational commitment to accessibility were considered essential features.

From a technical standpoint, my criteria as the front-end developer were just as stringent. The ideal library had to be lightweight to ensure optimal performance, architected to minimize bundle size, and supported by an active and helpful community. Our evaluation process led us to three final contenders: Material UI (MUI), Ant Design, and Mantine.

The Great UI Library Debate

Our analysis commenced with Material UI (MUI). As one of the most established libraries in the ecosystem, its feature-rich nature and our team's prior experience with it were significant advantages. However, a critical issue emerged during our assessment of its Figma integration. The free version of the official MUI Figma kit proved to be highly restrictive, permitting customization for only a limited set of components. This limitation would have compelled our designer to detach instances from the main library to apply custom styles, thereby severing the connection to the design system and reintroducing the very inconsistencies we aimed to eliminate. This effectively nullified the benefit of using a unified system.

Subsequently, we evaluated Ant Design. While it is an undeniably powerful and extensive library, previous experience raised concerns regarding its suitability for our project. The documentation had, at times, proven difficult to navigate due to language barriers, with some sections available only in Chinese. This posed a potential risk to development velocity, especially during troubleshooting. Furthermore, we assessed that its commitment to accessibility, although improving, was not as deeply integrated into its core architecture compared to more contemporary alternatives.

Why Mantine Came Out on Top

Ultimately, we selected Mantine, and its performance throughout the project affirmed it was the correct decision. It not only met our initial requirements but exceeded them in several crucial areas.

1. Seamless Integration Between Design and Development

Mantine's most compelling advantage was its exceptional support for Figma. We discovered a robust and meticulously maintained community Figma kit that precisely mirrored the library's React components. This synergy established a seamless workflow, enabling our designer to construct layouts using variants and properties that directly corresponded to the props used in the codebase. This one-to-one mapping eliminated ambiguity, guaranteed high-fidelity implementation, and resulted in the most efficient design-to-code handoff process I have encountered.

2. Performance First: Lightweight and Optimized

A developer must always remain mindful of the application's final bundle size, and Mantine is architected with performance as a primary concern. While the library is impressively lightweight, its most significant performance feature is its inherent support for tree-shaking. This is a dead-code elimination technique employed by modern JavaScript bundlers, such as Vite or Webpack. The bundler analyzes the import statements throughout the application and excludes any code from the final bundle that has not been explicitly imported. Because Mantine is designed to be tree-shakeable, an import statement like import { Button, Paper } from '@mantine/core' ensures that only the code for the Button and Paper components is included in the production build. All other unused components are effectively pruned, leading to a substantially smaller bundle size and, consequently, a faster application for the end-user.

3. A Truly Modular and Flexible Ecosystem

Unlike monolithic libraries, Mantine is designed as a collection of independent packages. This modular architecture is a key strength, as it allows developers to install only the functionality they require. Our project began with @mantine/core for the fundamental components. As the application's requirements evolved, we selectively integrated additional packages:

@mantine/hooks for a fantastic collection of utility hooks.
@mantine/notifications for a simple and elegant notification system.
@mantine/modals to manage our dialogs and confirmation popups.
@mantine/form for robust and easy-to-use form state management.

This à la carte approach ensures the project is not burdened with the code for unused features, such as a rich text editor or a date picker, thereby maintaining a lean and manageable dependency tree.

4. More Than Just Components: A Powerful Hooks Library

The @mantine/hooks package warrants special mention. It provides a comprehensive suite of well-tested, production-ready hooks that address common challenges in front-end development. Utilities such as useDebouncedValue for optimizing search inputs, useClickOutside for managing the dismissal of overlay elements, and useMediaQuery for implementing responsive logic saved us a considerable amount of development time. This demonstrates that Mantine's value proposition extends beyond mere UI elements to encompass a genuine enhancement of the overall developer experience.

5. Accessibility and Dark Mode as Core Principles

Mantine treats accessibility as a fundamental principle, not a secondary consideration. Its components are engineered to adhere to WAI-ARIA standards, guaranteeing full keyboard navigability and correct interpretation by screen readers. Focus management is handled intelligently out of the box; for example, components like modals and menus correctly trap focus to guide the user. This foundational commitment to accessibility provided a significant advantage in our efforts to build an inclusive application.

Similarly, the implementation of a dark theme was remarkably straightforward. By simply wrapping our application in the MantineProvider, we could toggle the color scheme via a single prop. Every component then automatically adapted to a polished and consistent dark theme, obviating the need for extensive custom CSS.

5. Flexible and Powerful Styling

Mantine achieves an excellent balance in its styling methodology. By default, components utilize CSS Modules, which inherently scope class names to prevent collisions and ensure style encapsulation—a crucial feature for large-scale applications. In addition to this, Mantine offers theme-aware style props (e.g., p, m, bg, c) for rapid, inline modifications that reference the project's central theme. For instance, p="md" will apply the precise padding value designated as md in the theme configuration. This hybrid system provides the best of both worlds: the robustness and maintainability of CSS Modules for foundational styling, combined with the convenience of utility props for layout adjustments and minor stylistic changes. The theming system itself is highly intuitive, simplifying the process of defining global brand colors, typography, and spacing.

7. Rapid Prototyping with Mantine UI

While @mantine/core provides the building blocks, Mantine UI provides the finished structures. This is a collection of over 100 responsive components and page sections—like headers, hero sections, feature grids, and footers—that are ready to be dropped into an application. We used these extensively to quickly build out standard pages, which allowed us to focus our energy on the more unique, data-driven features of our application.

8. A Thriving Ecosystem of Extensions

Beyond the official packages, Mantine's power is amplified by a thriving ecosystem of community-driven extensions. The Mantine Extensions Hub serves as a central showcase for these third-party libraries, which provide specialized functionality that can be seamlessly integrated into any Mantine project. This allows developers to extend the core library's capabilities without having to build complex components from scratch. During our project, we explored several extensions that solved specific needs, including powerful data tables, onboarding tours for user guidance, resizable split panes for complex layouts, and feature-rich scheduling components. This vibrant community and its contributions demonstrate the library's flexibility and underscore its status as a comprehensive and adaptable solution.

Final Thoughts

In the highly competitive landscape of UI libraries, Mantine achieves a remarkable and uncommon balance. It offers the development velocity and convenience expected of a mature component library, but without compromising on performance, flexibility, or the overall developer experience. For our team, it successfully bridged the critical gap between design and engineering, satisfied all our technical prerequisites, and ultimately enabled us to deliver a superior product more efficiently. It has since become our default selection for new React projects, and I recommend it without reservation.

React Keycloak Integration: Secure Auth for Existing Backend

Salva Torrubia — Thu, 08 May 2025 12:54:09 +0000

In a recent greenfield project, I inherited a Keycloak instance already deployed and configured for the back-end services. My next challenge was to research and apply best practices for securely integrating that same Keycloak realm into the React front-end. The goal was to enable seamless, PKCE-based single-page-app authentication, preserve silent SSO, and ensure the .NET API accepts tokens issued to the front-end—without exposing secrets in the browser.

Why Two Clients

I already have a confidential Keycloak client (“api-service”) protecting your .NET API. To integrate my React front end securely:

Create a second, public client (spa-app) in the same realm, using Authorization Code Flow + PKCE.

Add a Client Scope + Audience Mapper so tokens for spa-app also include the api-service audience claim.

Wrap your React app in a single ReactKeycloakProvider, avoiding React 18 StrictMode’s double-init() issue.

Provide minimal login, logout, and user-info examples using @react-keycloak/web.

Include a tiny silent-check-sso.html for background SSO checks.

This pattern keeps your secrets on the server, enforces least-privilege via audiences, and delivers seamless silent SSO for your SPA.

Create the Public SPA Client in Keycloak

Clients → Create

Client ID: spa-app
Protocol: openid-connect

Settings

Access Type: Public (no client secret)
Standard Flow Enabled: ON (Authorization Code Flow)
Implicit Flow Enabled: OFF
Direct Access Grants Enabled: OFF

Advanced
Proof Key for Code Exchange Code Challenge Method: S256 (enables PKCE)

Login Settings

Root URL / Home URL:

http://localhost:3000
https://<your-app>.azurestaticapps.net

Valid Redirect URIs:

http://localhost:3000/*
https://<your-app>.azurestaticapps.net/*

Web Origins:

http://localhost:3000
https://<your-app>.azurestaticapps.net

Save.

Share the API Audience via Client Scope

By default, tokens for spa-app carry only "aud": ["spa-app"], but your API expects "aud": "api-service". Add it without code changes:

Client Scopes → Create

Name: api-audience

Protocol: openid-connect

Include in token scope: OFF

api-audience → Mappers → Create

Name: api-audience-mapper

Mapper Type: Audience

Included Client Audience: api-service

Token Claim Name: aud

Add to access token: on

Add to ID token: off

Clients → spa-app → Client Scopes → Default:
add api-audience.

React Integration: Provider + Silent SSO

Install the Keycloak Adapter
First, install the official Keycloak JavaScript adapter and React bindings, which provide the low-level keycloak-js client and a convenient wrapper:
npm install keycloak-js @react-keycloak/web

Configure keycloak.ts
Create a dedicated module to initialize a single Keycloak instance (avoiding double-init errors) and export your initOptions for Authorization Code Flow + PKCE with silent SSO:

import Keycloak from 'keycloak-js';

// Instantiate Keycloak once, pointing at your realm and SPA client
export const keycloak = new Keycloak({
  url: import.meta.env.VITE_KEYCLOAK_URL,
  realm: import.meta.env.VITE_KEYCLOAK_REALM,
  clientId: 'spa-app',
});

export const initOptions = {
  onLoad: 'check-sso',                      // perform a silent session 
  flow: 'standard',                         // use the OIDC Authorization Code Flow
  pkceMethod: 'S256',                       // enforce PKCE for extra SPA security
  silentCheckSsoRedirectUri: `${window.location.origin}/silent-check-sso.html`,
  checkLoginIframe: true,                   // enable the hidden iframe for silent token refresh
  checkLoginIframeInterval: 30,             // polling interval in seconds
  enableLogging: true,                      // turn on adapter debug logging
};

Create the Silent-SSO Callback Page
Keycloak’s JavaScript adapter will load this page inside a hidden iframe to perform a background session check. When it finishes, it uses postMessage to notify the parent window, resolving the silent SSO promise. Place this file at public/silent-check-sso.html:

<!doctype html>
<html>
  <body>
    <script>
      // Notify the parent window with the full URL (including tokens in the fragment)
      parent.postMessage(location.href, location.origin);
    </script>
  </body>
</html>

This minimal snippet is exactly what the official Keycloak docs recommend for the silent-SSO iframe callback.

Provider Setup (Avoid React 18 Double-Init)
React 18’s StrictMode mounts and unmounts class-based components twice in development, which would trigger keycloak.init() two times and break with “A ‘Keycloak’ instance can only be initialized once.” To prevent this, render your outside of :

import ReactDOM from 'react-dom/client';
import { ReactKeycloakProvider } from '@react-keycloak/web';
import App from './App';
import { keycloak, initOptions } from './keycloak';

ReactDOM.createRoot(document.getElementById('root')!).render(
  // Note: no <React.StrictMode> wrapper here
  <ReactKeycloakProvider authClient={keycloak} initOptions={initOptions}>
    <App />
  </ReactKeycloakProvider>
);

By removing the StrictMode wrapper around the provider, you ensure keycloak.init() is called exactly once.

Simple Login / Logout / User-Info Example
Use the useKeycloak hook inside any component to trigger login, logout, and display basic user info:

import React from 'react';
import { useKeycloak } from '@react-keycloak/web';

export default function UserMenu() {
  const { keycloak, initialized } = useKeycloak();

  // Wait until Keycloak finishes initialization (including silent SSO)
  if (!initialized) {
    return <div>Loading authentication…</div>;
  }

  // If not authenticated yet, show a Login button
  if (!keycloak.authenticated) {
    return <button onClick={() => keycloak.login()}>Login</button>;
  }

  // Once authenticated, extract user info from the parsed token
  const username = keycloak.tokenParsed?.preferred_username;
  const roles    = keycloak.tokenParsed?.realm_access?.roles || [];

  return (
    <div>
      <span>Hello, {username}</span>
      <span>Roles: {roles.join(', ')}</span>
      <button onClick={() => keycloak.logout()}>Logout</button>
    </div>
  );
}

Summary

With this configuration your React SPA and .NET API remain securely isolated yet seamlessly integrated under the same Keycloak realm by using a public client for the front end and a confidential client for the back end, leveraging PKCE and silent SSO for a friction-free user experience, and sharing the API’s audience through a simple client scope mapper so no server code changes are required, all while avoiding double initialization in React 18 by placing the Keycloak provider outside StrictMode and keeping your secrets safely on the server.

Speed Up Your React App: Tools, Tips and Architecture Tricks

Salva Torrubia — Mon, 05 May 2025 10:38:38 +0000

Building fast, responsive React apps isn’t magic—it’s the result of understanding how React works under the hood and applying best practices. In this post, we’ll explore:

Virtual DOM and selective updates
Efficient list rendering and virtualization
Memoization techniques with hooks and HOCs
Code-splitting and lazy loading
Architectural best practices (composition, SOLID, DRY, KISS)
Measuring and monitoring performance

The Virtual DOM & Selective Updates

What is the Virtual DOM?
React maintains a lightweight, in-memory representation of the real DOM. This “Virtual DOM” lets React compute exactly what changed without touching the real browser DOM on every render—because direct DOM manipulations are expensive.

Diffing Algorithm 🔄
When state or props change, React generates a new Virtual DOM tree.
It then diffs this tree against the previous one to identify minimal updates.

Selective Updates
Only the changed nodes are patched in the real DOM, avoiding wholesale re-renders and boosting performance.

// Conceptual illustration—React does something like:
const prevVDOM = renderApp(props);
const nextVDOM = renderApp(newProps);
const patches = diff(prevVDOM, nextVDOM);
applyPatchesToDOM(patches);

Efficient Rendering of Lists

Keys 🔑
Avoid using array indices as keys—unstable keys lead to unnecessary re-renders and bugs. Instead, use unique, stable IDs:

// ❌ Bad: key={index}
<ul>
  {items.map((item, index) => (
    <li key={index}>{item.name}</li>
  ))}
</ul>

// ✅ Good: key={item.id}
<ul>
  {items.map(item => (
    <li key={item.id}>{item.name}</li>
  ))}
</ul>

Virtualization for Large Lists

Rendering 500+ rows at once kills performance. Virtualization renders only the visible portion of a list.Tools like react-windows can be very usefull:

import { FixedSizeList as List } from 'react-window';

function VirtualizedList({ items }) {
  return (
    <List
      height={500}
      itemCount={items.length}
      itemSize={35}
      width="100%"
    >
      {({ index, style }) => (
        <div style={style}>
          {items[index].name}
        </div>
      )}
    </List>
  );
}

💡 If you need global search across 500+ items, consider a local search filter before rendering the virtualized list.

Memoization & Hooks for Speed 🧠

React.memo for Components
Wrap pure functional components to skip renders when props don’t change.

useCallback for Functions
Cache callback references so children relying on them don’t re-render:

function ProductPage({ productId, referrer, theme }) {
  const handleSubmit = useCallback((orderDetails) => {
    post('/product/' + productId + '/buy', {
      referrer,
      orderDetails,
    });
  }, [productId, referrer]); 

  return (
    <div className={theme}>
      <ShippingForm onSubmit={handleSubmit} />
    </div>
  );
}

💡 If the function has no dependencies, you can define it outside the component to guarantee stability.

useMemo for Expensive Calculations
Avoid recalculating values on every render:

export default function TodoList({ todos, tab, theme }) {
  const visibleTodos = useMemo(
    () => filterTodos(todos, tab),
    [todos, tab]
  );
  return (
    <div className={theme}>

      <List items={visibleTodos} />
    </div>
  );
}

💡 Prefer useMemo over juggling useState + useEffect for pure calculations.

Code-Splitting & Lazy Loading with Suspense ⏳

Split your bundle into chunks to load routes or heavy components on demand and displays a fallback UI while waiting for code or data.

Use for Heavy/Non-Critical Components:
Routes (e.g., /settings, /admin).
Modals, tabs, or infrequently used features.

Avoid for Critical Components:
Components needed immediately (e.g., Navbar, Footer).
Small components (overhead may outweigh benefits).

Combine with Routing:
Most frameworks (TansTack Router, React Router, Next.js) support lazy-loaded routes.

import React, { lazy, Suspense } from 'react';

const Settings = lazy(() => import('./Settings'));

function App() {
  return (
    <Suspense fallback={<Spinner />}>
      <Settings />
    </Suspense>
  );
}

Architectural Best Practices 🏗️

A solid React architecture improves performance, maintainability, and scalability. Principles like SOLID, DRY, and KISS guide us to avoid duplication, simplify components, and streamline collaboration in teams.

Composition vs. Inheritance
React encourages composition over inheritance. Instead of complex component hierarchies, build UIs by assembling small, reusable pieces via props (especially children).

// ❌ Reusable via Props
function Card({ title, subtitle}) {
  return (
    <div className="card">
      <h3>{title}</h3>
      <h4>{subtitle}</h4>
    </div>
  );
}

// ✅ Usage: Compose content
function Card({children}) {
  return (
      <div className="card">
        {children}
     </div>
  );
}

SOLID: Focus on the "S"
The SOLID principles are guidelines for writing maintainable and scalable code. The "S" (Single Responsibility Principle - SRP) states:

"A component, class, or function should have a single responsibility—i.e., only one reason to change."

❌ // Combines file handling, order history, and SQL logic
<UserDatabase />

✅
<DevFileSection />      // Handles file metadata/configuration
<OrderHistory />        // Manages order history display
<GetFileColumnized />   // Formats data into columns (e.g., SQL results)

DRY
Extract repeated logic into custom hooks (e.g., useFetch, useForm, useEmail):

// ✅ Reusable hook
function useEmail(initialValue = '') {
  const [email, setEmail] = useState(initialValue);
  const isValid = useMemo(() => 
    /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email), 
    [email] // Recompute only when email changes
  );

  return { email, setEmail, isValid };
}

// Clean components using the hook
function FormA() {
  const { email, setEmail, isValid } = useEmail();

  return (
    <input 
      type="email" 
      value={email} 
      onChange={(e) => setEmail(e.target.value)} 
    />
  );
}

function FormB() {
  const { email, setEmail, isValid } = useEmail();

  return (
    <input 
      type="email" 
      value={email} 
      onChange={(e) => setEmail(e.target.value)} 
    />
  );
}

KISS
Keep components focused and code paths clear—complexity kills performance:

// ❌ Over-engineered button with redundant logic
function FancyButton({ onClick, children }) {
  const [hovered, setHovered] = useState(false);

  return (
    <button 
      onClick={onClick}
      onMouseEnter={() => setHovered(true)}
      onMouseLeave={() => setHovered(false)}
      style={{
        background: hovered ? "blue" : "navy",
        padding: "10px 25px",
        borderRadius: "8px",
        color: "white",
        transition: "all 0.3s"
      }}
    >
      {children}
    </button>
  );
}

// ✅ Simple button with external CSS (KISS in action!)
function SimpleButton({ onClick, children }) {
  return (
    <button 
      onClick={onClick}
      className="primary-btn"  // Styles defined in CSS
    >
      {children}
    </button>
  );
}

State Management

Avoid excessive prop drilling. Use Context API, Zustand, Redux, or URL-based state (React Router’s search params) where appropriate.

Caching
Minimize redundant fetches with tools like TanStack Query, which also handles background updates and cache invalidation gracefully.

Monitoring Performance 📊

React Developer Tools
Inspect component render times and “why did this render?”
Profile CPU usage and identify bottlenecks.

Lighthouse
Built into Chrome DevTools (Audits → Performance, Accessibility, SEO).
Provides actionable suggestions (e.g., “Reduce unused JavaScript”).

Bundle Analyzer
Visualize your bundle’s modules with webpack-bundle-analyzer.
Pinpoint large dependencies you can lazy-load or replace with lighter alternatives.

Conclusion ⚡

Optimizing React performance is a combination of understanding its internals (Virtual DOM, diffing), applying targeted techniques (memoization, virtualization, code splitting), and maintaining healthy architecture (composition, SOLID, DRY). Finally, always measure before and after changes—tools like React Profiler and Lighthouse will guide you toward the highest-impact wins.

Testing TanStack Router

Salva Torrubia — Fri, 02 May 2025 22:11:44 +0000

For my new project I decided to jump from React Router 7 to TanStack Router 🔥, especially since I’d been loving TanStack Query and figured the synergy between the two would be really powerful. But when it came time to write tests, I couldn’t find much documentation on wiring up TanStack Router in React Testing Library. That’s why I built this tiny helper 🛠️

Its a file-based implementation

Full Code

test-utils.ts

import React from 'react'
import {
  Outlet,
  RouterProvider,
  createMemoryHistory,
  createRootRoute,
  createRoute,
  createRouter,
} from '@tanstack/react-router'
import { render, screen } from '@testing-library/react'
import { QueryClientProvider, QueryClient } from '@tanstack/react-query'

type RenderOptions = {
  pathPattern: string
  initialEntry?: string
  queryClient?: QueryClient
}

/**
 * Renders a component under:
 *  - a minimal TanStack Router instance (memory history),
 *  - optionally wrapped in a QueryClientProvider.
 *
 * If `initialEntry` is omitted, it defaults to `pathPattern`.
 *
 * @param Component  The React component to mount.
 * @param opts       Render options.
 * @returns { router, renderResult }
 */

export async function renderWithProviders(
  Component: React.ComponentType,
  { pathPattern, initialEntry = pathPattern, queryClient }: RenderOptions,
) {
  // Root route with minimal Outlet for rendering child routes
  const rootRoute = createRootRoute({
    component: () => (
      <>
        <div data-testid="root-layout"></div>
        <Outlet />
      </>
    ),
  })

  // Index route so '/' always matches
  const indexRoute = createRoute({
    getParentRoute: () => rootRoute,
    path: '/',
    component: () => <div>Index</div>,
  })

  // Test route mounting your Component at the dynamic path
  const testRoute = createRoute({
    getParentRoute: () => rootRoute,
    path: pathPattern,
    component: () => <Component />,
  })

  // Create the router instance with memory history
  const router = createRouter({
    routeTree: rootRoute.addChildren([indexRoute, testRoute]),
    history: createMemoryHistory({ initialEntries: [initialEntry] }),
    defaultPendingMinMs: 0,
  })

  // Build the render tree and add QueryClientProvider if provided
  let tree = <RouterProvider router={router} />
  if (queryClient) {
    tree = (
      <QueryClientProvider client={queryClient}>{tree}</QueryClientProvider>
    )
  }

  // Render and wait for the route to resolve and the component to mount
  const renderResult = render(tree)
  await screen.findByTestId('root-layout')

  return { router, renderResult }
}

Create a Minimal Root Route

const rootRoute = createRootRoute({
  component: () => (
    <>
      <div data-testid="root-layout" />
      <Outlet />
    </>
  ),
})

Renders a <div data-testid="root-layout"/> plus an <Outlet/> so we can wait for router hydration.

Add an Index Route (/)

const indexRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: '/',
  component: () => <div>Index</div>,
})

Simple placeholder for index.
Ensures that navigating to "/" always resolves without errors.

Add Your Test Route (path)

const testRoute = createRoute({
  getParentRoute: () => rootRoute,
  path: pathPattern,
  component: () => <Component />,
})

pathPattern may include dynamic segments (e.g. "/users/$userId").
The router uses this pattern to know where to “mount” the component under test.

Instantiate the Router

const router = createRouter({
  routeTree: rootRoute.addChildren([indexRoute, testRoute]),
  history: createMemoryHistory({ initialEntries: [initialEntry] }),
  defaultPendingMinMs: 0,
})

routeTree: Combines rootRoute with its children (indexRoute, testRoute).
createMemoryHistory: Starts the router at the desired path.
initialEntries: [initialEntry]: starts the router, keeping route definition (pathPattern) separate from the test URL (initialEntry).
defaultPendingMinMs: 0: Speeds up transition resolution during testing by removing any artificial delay.

Build the Render Tree

let tree = <RouterProvider router={router}/>
if (queryClient)
  tree = <QueryClientProvider client={queryClient}>{tree}</QueryClientProvider>

<RouterProvider>: Supplies the router context to your components.
Optional Query Client: If you passed queryClient, wrap the router in so your components can use React Query hooks.

Render and Await Hydration

const renderResult = render(tree)
await screen.findByTestId('root-layout')

render(tree): Uses React Testing Library to render the component tree.
findByTestId('root-layout'): Waits until the router’s root layout is mounted, guaranteeing that navigation and route resolution are complete before assertions.

Return Utilities for Tests

return { router, renderResult }

router: Access the router instance in your test for navigation, state inspection, etc.
renderResult: Provides all the usual Testing Library query utilities and can be usefull for testing accesibility

Example Usage with dynamic route

import { renderWithProviders } from './test-utils'
import { QueryClient } from '@tanstack/react-query'
import User from './User'
import { screen } from '@testing-library/react'
import { usersQueryOptions } from './queries/users/users'

// Optional
import { axe, toHaveNoViolations } from 'jest-axe'

type UserData = {
  id: string
  name: string
}

const testUserId = '1'
const pathPattern = '/users/$userId'
const initialEntry = `/users/${testUserId}`

const mockUser: UserData = { id: testUserId, name: 'Alice' }

test('it shows the user name', async () => {
  const queryClient = new QueryClient()

  // Prime the React-Query cache
  queryClient.setQueryData(usersQueryOptions.queryKey, mockUser)

  // Render
  const { renderResult } = await renderWithProviders(User, {
    pathPattern,
    initialEntry,
    queryClient,
  })

  // Assert that the user name is displayed
  expect(screen.getByText(mockUser.name)).toBeInTheDocument()

  // Optional: Accessibility audit
  const results = await axe(renderResult.container)
  expect(results).toHaveNoViolations()
})

In Summary

Thanks for reading! 🎉 I hope this helper makes your TanStack Router tests a breeze. If you have ideas, questions, or improvements, drop a comment below—let’s keep learning together. Happy testing! 🚀