DEV Community: Terry W

Fixing Playwright build errors on Render when browsers are missing

Terry W — Sat, 23 Aug 2025 23:12:54 +0000

TL;DR

If Playwright runs locally but fails on Render with "executable does not exist", install Chromium during build and set PLAYWRIGHT_BROWSERS_PATH to a folder inside the project so the browser binary is included in the deploy artifact.

Background

I am using Playwright on my API to render email templates for my app, Snap Template. It works fine on my computer (insert meme here), but after deploying to Render the export feature failed with Playwright complaining the Chromium executable did not exist. This post explains how I diagnosed the issue and the fix I used so Playwright can find the browser binary in the deployed service.

Root cause

Locally I had previously run npx playwright install, so the browser binaries existed in my local cache.
The runtime container therefore did not have the Chromium binary at the expected path and Playwright failed to launch it.

The working fix

Add a postinstall script to package.json that installs Chromium only: "postinstall": "npx playwright install chromium"
Use this build command on Render so the postinstall runs during build: npm install && npm run postinstall && npm run build
Add this environment variable in Render, pointing to the path for the playwright cache inside the built project: PLAYWRIGHT_BROWSERS_PATH=/opt/render/project/.cache/playwright

Why this works

postinstall downloads Chromium into the project when the build runs.
PLAYWRIGHT_BROWSERS_PATH forces Playwright to put and look for the browser binaries in a folder that is part of the deployed artifact. The runtime process finds the executable and Playwright launches correctly.

Extra Checks and Good Practices

Monitor disk usage. Playwright browser files are large. Keep an eye on Render storage and logs.
Consider playwright-chromium if you want a smaller install that targets Chromium only.
If you need guaranteed system libraries and reproducible builds, use a Playwright-ready Docker image such as mcr.microsoft.com/playwright:latest. That image includes OS deps and browser binaries.
Add a tiny startup debug log for chromium.executablePath() to aid future diagnostics.
Do the Playwright install during build only. Installing at runtime increases cold start time.

TLDR checklist

Did postinstall run during build? Check Render build logs.
Is PLAYWRIGHT_BROWSERS_PATH pointing inside the project? If not, set it.

Closing notes

If you deploy Playwright on a host that separates build and runtime you will likely need to install the browsers into the deploy artifact. Setting the Playwright browsers path to a project folder in the environment variables and running npx playwright install chromium during build solved this for me on Render.

If this helped you do the Playw-right thing and get your service working, or you have a cleaner approach, drop a comment. I’m running SnapTemplate and would love to hear how you use Playwright in your app.

Fixing Vite HMR Issues in React by Splitting Your Auth Context

Terry W — Tue, 20 May 2025 18:32:45 +0000

Have you ever updated a file in your React + Vite project only to see full page reloads instead of fast refresh? 😩

That happened to me when I built an authentication context and exported both the provider and a custom hook (useAuth) from the same .tsx file. Turns out, that’s a no-go if you want smooth Hot Module Reloading (HMR) with Vite.

Here’s what was happening and how a small refactor completely fixed it.

The Problem

I had a single AuthContext.tsx file that looked something like this:

import {
  createContext,
  useContext,
  useState,
  useEffect,
  ReactNode,
} from "react";
import authApi from "@/api/auth-api";
import { User } from "@/types/users";
import { AuthContextType, AuthResponse } from "@/types/auth";
const AuthContext = createContext<AuthContextType | undefined>(undefined);

export function AuthProvider({ children }: { children: ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);
...
  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

export function useAuth() {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error("useAuth must be used within an AuthProvider");
  }
  return context;
}

Vite kept logging:

vite hmr invalidate /src/contexts/AuthContext.tsx Could not Fast Refresh ("useAuth" export is incompatible). Learn more at https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-react#consistent-components-exports

Basically, Vite's React plugin only supports Fast Refresh when your .tsx file exports components only (i.e., PascalCase components). If you export anything else — like a custom hook — it invalidates the module and reloads the whole page.

The Fix

The cleanest solution: split your hook into a separate .ts file.

AuthContext.ts

import { createContext, useContext } from "react";
import type { AuthContextType } from "@/types/auth";

export const AuthContext = createContext<AuthContextType | undefined>(
  undefined
);

export function useAuth() {
  const ctx = useContext(AuthContext);
  if (!ctx) throw new Error("useAuth must be used within <AuthProvider>");
  return ctx;
}

AuthProvider.tsx

import { useState, useEffect, ReactNode } from "react";
import authApi from "@/api/auth-api";
import { User } from "@/types/users";
import { AuthResponse } from "@/types/auth";
import { AuthContext } from "@/contexts/AuthContext";

export function AuthProvider({ children }: { children: ReactNode }) {
  // ... state + auth methods here ...

  return <AuthContext.Provider value={value}>{children}</AuthContext.Provider>;
}

Takeaway

If you're using Vite with React and notice weird HMR behaviour, check your exports. Keep .tsx files component-only, and move hooks or utilities into .ts files to avoid these issues.

Have you run into other quirky Vite or React dev issues? Got any lightweight performance tricks? Drop them in the comments, and let others know what’s worked for you! 👇

The Art of API Documentation: A Comprehensive Guide

Terry W — Thu, 08 May 2025 00:38:25 +0000

Introduction
What Is an API?
Why Good Documentation Matters
Essential Parts of API Documentation
Advanced Documentation Tips
Best Practices I’ve Learned
Conclusion

Introduction

As software development has evolved, APIs (Application Programming Interfaces) connect different systems and services. I’ve found that even the most powerful APIs require clear documentation to be truly useful. This article shares how I create clear API documentation. By the end of this post, you’ll have a bulletproof template for writing documentation that even your sleepiest teammate can follow.

What is an API?

An API is a set of rules that allows different applications to communicate. It acts as a contract between the data provider (the server) and the data consumer (the client).

APIs help developers:

Access features from other systems
Retrieve or modify data in external systems
Integrate multiple services seamlessly
Build on existing platforms without knowing their internals

In my News API project, users can get information about users, articles, comments, and topics through simple endpoints without needing to understand the database structure.

Why Good Documentation Matters

Good documentation is your friendly tour guide; no one likes getting lost in a maze of endpoints.

For people using your API:

Easier to learn: Developers understand your API quickly
Faster to implement: Clear examples help speed up integration
Fewer questions: Good documentation answers common questions
Better experience: Developers can focus on building rather than figuring out your API

For people providing the API:

More users: Well documented APIs attract more developers
Consistency: Documentation helps your team stay on the same page
Less support work: Less time answering basic questions
Better design: Writing documentation often shows design problems

Essential Parts of API Documentation

Here are the key parts of good API documentation:

1. Introduction and Overview

Start with a simple description of what your API does and why it exists:

API documentation for the NC News API

2. Base URL

Clearly show the base URL for all requests:

"base_url": "/api"

3. List of Endpoints

Organise endpoints in logical groups. For my News API, I grouped them as:

API Information
Users
Topics
Articles
Comments

4. Detailed Endpoint Information

For each endpoint, include:

a. HTTP Method and Path

Show the method (GET, POST, PUT, PATCH, DELETE) and full path.

b. Description

Briefly explain what the endpoint does.

Example:

"GET /api/users": {
  "description": "Returns an array of users with the username, name and avatar url"
}

c. Request Parameters

Explain all parameters needed in the request.

d. Response Format

Show what successful responses look like with examples.

Example:

"exampleResponse": [
  {
    "username": "butter_bridge",
    "name": "jonny",
    "avatar_url": "https://www.healthytherapies.com/wp-content/uploads/2016/06/Lime3.jpg"
  }
]

e. Error Handling

List possible error codes and when they happen.

Example:

"errors": [
  {
    "status": 404,
    "msg": "User does not exist"
  },
  {
    "status": 409,
    "msg": "Username already exists"
  }
]

f. Example Requests and Responses

Show sample requests and what responses they get.

Advanced Documentation Tips

Version Control for Documentation

As your API changes, keep documentation updated:

Use version numbers for your API
Document what changes between versions
Help users update when big changes happen

Using Markdown

Use Markdown to achieve:

Consistent formatting
Code highlighting
Easy updates
Works well with version control

Best Practices I've Learned

Through the development of my News API project, I’ve identified key principles that produce genuinely helpful documentation:

Balance Completeness with Clarity

Good documentation covers everything developers need to know without overwhelming them. For my News API, I created a consistent template for each endpoint that includes all essential information (method, path, parameters, responses) while keeping descriptions concise and focused. This structured approach helps users find exactly what they need quickly.

Show, Don't Just Tell

Documentation comes alive through examples. When I explain an endpoint like GET /api/articles, I include:

A sample request URL
What parameters affect the results
A complete response example showing the data structure
Common error scenarios

These real-world examples help developers visualise how to use the API and what to expect, saving them significant time during implementation.

Maintain and Evolve Your Documentation

Documentation that falls out of sync with your API quickly becomes useless or even harmful. I've made documentation updates part of my development workflow—whenever I change an endpoint, add a feature, or fix a bug that affects behaviour, I immediately update the relevant documentation. This ongoing maintenance ensures developers always have accurate information.

Additionally, I maintain consistent terminology throughout all documentation (using "articles" not "posts" in one section and "stories" in another), which prevents confusion and helps developers build a clear mental model of how the API works.

Bonus Tip - Quickly Grab Curl Requests

You can quickly get the curl requests made to APIs by opening developer tools, navigating to the network tab and right clicking on an API call, where you will have a copy option and a few choices:

Maintain a Changelog File:

Treat your APIs changelog like a first-class document by tracking each version, date, and summary of changes in a CHANGELOG.md at the repo root so consumers see it immediately, also using Semantic Versioning (MAJOR.MINOR.PATCH) and call it out in your changelog; this signals breaking vs. non-breaking changes at a glance.

Conclusion

Good API documentation shows professionalism. It's not an afterthought but a key part of API development. Following these guidelines will help you create documentation that makes your API more valuable and easier to use.

Remember: great documentation doesn't just explain how your API works, it helps developers imagine what they can build with it.

How To Implement Express Authentication with RBAC (Role Based Access Control)

Terry W — Thu, 24 Apr 2025 03:03:50 +0000

Introduction

Securing an API goes beyond simply checking credentials. You need to control who can do what, and ensure that tokens are both short-lived and revocable. In this article, we’ll cover:

Defining concise routes for registration, login, token refresh and logout, complete with input validation.
Building a controller to hash passwords, generate JSON Web Tokens (JWTs) and store refresh tokens in the database.
Writing middleware to verify JWTs, attach user information to requests and enforce role checks.
Applying those middleware functions to event-management routes so that only authorised users can create, update or delete events.

All snippets come from a single Express project; adapt them as needed for your setup.

1. Auth Routes with Validation

First, set up a dedicated router for authentication. We use express-validator to enforce input rules.

import { Router } from "express";
import { body, validationResult } from "express-validator";
import * as authController from "../controllers/auth-controller";

const authRouter = Router();

const validateRequest: RequestHandler = (
  req: Request,
  res: Response,
  next: NextFunction
): void => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    const formattedErrors = errors.array().map((error) => {
      if (error.type === "field") {
        return {
          field: error.path,
          message: error.msg,
        };
      }
      return {
        message: error.msg,
      };
    });

    res.status(400).json({
      status: "error",
      errors: formattedErrors,
    });
    return;
  }
  next();
};

const registerValidation = [
  body("username")
    .trim()
    .notEmpty()
    .withMessage("Username is required")
    .isLength({ min: 3, max: 30 })
    .withMessage("Username must be between 3 and 30 characters"),

  body("email")
    .trim()
    .notEmpty()
    .withMessage("Email is required")
    .isEmail()
    .withMessage("Must be a valid email address"),

  body("password")
    .trim()
    .notEmpty()
    .withMessage("Password is required")
    .isLength({ min: 6 })
    .withMessage("Password must be at least 6 characters"),

  // Optional fields for event organiser registration
  body("isEventOrganiser")
    .optional()
    .isBoolean()
    .withMessage("isEventOrganiser must be a boolean"),

  body("teamName")
    .optional()
    .custom((value, { req }) => {
      // Only require teamName if isEventOrganiser is true
      if (
        req.body.isEventOrganiser === true &&
        (!value || value.trim() === "")
      ) {
        throw new Error(
          "Team name is required when registering as an event organiser"
        );
      }
      return true;
    })
    // Only apply length validation if a non-empty value is provided
    .if((value) => value !== undefined && value !== null && value.trim() !== "")
    .isLength({ min: 3, max: 100 })
    .withMessage("Team name must be between 3 and 100 characters"),

  body("teamDescription").optional(),
];

authRouter.post("/register", registerValidation, validateRequest, register);

authRouter.post("/login", loginValidation, validateRequest, login);

authRouter.post(
  "/refresh-token",
  refreshTokenValidation,
  validateRequest,
  refreshTokenHandler
);

authRouter.post("/logout", logoutValidation, validateRequest, logout);

export default authRouter;

2. Auth Controller: Hashing, Tokens and Sessions

The auth controller handles:

Password hashing with bcryptjs
JWT creation (access and refresh tokens)
Storing refresh tokens in the database for later revocation

Token Generation

import jwt from "jsonwebtoken";
import bcrypt from "bcryptjs";

const JWT_SECRET = process.env.JWT_SECRET || "your-secret-key";
const JWT_REFRESH_SECRET =
  process.env.JWT_REFRESH_SECRET || "your-refresh-secret-key";
const ACCESS_TOKEN_EXPIRY = process.env.ACCESS_TOKEN_EXPIRY || "1d";
const REFRESH_TOKEN_EXPIRY = process.env.REFRESH_TOKEN_EXPIRY || "7d";

const generateTokens = async (user: User): Promise<AuthTokens> => {
  // Get staff role if exists
  const teamMember = await selectTeamMemberByUserId(user.id as number);

  // Create payload with user data and role
  const payload = {
    id: user.id,
    username: user.username,
    email: user.email,
    role: teamMember ? teamMember.role : null,
    // Add a timestamp to make tokens unique
    timestamp: Date.now(),
  };

  // Generate access token
  const accessToken = jwt.sign(
    payload,
    JWT_SECRET as jwt.Secret,
    {
      expiresIn: ACCESS_TOKEN_EXPIRY,
      algorithm: "HS256",
    } as jwt.SignOptions
  );

  // Generate refresh token
  const refreshToken = jwt.sign(
    {
      id: user.id,
      // Add randomness to make refresh tokens unique
      timestamp: Date.now(),
      nonce: Math.random().toString(36).substring(2),
    },
    JWT_REFRESH_SECRET as jwt.Secret,
    {
      expiresIn: REFRESH_TOKEN_EXPIRY,
      algorithm: "HS256",
    } as jwt.SignOptions
  );

  // Calculate expiry date for the refresh token
  let refreshExpirySeconds: number;
  if (typeof REFRESH_TOKEN_EXPIRY === "string") {
    // Parse string like "7d" to seconds
    if (REFRESH_TOKEN_EXPIRY.endsWith("d")) {
      // Convert days to seconds
      refreshExpirySeconds = parseInt(REFRESH_TOKEN_EXPIRY) * 24 * 60 * 60;
    } else if (REFRESH_TOKEN_EXPIRY.endsWith("h")) {
      // Convert hours to seconds
      refreshExpirySeconds = parseInt(REFRESH_TOKEN_EXPIRY) * 60 * 60;
    } else if (REFRESH_TOKEN_EXPIRY.endsWith("m")) {
      // Convert minutes to seconds
      refreshExpirySeconds = parseInt(REFRESH_TOKEN_EXPIRY) * 60;
    } else {
      // Assume seconds or use default
      refreshExpirySeconds = parseInt(REFRESH_TOKEN_EXPIRY) || 60 * 60 * 24 * 7; // Default 7 days
    }
  } else {
    refreshExpirySeconds = 60 * 60 * 24 * 7; // Default 7 days
  }

  const expiresAt = new Date();
  expiresAt.setSeconds(expiresAt.getSeconds() + refreshExpirySeconds);

  // Store refresh token in database
  await createSession(user.id as number, accessToken, refreshToken, expiresAt);

  return { accessToken, refreshToken };
};

Register and Login

On registration, check for an existing username or email, hash the password and then wrap the creation and optional team setup in a transaction:

export const register = async (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  try {
    const userData: RegistrationData = req.body;
    const {
      username,
      email,
      password,
      isEventOrganiser,
      teamName,
      teamDescription,
    } = userData;

    // Check if username or email already exists
    try {
      const existingUsername = await selectUserByUsername(username);
      // If we get here, the username exists
      return res.status(400).send({
        status: "error",
        msg: "Username already exists",
      });
    } catch (usernameError: any) {
      // If the error is a 404, it means the username doesn't exist - this is what we want
      if (usernameError.status !== 404) {
        return next(usernameError);
      }
    }

    try {
      const existingEmail = await selectUserByEmail(email);
      // If we get here, the email exists
      return res.status(400).send({
        status: "error",
        msg: "Email already exists",
      });
    } catch (emailError: any) {
      // If the error is a 404, it means the email doesn't exist - this is what we want
      if (emailError.status !== 404) {
        return next(emailError);
      }
    }

    // Hash password
    const saltRounds = 10;
    const passwordHash = await bcryptjs.hash(password, saltRounds);

    // Use transaction to ensure all operations succeed or fail together
    const result = await withTransaction(async () => {
      // Create user
      const newUser = await insertUser(username, email, passwordHash);
      const dbUser = newUser as User;

      let team: TeamResponse | null = null;
      let teamMember: ExtendedTeamMember | null = null;

      // If user wants to be an event organiser, create a team and add them as an event_manager
      if (isEventOrganiser) {
        if (!teamName) {
          throw {
            status: 400,
            msg: "Team name is required for event organisers",
          };
        }

        // Create team
        team = (await insertTeam(
          teamName,
          teamDescription
        )) as unknown as TeamResponse;

        // Add user as team event_manager
        teamMember = (await insertTeamMember(
          dbUser.id as number,
          team.id,
          "team_admin"
        )) as unknown as ExtendedTeamMember;
      }

      // Generate tokens
      const { accessToken, refreshToken } = await generateTokens(dbUser);

      // Sanitize user object for response (remove password_hash)
      const { password_hash, ...sanitizedUser } = dbUser;

      return { sanitizedUser, accessToken, refreshToken, team, teamMember };
    });

    res.status(201).send({
      status: "success",
      data: {
        user: {
          id: result.sanitizedUser.id,
          username: result.sanitizedUser.username,
          email: result.sanitizedUser.email,
        },
        accessToken: result.accessToken,
        refreshToken: result.refreshToken,
        ...(result.team && { team: result.team }),
        ...(result.teamMember && { teamMember: result.teamMember }),
      },
    });
  } catch (error) {
    next(error);
  }
};

The login endpoint verifies the password before issuing new tokens:

export const login = async (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  try {
    const { username, password } = req.body;

    // Find user by username
    try {
      const user = await selectUserByUsername(username);

      // Ensure user is not null before proceeding
      if (!user) {
        return res.status(401).send({
          status: "error",
          msg: "Username is incorrect",
        });
      }

      // Verify password
      const isPasswordValid = await bcryptjs.compare(
        password,
        user.password_hash
      );
      if (!isPasswordValid) {
        return res.status(401).send({
          status: "error",
          msg: "Password is incorrect",
        });
      }

      // The user object from database will have an ID
      const dbUser = user as User;

      // Generate tokens
      const { accessToken, refreshToken } = await generateTokens(dbUser);

      // Sanitize user object for response (remove password_hash)
      const { password_hash, ...sanitizedUser } = dbUser;

      res.status(200).send({
        status: "success",
        data: {
          user: {
            id: sanitizedUser.id,
            username: sanitizedUser.username,
            email: sanitizedUser.email,
          },
          accessToken,
          refreshToken,
        },
      });
    } catch (error: any) {
      // Handle the 404 user not found error
      if (error.status === 404) {
        return res.status(401).send({
          status: "error",
          msg: "Username is incorrect",
        });
      }
      next(error);
    }
  } catch (error) {
    next(error);
  }
};

Authentication & Authorisation Middleware

To protect routes we need middleware that:

Verifies the JWT and attaches user data to req.user
Checks that the user has the required role, if any

Verifying the token

export const authenticate = (
  req: Request,
  res: Response,
  next: NextFunction
) => {
  try {
    const authHeader = req.headers.authorization;

    if (!authHeader || !authHeader.startsWith("Bearer ")) {
      return res.status(401).json({
        status: "error",
        msg: "Unauthorized - No token provided",
      });
    }

    const token = authHeader.split(" ")[1];

    const decoded = jwt.verify(token, JWT_SECRET) as {
      id: number;
      username: string;
      email: string;
      role: string | null;
    };

    // Add user data to request
    req.user = decoded;

    next();
  } catch (error) {
    if (error instanceof Error && error.name === "TokenExpiredError") {
      // Get token anyway to provide expiry info
      const token = req.headers.authorization?.split(" ")[1] || "";

      return res.status(401).json({
        status: "error",
        msg: "Unauthorized - Token expired",
        details: "Please refresh your access token or log in again",
        tokenInfo: getTokenExpiryInfo(token),
      });
    }

    return res.status(401).json({
      status: "error",
      msg: "Unauthorized - Invalid token",
    });
  }
};

Checking Roles

export const authorize = (requiredRole: string) => {
  return async (req: Request, res: Response, next: NextFunction) => {
    try {
      if (!req.user) {
        return res.status(401).json({
          status: "error",
          msg: "Unauthorized - Authentication required",
        });
      }

      // If no specific role is required, just being authenticated is enough
      if (!requiredRole) {
        return next();
      }

      // If user doesn't have a role yet, deny access
      if (!req.user.role) {
        return res.status(403).json({
          status: "error",
          msg: "Forbidden - Insufficient permissions",
        });
      }

      // Check if user has the required role
      const teamMember = await selectTeamMemberByUserId(req.user.id);

      if (!teamMember || teamMember.role !== requiredRole) {
        return res.status(403).json({
          status: "error",
          msg: "Forbidden - Insufficient permissions",
        });
      }

      next();
    } catch (error) {
      next(error);
    }
  };
};

You can extend this pattern for team or event specific checks by querying your database within the middleware.

4. Applying Middleware to Routes

Finally, protect any route by adding the appropriate middleware. For example, in the events router I added the auth middleware to the route handlers:

// POST /api/events - Create a new event
// Requires team admin or event_manager role
eventsRouter.post(
  "/",
  authenticateHandler,
  eventValidation,
  validateRequest,
  createEventHandler
);

The validateRequest function I used:

const validateRequest = (
  req: Request,
  res: Response,
  next: NextFunction
): void => {
  const errors = validationResult(req);
  if (!errors.isEmpty()) {
    // Check if there's a specific time validation error
    const timeError = errors
      .array()
      .find(
        (error) =>
          error.type === "field" &&
          error.msg === "End time must be after start time"
      );

    if (timeError) {
      // For PATCH requests, return the error as a msg
      if (req.method === "PATCH") {
        res.status(400).json({
          status: "error",
          msg: "End time must be after start time",
        });
        return;
      }
      // For POST requests, format the error to match the test expectations
      else {
        res.status(400).json({
          status: "error",
          errors: [
            {
              message: "End time must be after start time",
            },
          ],
        });
        return;
      }
    }

    // Handle other validation errors
    const formattedErrors = errors.array().map((error) => {
      if (error.type === "field") {
        return {
          field: error.path,
          message: error.msg,
        };
      }
      return {
        message: error.msg,
      };
    });

    res.status(400).json({
      status: "error",
      errors: formattedErrors,
    });
    return;
  }
  next();
};

Here:

authenticateHandler ensures users ID and JWT is valid
eventUpdateValidation and validateRequest handle the input validation
authorizeEventAction middleware is part of the updateEventHandler logic.

Conclusion

With a central token generation function and a handful of middleware routines, you can:

Confirm every request originates from a known user
Grant or deny access by a role
Refresh and revoke tokens through a session table

If you found this guide helpful, please give it a ❤️ and leave a comment below – I’d love to hear your feedback and any questions you have. And if you’d like hands-on help securing your API or building out your authentication workflows, feel free to message me on LinkedIn

State of Auth Made Simple

Terry W — Tue, 18 Feb 2025 14:12:52 +0000

Have you ever struggled to maintain persistent user data across your app, whether for authentication or other contexts? If so, you're not alone! In this post, I'll share my current approach to tackling this challenge in Next.js or Vite apps.

User authentication is a cornerstone of modern web applications, and managing it efficiently can significantly improve both security and developer experience. I’ll walk you through how I use React Context with Firebase to handle authentication, protect routes, and manage user profiles without unnecessary complexity.

Whether you're just starting out or already experienced, these techniques will help you build a robust and scalable authentication system. Here's how to implement it, step by step.

Setting Up the AuthContext

At the core of our authentication system is the AuthContext. This React Context centralises user authentication logic, ensuring every component has seamless access to the current user state without prop drilling.

Prerequisites

Before diving into the implementation, ensure you have:
✅ A Firebase project set up
✅ A web app created within Firebase
✅ Authentication enabled
✅ Firestore configured for storing user data

Once that’s in place, let’s build our AuthContext.

Creating the AuthContext

Below is the implementation of /app/contexts/AuthContext.tsx:

"use client";

import React, { createContext, useContext, useState, useEffect } from "react";
import { auth } from "../firebase/config";
import { onAuthStateChanged, User } from "firebase/auth";
import { AuthContextType, AuthProviderProps } from "@/types";
import { Loader2 } from "lucide-react";

const AuthContext = createContext<AuthContextType | undefined>(undefined);

export const useAuth = (): AuthContextType => {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error("useAuth must be used within an AuthProvider");
  }
  return context;
};

export const AuthProvider: React.FC<AuthProviderProps> = ({ children }) => {
  const [user, setUser] = useState<User | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const unsubscribe = onAuthStateChanged(auth, (user) => {
      setUser(user);
      setLoading(false);
    });
    return () => unsubscribe();
  }, []);

  // Show a simple loading state
  if (loading) {
    return (
      <div className="min-h-screen flex items-center justify-center bg-background">
        <Loader2 className="animate-spin text-foreground" size={24} />
      </div>
    );
  }

  return (
    <AuthContext.Provider value={{ user, loading }}>
      {children}
    </AuthContext.Provider>
  );
};

Key Takeaways

Context Creation: The AuthContext is initialised with an undefined default value and later provided with the actual authentication state.
Custom Hook (useAuth): A helper function that simplifies accessing the auth state and ensures correct usage within the provider.
Real-Time Authentication: The useEffect hook listens for Firebase auth state changes and updates the user state accordingly.
Loading State: A spinner is displayed while authentication status is being determined, preventing unnecessary flickering in the UI.

Integrating AuthProvider in Your Application

To ensure authentication state is available across your app, wrap your root layout with the AuthProvider. This allows all components to access the user state seamlessly.

Here’s how it’s done in /app/layout.tsx:

import "./globals.css";
import type { Metadata } from "next";
import { Montserrat } from "next/font/google";
import { Toaster } from "@/components/ui/sonner";
import { ThemeProvider } from "@/components/ThemeProvider";
import Navbar from "@/components/Navbar";
import { AuthProvider } from "@/context/AuthContext";
const montserrat = Montserrat({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Auth Context + Firebase",
  description: "State of Auth Made Simple",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className={`${montserrat.className}`}>
        <a
          href="#main-content"
          className="sr-only focus:not-sr-only focus:absolute focus:top-0 focus:left-0 focus:z-50 focus:p-4 bg-background"
        >
          Skip to main content
        </a>
        <AuthProvider>
          <ThemeProvider
            attribute="class"
            defaultTheme="system"
            enableSystem
            disableTransitionOnChange
          >
            <Navbar />
            {children}
            <Toaster closeButton />
          </ThemeProvider>
        </AuthProvider>
      </body>
    </html>
  );
}

Highlights

Global Accessibility: By wrapping your app with AuthProvider, every component can access the auth state.
Hydration Considerations: The suppressHydrationWarning property in the <html> tag prevents hydration mismatches, improving client-side rendering stability.
Seamless Integration: The auth state is integrated alongside other providers (like the ThemeProvider), keeping the application structure clean and modular.

Protecting Routes with Client-Side Redirection

So, how do we ensure only the right users access the right pages? Let’s explore a simple, effective approach. Below is how I enforced authentication and email verification using React hooks:

"use client";

import { useEffect } from "react";
import { useRouter } from "next/navigation";
import { useAuth } from "@/context/AuthContext";
import PromptLibrary from "@/components/PromptLibrary";

export default function Home() {
  const { user } = useAuth();
  const router = useRouter();

  useEffect(() => {
    const timeout = setTimeout(() => {
      if (!user) {
        router.push("/auth");
      } else if (!user.emailVerified) {
        router.push("/verify-email");
      }
    }, 100);

    return () => clearTimeout(timeout);
  }, [user, router]);

  if (!user || !user.emailVerified) {
    return null;
  }

  return (
    <main className="min-h-screen bg-background" aria-label="Main content">
      <PromptLibrary />
    </main>
  );
}

Explanation

Authentication Check: The useEffect hook verifies if a user is authenticated and whether their email is verified.
Automatic Redirection: Unauthenticated users are redirected to /auth, while users with unverified emails are sent to /verify-email.
Graceful Handling: A short delay (setTimeout) ensures the user state is settled before triggering a redirection, preventing unnecessary flickers or race conditions.
Minimal UI Flashing: The component returns null if the user is not authenticated, avoiding unnecessary renders before navigation.

Managing User Profiles with Firebase

Firebase provides an excellent backend solution not just for authentication, but also for managing and storing user data. Below, you'll find two helper functions to fetch and update user profiles using Firestore:

Fetching a User Profile

To fetch a user’s profile from Firestore, add these functions to your /app/firebase/config.ts file:

export const getUserProfile = async (userId: string) => {
  const userRef = doc(db, "users", userId);
  const userDoc = await getDoc(userRef);

  if (userDoc.exists()) {
    return userDoc.data();
  }
  return null;
};

export const updateUserProfile = async (
  userId: string,
  data: {
    displayName?: string;
    photoURL?: string;
    email?: string;
    emailVerified?: boolean;
  }
) => {
  const userRef = doc(db, "users", userId);
  const userDoc = await getDoc(userRef);

  if (!userDoc.exists()) {
    // Create new user document if it doesn't exist
    await setDoc(userRef, {
      ...data,
      createdAt: new Date(),
      updatedAt: new Date(),
      emailVerified: data.emailVerified ?? false,
    });
  } else {
    // Update existing user document
    await updateDoc(userRef, {
      ...data,
      updatedAt: new Date(),
    });
  }
};

Function highlights

Document Check: Before updating, updateUserProfile checks whether the document exists. If not, it creates a new one.
Fetching Data: getUserProfile retrieves the user document from Firestore, returning the data if it exists, or null if not.
Efficient Updates: Both functions ensure that user profiles are either created or updated correctly with the current timestamp (createdAt and updatedAt), keeping your Firestore data in sync with the latest user information.

Integrating Firebase in React Components

Now that everything is in place, you can integrate Firebase into a user-facing component. In the example below I built a profile settings dialog with ShadCN, where users can update their profile information:

"use client";

import { useState } from "react";
import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
} from "@/components/ui/dialog";
import { Label } from "@/components/ui/label";
import { Button } from "@/components/ui/button";
import { Input } from "@/components/ui/input";
import { updateProfile } from "firebase/auth";
import { toast } from "sonner";
import { updateUserProfile } from "@/firebase/config";
import { ProfileSettingsDialogProps } from "@/types";

export function ProfileSettingsDialog({
  user,
  isOpen,
  onOpenChange,
}: ProfileSettingsDialogProps) {
  const [displayName, setDisplayName] = useState(user.displayName || "");
  const [photoURL, setPhotoURL] = useState(user.photoURL || "");
  const [isLoading, setIsLoading] = useState(false);

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setIsLoading(true);

    try {
      // Update Firebase Auth profile
      await updateProfile(user, {
        displayName,
        photoURL,
      });

      // Update Firestore user profile
      await updateUserProfile(user.uid, {
        displayName,
        photoURL,
        email: user.email || undefined,
      });

      toast.success("Profile updated successfully");
      onOpenChange(false);
    } catch (error) {
      toast.error("Failed to update profile");
      console.error("Error updating profile:", error);
    } finally {
      setIsLoading(false);
    }
  };

  // Render the dialog UI here...
}

What This Component Does

State Management: The component maintains local state for displayName and photoURL, allowing for controlled inputs and smooth state changes.
Profile Updates: Upon form submission, it synchronizes the user's profile across both Firebase Authentication and Firestore.
User Feedback: The component provides clear success and error notifications using toast messages, ensuring users are informed of the outcome.

By using this component, users can easily update their profile details, with changes reflected both in Firebase Auth and Firestore, ensuring data consistency.

Conclusion

By integrating React Context with Firebase, you can create a seamless authentication experience in your Next.js applications. This approach not only centralises user state management but also simplifies route protection and profile handling. With modular code and a clear separation of concerns, your app is set up to scale as your user base grows.

These strategies will enhance your app’s security, reliability, and user experience—benefitting both developers and end users alike.

I’d love to hear your thoughts! Feel free to share any feedback or experiences in the comments. Thanks for reading, and happy coding!

Restoring Chrome Bookmarks

Terry W — Thu, 13 Feb 2025 22:11:17 +0000

How to Manually Restore Deleted Chrome Bookmark Folders

Losing your carefully organised Chrome bookmark folders can be a nightmare—especially when Chrome Sync or an accidental deletion wipes out your saved folders. In this tutorial, I'll share the process I used to recover my bookmarks manually by leveraging Chrome’s built-in backup file (Bookmarks.bak). Follow these steps on macOS or Windows to restore your bookmark folders one-by-one.

What You’ll Need

For macOS: Finder access to your Chrome profile directory (typically in your Library folder).
For Windows: File Explorer access to your Chrome user data folder.
A quiet moment and a little patience if you have many folders to recover.

General Overview

The method works by temporarily stopping Chrome Sync from overwriting your changes, restoring the backup file as your active bookmarks file, and then copying individual folders back into your restored bookmarks once Chrome has updated. The key steps for both operating systems are:

Disconnect from the Internet: Prevent Chrome Sync from re-uploading the current (empty) bookmarks.
Quit Chrome Completely: Ensure Chrome isn’t running in the background.
Access Your Chrome Profile Folder: Locate the folder where the bookmark files are stored.
Replace the Bookmarks File: Delete or rename the current bookmarks file, duplicate the backup file (Bookmarks.bak), and rename it to Bookmarks.
Reopen Chrome Offline: Verify that your bookmarks are restored.
Recover Each Folder: Copy the desired bookmark folder, reconnect to the internet, let Chrome update, then paste the folder back.
Repeat: Do this for each folder you need to restore.

Detailed Steps for macOS

Prepare Your System

Turn Off Wi-Fi: Disconnect from your network to prevent Chrome Sync from interfering.
Quit Chrome Completely: Use Activity Monitor to ensure no Chrome processes are running.

Locate Your Chrome Profile Folder

Open Finder.
Press Go, Go To Folder

Then type in:

~/Library/Application Support/Google/Chrome/Default/

You’ll see two files: Bookmarks and Bookmarks.bak.

Restore the Bookmarks Backup

Delete the Current Bookmarks File: Remove the Bookmarks file.
Duplicate and Rename: Duplicate Bookmarks.bak and rename the copy to Bookmarks (remove the “.bak” extension).

Launch Chrome Offline

With Wi-Fi still off, reopen Chrome and verify that your bookmarks now reflect the backup state.

Recover Your Folders

In Chrome, open the Bookmark Manager (via chrome://bookmarks).
Copy a Folder: Select and copy the folder you wish to restore.
Turn Wi-Fi On: Reconnect to the internet and wait a moment for Chrome to sync.
Paste the Folder: Reopen Bookmark Manager and paste the folder into your bookmarks.
Repeat for each folder.

For Windows users

Prepare Your System

Disconnect from the Internet: Turn off Wi-Fi or unplug your network cable.
Quit Chrome Completely: Use Task Manager (Ctrl + Shift + Esc) to ensure all Chrome processes are closed.

Locate Your Chrome Profile Folder

Open File Explorer.
Navigate to:

C:\Users\[YourUsername]\AppData\Local\Google\Chrome\User Data\Default\

(If you don’t see the AppData folder, ensure that hidden files are visible by enabling “Hidden items” in the View menu.)

You should see the files Bookmarks and Bookmarks.bak.

Restore the Bookmarks Backup

Delete the Current Bookmarks File: Delete the Bookmarks file.
Duplicate and Rename: Copy the Bookmarks.bak file and rename the copy to Bookmarks (remove the “.bak” extension).

Launch Chrome Offline

With your computer still disconnected from the internet, launch Chrome.
Check that your bookmarks now reflect the restored backup.

Recover Your Folders

Open the Bookmark Manager in Chrome (type chrome://bookmarks in the address bar).
Copy a Folder: Select and copy the bookmark folder you want to recover.
Reconnect to the Internet: Enable your network connection and wait for Chrome to sync.
Paste the Folder: Return to the Bookmark Manager and paste the folder.
Repeat for each folder you need to restore.

Tips & Best Practices

Regular Backups: Once you’ve restored your bookmarks, export them via Bookmark Manager (Organise > Export bookmarks) to keep a current backup.
Disable Sync Temporarily: Consider signing out of your Google account or disabling bookmark sync while performing these steps.
Use Built-In Backups: If you have Time Machine on macOS or File History on Windows, you may also restore the entire profile folder from a backup.
Export Regularly: Even if you rely on sync, periodically export your bookmarks as an HTML file for an extra layer of safety.

Conclusion

By following these step-by-step instructions on macOS and Windows, you can manually restore deleted Chrome bookmark folders, even if Chrome Sync initially overwrites your restored file. It might be a bit tedious if you have many folders, but with a little patience, you can regain your organised bookmarks.

Have you ever had to restore your Chrome bookmarks manually? Share your experiences and any extra tips in the comments below!

Creating My First NPM Package: CLI Dev Tool

Terry W — Sun, 12 Jan 2025 21:45:50 +0000

Introduction

Hello Dev.to community! Not only is this my first npm package but it is also my first dev.to article. As a developer who recently transitioned into full-stack development, I found the process of setting up Express.js projects slightly tedious and time-consuming. I wanted to automate this repetitive process somewhat, so I created a CLI tool that scaffolds an entire backend application with boilerplate code to help get you started quickly. This post will walk you through my journey of building my first npm package and show how it can save you time on your next project.

The Challenge

Every backend project requires a complex setup process: creating routes, data models, controllers, configuring database connections, and managing environment variables. Without automation, developers can spend valuable time copy-pasting boilerplate code and following the same setup checklist repeatedly. My CLI tool helps solve this by creating a customisable tool that handles these slightly monotonous tasks, allowing developers to focus on building features instead of project setup.

Building the Package: Key Features

Let me walk you through the main features I've built into this tool:

Multiple Database Support: Quickly scaffold your Express.js app with your choice of PostgreSQL, MySQL, SQLite, or MongoDB. No need to worry about different connection setups - the tool handles that for you.
Automatic Configuration: Skip the tedious setup phase. The tool creates your .env files, configures your connection strings, and sets up all the necessary folders, getting you ready to code faster.
Clean MVC Architecture: Start with a well-organized project structure. Your routes, controllers, and models are neatly arranged following MVC patterns, making your codebase easier to maintain as it grows.
TypeScript or JavaScript Support: Whether you prefer the simplicity of JavaScript or the type safety of TypeScript, the choice is yours. The tool generates all the boilerplate in your preferred language.

How I Built It

I built the package using Node.js and utilised the prompts library for interactive prompts, allowing users to select their database and other options. The scaffolding is inspired by how Vite’s script handles templates. I implemented a similar approach by organising different template folders for various frameworks and database setups. Users can choose from options like PostgreSQL, MongoDB, SQLite, or MySQL, each with TypeScript or JavaScript variants.

The CLI functionality is achieved using minimist for argument parsing. File operations, such as copying template files, are handled with fs and custom helper functions. One challenge I faced was understanding how the project structures are output, which I overcame through hands-on experimentation and iteration.

Usage

To get started, run the command to scaffold your app:

npx create-mvc-server

After running the command, you'll be prompted to:

Enter your project name
Select your database:
- PostgreSQL
- MySQL
- SQLite
- MongoDB
Choose between JavaScript/TypeScript

The tool will generate a structure like:

my-project/
├── src/
│   ├── controllers/
│   ├── models/
│   ├── routes/
│   ├── config/
│   │   └── db.js
│   └── app.js
├── .env
└── package.json

Next Steps

The package is still in its early stages, and I plan to expand its capabilities by adding support for more database configurations and authentication boilerplates. In the future, I am also considering exploring alternative server implementations, such as using Go instead of Express, to broaden its use cases and appeal to a wider range of developers.

Conclusion

This project has been an enjoyable and educational journey. I’ve gained valuable insights into building CLI tools and publishing them on npm. I’m eager to continue enhancing the package and making it a useful tool for developers to streamline their project setup. If you’d like to give it a try or contribute, please visit the GitHub repository and share your feedback. Your input would be greatly appreciated!

Your Feedback Matters

Do you have suggestions or ideas for improvement? Are you interested in contributing? I’d be delighted to hear from you and welcome any contributions. You can find the source code here on GitHub.

DEV Community: Terry W

Fixing Playwright build errors on Render when browsers are missing

TL;DR

Background

Root cause

The working fix

Why this works

Extra Checks and Good Practices

TLDR checklist

Closing notes

Fixing Vite HMR Issues in React by Splitting Your Auth Context

The Problem

The Fix

Takeaway

The Art of API Documentation: A Comprehensive Guide

Table of Contents

Introduction

What is an API?

Why Good Documentation Matters

Essential Parts of API Documentation

1. Introduction and Overview

2. Base URL

3. List of Endpoints

4. Detailed Endpoint Information

a. HTTP Method and Path

b. Description

c. Request Parameters

d. Response Format

e. Error Handling

f. Example Requests and Responses

Advanced Documentation Tips

Version Control for Documentation

Using Markdown

Best Practices I've Learned

Balance Completeness with Clarity

Show, Don't Just Tell

Maintain and Evolve Your Documentation

Bonus Tip - Quickly Grab Curl Requests

Maintain a Changelog File:

Conclusion

How To Implement Express Authentication with RBAC (Role Based Access Control)

Introduction

1. Auth Routes with Validation

2. Auth Controller: Hashing, Tokens and Sessions

Token Generation

Register and Login

Authentication & Authorisation Middleware

Verifying the token

Checking Roles

4. Applying Middleware to Routes

Conclusion

State of Auth Made Simple

Setting Up the AuthContext

Prerequisites

Creating the AuthContext

Key Takeaways

Integrating AuthProvider in Your Application

Highlights

Protecting Routes with Client-Side Redirection

Explanation

Managing User Profiles with Firebase

Fetching a User Profile

Function highlights

Integrating Firebase in React Components

What This Component Does

Conclusion

Restoring Chrome Bookmarks

How to Manually Restore Deleted Chrome Bookmark Folders

What You’ll Need

General Overview

Detailed Steps for macOS

Prepare Your System

Locate Your Chrome Profile Folder

Restore the Bookmarks Backup

Launch Chrome Offline

Recover Your Folders

For Windows users

Prepare Your System

Locate Your Chrome Profile Folder

Restore the Bookmarks Backup