DEV Community: Terry W

Cursor Was Using 50GB of Memory - The Cause Was a Nested `.cursor` Folder

Terry W — Fri, 03 Jul 2026 18:07:23 +0000

I recently hit a fairly ridiculous issue while running a Next.js app.

My Mac started slowing down badly, and Activity Monitor showed:

Cursor: 50GB+ memory
Chrome: 16GB+ memory

At first, I assumed the app had a memory leak.

I checked the usual suspects:

React render loops
leaking useEffect hooks
timers and listeners without cleanup
excessive console logging
large client-side renders
Next.js cache problems

I also cleared .next, restarted the dev server, restarted Cursor, and checked for unusually large files.

None of that fixed it.

The Actual Cause

Eventually, I noticed that the .cursor directory was nested inside the project instead of sitting at the repository root.

It looked roughly like this:

my-project/
├── app/
│   └── some-folder/
│       └── .cursor/
├── components/
├── package.json
└── next.config.ts

Instead of:

my-project/
├── .cursor/
├── app/
├── components/
├── package.json
└── next.config.ts

I have no idea how it ended up there.

I moved the nested .cursor folder back to the project root, fully restarted Cursor, and the memory usage immediately returned to normal. That was the only change that actually fixed it.

Why This Took So Long to Find

Restarting Cursor had not helped because it was reopening the same project with the same misplaced directory.

The app itself looked guilty because Chrome was also consuming a large amount of memory, so I spent time checking React and Next.js first.

In the end, the problem was not a render loop or some deeply buried application bug.

It was one hidden folder in the wrong place.

Quick Check

Run this from the project root:

find . -type d -name ".cursor"

For a normal single-project repository, you would usually expect:

./.cursor

A deeply nested result is worth investigating.

Be careful with monorepos, because nested configuration may be intentional. Do not move anything blindly.

The Fix

Find the misplaced .cursor directory.
Move it to the repository root.
Fully quit Cursor.
Reopen the project.
Check memory usage again.

In my case, that was enough.

The Lesson

When an editor suddenly starts consuming absurd amounts of memory, do not only inspect the application code.

Also inspect the project structure, especially hidden tool-specific directories.

One misplaced folder caused Cursor to reach more than 50GB of memory and sent me looking for problems that were not there.

Building My First Component Library: What Went Well, What Broke, and What AI Changed

Terry W — Fri, 12 Jun 2026 13:45:51 +0000

Over the past couple of months, I've been building a component library.

The original goal wasn't to create another collection of buttons, cards, and inputs. I wanted to build components that felt intuitive to use and satisfying to interact with, the kind of things you actually enjoy dropping into a project instead of fighting with.

As the project evolved, I decided to structure it for delivery via a shadcn-style registry approach. That meant components aren’t installed as a traditional package, they are pulled directly into your codebase. You own them. You can modify them. You are not stuck behind an abstraction layer you do not control.

What I thought would mostly be a UI project quickly revealed itself to be just as much about architecture, structure, and how components are actually distributed and consumed in real projects.

Why I Started Building It

I enjoy frontend work, but I’ve always been more drawn to backend engineering and how things are structured under the hood.

I like the small details. Interactions that feel right. Components that don’t just “work”, but feel like they’ve been thought through properly.

A lot of existing libraries either feel too heavy, too restrictive, or too disconnected from real-world usage once you start bending them to fit actual apps.

So the idea was simple: build something more flexible and more enjoyable to work with, not just visually but structurally.

And also build something reusable instead of just another one-off project.

Why I Chose a Registry-Based Approach

The shadcn approach was a big influence here.

Instead of shipping a black-box component library, you expose a registry that lets developers install only what they need directly into their project.

It solves a few problems at once:

No dependency lock-in
Full control over styling and behaviour
Easier to customise without fighting the library
Better fit for real-world projects where not everything is needed

It also just feels better as a developer experience. You are not guessing what is inside a package, you can see it.

Building Components Wasn't the Hard Part

This is where things got interesting.

Building components themselves was fairly straightforward most of the time.

The harder part was everything around them.

Once you move into a registry-based delivery model, you are no longer just thinking about UI. You are thinking about how components actually exist outside your system:

How components are structured for export
How they are described and discovered in a registry
How users install them into their own projects
How examples are stored and rendered
How everything stays consistent as it scales

I expected to spend most of my time building components. Instead, I found myself spending a surprising amount of time thinking about how those components would actually reach users.

That shift in thinking was probably the biggest early lesson.

What Broke

Some of my earliest assumptions didn't survive contact with growth.

A few abstractions became more complicated than they needed to be. Metadata relationships had to be revisited. Documentation occasionally lagged behind implementation. There were also moments where AI-generated solutions looked reasonable on the surface but didn't align with the architectural direction I wanted the project to take.

None of these were catastrophic failures, but they reinforced an important lesson: the bigger challenge wasn't building components, it was keeping everything coherent as the project evolved.

Architecture Lessons From a First-Time Build

This is my first time building anything that leans into this kind of structure, so a lot of it has been learned on the fly.

Some decisions felt obvious at the start, and then less obvious once the project grew.

There has been a fair bit of refactoring, especially around how components, metadata, and registry entries relate to each other.

Looking back, there are definitely parts I would redesign if I started again. Some abstractions are slightly heavier than they need to be, and some structure decisions only really make sense because I have already lived through the problems they were meant to solve.

But it works, and that has been enough to keep moving.

What AI Actually Helped With

AI has been a big part of this build, but not in the “press a button and it builds everything” sense.

Where AI helped

Generating initial component scaffolds
Speeding up repetitive boilerplate
Exploring different implementation approaches quickly
Prototyping UI variations faster than I normally would
Increasing the amount of iteration I could realistically do

Not only did it start to change how I work day-to-day, it also began producing genuinely useful outputs when pushed in the right direction.

It still needs guidance most of the time, but the speed of iteration it enables is hard to ignore.

Where AI needed guidance

Keeping architecture decisions consistent across the project
Avoiding choices that would break the structure of the system later
Refactoring larger parts of the codebase
Understanding the constraints of how everything fits together
Preventing architectural drift as the project scaled

A lot of it was less “AI building it for me” and more “AI letting me move faster while I constantly correct direction”.

AI was a force multiplier, not an autopilot.

The Biggest Thing I Learned

The biggest shift for me has been realising that building software is often less about writing code and more about making decisions.

What to abstract and what not to. What to simplify. What to leave slightly messy for now instead of overengineering too early.

As the project has grown, architecture and structure matter more than individual components.

Another underrated part has been documentation, especially changelogs. I have definitely learned that keeping things up to date is significantly easier than reconstructing everything afterwards.

What's Next

TT UI has now been released, which means the focus shifts from building in isolation to learning from real usage.

That means:

Fixing rough edges in the current structure
Expanding the component set
Adding more blocks and templates
Improving the registry experience
Listening to feedback and adjusting based on how developers actually use it

At this stage, assumptions matter less than real-world usage.

Closing Thoughts

Building this library has taught me a lot more than just component development.

It has been a lesson in architecture, tooling, distribution, documentation, and how AI actually fits into real-world development workflows.

It has also been a reminder that most projects look cleaner from the outside than they feel while you are building them.

It is not perfect, but it is real, shipped, and usable. And for a first pass at something like this, that feels like enough to keep going.

Thanks for reading. If you'd like to take a look at what I've been building, you can find TT UI here: https://ui.tibbstech.co.uk

Fixing Playwright build errors on Render when browsers are missing

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

Background

I use Playwright in my API to render email templates for my app, Snap Template.

It worked fine on my computer—insert “works on my machine” meme here—but after deploying to Render, the export feature failed because Playwright could not find the Chromium executable.

The deployment itself completed successfully. The failure occurred at runtime when the API attempted to launch Chromium.

Root Cause

Locally, I had previously run:

npx playwright install

That downloaded the browser binaries into Playwright’s cache on my computer.

The Render environment did not have the same local cache, so although the Playwright package was installed, the Chromium executable it expected was missing.

Playwright normally stores browsers in an operating-system-specific cache. On Linux, that defaults to:

~/.cache/ms-playwright

The location can be changed using PLAYWRIGHT_BROWSERS_PATH.

The Fix That Worked

1. Install Chromium During `postinstall`

I added the following script to package.json:

{
  "scripts": {
    "postinstall": "playwright install chromium",
    "build": "your-build-command"
  }
}

This installs only Chromium rather than downloading every browser supported by Playwright.

Because my API launches Playwright in production, the relevant Playwright package also needs to be inside dependencies, not only devDependencies:

{
  "dependencies": {
    "playwright": "your-installed-version"
  }
}

Production dependencies are packages required for the deployed application to run, while development dependencies are intended for development and testing tools that are not needed at runtime.

2. Use a Render Build Command

My Render build command can now be:

npm ci && npm run build

Or, when the project does not have a suitable lockfile:

npm install && npm run build

There is no need to add npm run postinstall manually:

npm install && npm run postinstall && npm run build

npm automatically runs lifecycle scripts such as postinstall as part of the installation process. Running it again would download or verify the browser installation twice.

Alternatively, you can remove the postinstall script and make the browser installation explicit:

npm ci && npx playwright install chromium && npm run build

Either approach is valid. I used postinstall so the browser installation remains part of the dependency setup.

3. Configure the Browser Path

In Render, I added:

PLAYWRIGHT_BROWSERS_PATH=/opt/render/project/.cache/playwright

The important part is not that every host must use this exact path. The important part is that the same PLAYWRIGHT_BROWSERS_PATH value is available during both:

Browser installation
Application runtime

This tells Playwright where to install Chromium and where to look for it later. Playwright officially supports overriding its default browser cache with this environment variable.

For a more portable project-local installation, Playwright also supports:

PLAYWRIGHT_BROWSERS_PATH=0

This stores the browsers under:

node_modules/playwright-core/.local-browsers

That is known as a hermetic installation.

Why It Works

The corrected deployment flow is:

Render installs the project dependencies.
npm automatically runs postinstall.
Playwright downloads the Chromium version expected by the installed package.
Chromium is stored at the configured browser path.
The API starts with the same environment variable.
Playwright finds and launches the installed executable.

Missing Browser vs Missing System Libraries

This fix addresses a missing Chromium executable.

If the error changes to missing shared libraries or operating-system dependencies, the browser is installed but the environment does not contain everything required to launch it.

Playwright can install browser dependencies using:

npx playwright install --with-deps chromium

However, installing system packages may require permissions that are not available in every managed hosting environment. Playwright documents --with-deps as the combined browser and operating-system dependency installation command.

When native deployment does not provide the required libraries, Docker gives you more control over the runtime environment.

Using Docker Instead

For more reproducible deployments, Playwright provides Docker images containing browser binaries and required system dependencies.

Pin the image to the Playwright version used by your project:

FROM mcr.microsoft.com/playwright:vX.Y.Z-noble

Replace vX.Y.Z with the version matching your installed Playwright package.

Avoid using:

FROM mcr.microsoft.com/playwright:latest

A version mismatch can mean the container has different browser binaries from those expected by the package.

The Playwright Docker image contains browsers and operating-system dependencies, but your application still needs to install its npm dependencies.

Extra Checks and Good Practices

Check the Installed Playwright Version

npx playwright --version

Each Playwright release expects specific browser versions, so reinstall the browsers after upgrading Playwright.

Log the Resolved Executable Path

A temporary debug log can confirm where Playwright expects Chromium:

import { chromium } from "playwright";

console.log(
  "Chromium executable:",
  chromium.executablePath()
);

Remove or reduce diagnostic logging once the deployment is stable.

Check the Installed Browsers

npx playwright install --list

This can help confirm whether Chromium was installed and where Playwright found it.

Monitor Disk Usage

Playwright browser installations can consume hundreds of megabytes, so monitor the service’s storage and build logs.

Install Only What You Need

Installing Chromium directly is already enough to avoid downloading Firefox and WebKit:

npx playwright install chromium

For strictly headless workloads, Playwright also provides an --only-shell option that can avoid downloading the full Chromium browser:

npx playwright install --only-shell chromium

Whether that option is appropriate depends on how your application launches and uses Chromium.

Install During Build, Not on Request

Do not download Chromium when a user requests an export.

Installing during runtime would:

Increase response and cold-start time
Add an external network dependency to the request
Risk concurrent downloads
Make failures harder to diagnose

Install the browser during the deployment build instead.

Checklist

Is Playwright in dependencies when it is used by the production API?
Did postinstall run during the Render build?
Did the build log show Chromium being downloaded?
Is PLAYWRIGHT_BROWSERS_PATH available during both build and runtime?
Does chromium.executablePath() point to an existing file?
Does the Playwright package version match the installed browser?
If Chromium exists, are Linux system libraries missing instead?
Would a pinned Playwright Docker image provide a more reliable environment?

Closing Notes

If Playwright works locally but fails after deployment, remember that the npm package and browser binaries are separate.

My local machine already had Chromium inside Playwright’s cache, while the Render service did not. Installing Chromium during the build and configuring a consistent PLAYWRIGHT_BROWSERS_PATH solved the runtime error for Snap Template.

The final setup was:

{
  "scripts": {
    "postinstall": "playwright install chromium"
  }
}

npm ci && npm run build

PLAYWRIGHT_BROWSERS_PATH=/opt/render/project/.cache/playwright

If this helped you do the Playw-right thing and get your service running, share what deployment setup worked for you.

TL;DR

If Playwright works locally but fails on Render with an executable does not exist error:

Install Chromium during the build.
Configure PLAYWRIGHT_BROWSERS_PATH so installation and runtime use the same location.
Make sure Playwright is installed as a production dependency.
Avoid running the postinstall script twice.

Playwright requires browser binaries that match the installed Playwright version. Installing the npm package alone does not guarantee that Chromium is available in the deployed environment.

Fixing React Fast Refresh Issues in Vite by Splitting Your Auth Context

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

Have you ever updated a file in a React and Vite project, only for the entire page to reload instead of React Fast Refresh preserving your state?

That happened while I was building an authentication context. I exported both the AuthProvider component and a custom useAuth hook from the same .tsx file.

The code worked, but Vite could no longer treat the module as a reliable Fast Refresh boundary. A small refactor fixed the issue.

The Problem

My original AuthContext.tsx contained the context, provider, and custom hook:

import {
  createContext,
  useContext,
  useEffect,
  useState,
  type ReactNode,
} from "react";

import authApi from "@/api/auth-api";
import type { AuthContextType, AuthResponse } from "@/types/auth";
import type { User } from "@/types/users";

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

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

  // Authentication state and methods...

  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 then logged the following warning:

[vite] (client) hmr invalidate /src/contexts/AuthContext.tsx
Could not Fast Refresh ("useAuth" export is incompatible).

Vite’s HMR system was still working, but React Fast Refresh could not safely preserve the component state for this module.

The provider is a React component, while useAuth is a hook. Exporting both from the same component module caused Vite to invalidate the module and propagate the update, which could result in a full-page reload.

The Fix

The fix was to separate the context and hook from the provider component.

`AuthContext.ts`

import {
  createContext,
  useContext,
} from "react";

import type { AuthContextType } from "@/types/auth";

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

export function useAuth(): AuthContextType {
  const context = useContext(AuthContext);

  if (context === undefined) {
    throw new Error(
      "useAuth must be used within an AuthProvider"
    );
  }

  return context;
}

`AuthProvider.tsx`

import {
  useEffect,
  useState,
  type ReactNode,
} from "react";

import authApi from "@/api/auth-api";
import { AuthContext } from "@/contexts/AuthContext";
import type { AuthResponse } from "@/types/auth";
import type { User } from "@/types/users";

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

  // Authentication state and methods...

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

After splitting the files, the Fast Refresh warning disappeared and updates no longer caused the entire page to reload.

Why This Works

React Fast Refresh works best when modules exporting React components remain consistent component boundaries.

Moving the context and hook into a separate .ts module leaves AuthProvider.tsx focused on exporting the provider component.

This is not a strict rule that every .tsx file can only contain component code, but it is a useful structure for avoiding incompatible Fast Refresh exports.

The ESLint rule below can also detect this pattern:

react-refresh/only-export-components

Takeaway

When a React and Vite project unexpectedly performs full-page reloads, check the exports in the affected component module.

A practical structure is:

contexts/
├── AuthContext.ts
└── AuthProvider.tsx

Keep component modules focused on component exports, and move reusable hooks, contexts, and utilities into separate files where appropriate.

The application behaviour may already work correctly, but separating the modules can restore Fast Refresh and preserve local state during development.

A Practical Guide to Writing Clear API Documentation

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

A Practical Guide to Writing Clear API Documentation

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

Introduction

APIs connect applications, services, and data sources. However, even a well-designed API can be difficult to use when its behaviour is not clearly documented.

This article covers the approach I use to document HTTP APIs, based on what I learned while building my NC News API.

By the end, you should have a practical structure for documenting a small API clearly and consistently.

What Is an API?

An API, or Application Programming Interface, defines how different pieces of software communicate.

For an HTTP API, this usually means documenting:

Which URLs are available
Which HTTP methods they accept
What data clients can send
What data the server returns
How authentication works
Which errors may occur

An API acts as a contract between the service providing the data and the application consuming it.

In my NC News API, clients can retrieve and modify users, articles, comments, and topics without needing to understand the underlying database structure.

Why Good Documentation Matters

Good documentation reduces the amount of guesswork required to use an API.

For API consumers

Faster onboarding: Developers can understand the API more quickly.
Fewer integration issues: Clear schemas and examples show what data is expected.
Less trial and error: Parameters, responses, and errors are defined upfront.
Better developer experience: Users can focus on building rather than reverse-engineering behaviour.

For API maintainers

Fewer support questions: Common issues can be answered directly in the documentation.
Greater consistency: The team has a shared reference for expected behaviour.
Improved API design: Documenting an endpoint often exposes unclear naming or inconsistent responses.
Safer changes: Versioning and deprecation notes help prevent unexpected breakages.

Essential Parts of API Documentation

1. Introduction and Overview

Begin with a concise explanation of what the API does and who it is intended for.

The NC News API provides access to users, topics, articles, and comments for a news discussion platform.

You should also include any important prerequisites, such as authentication requirements or account setup.

2. Server and Base URLs

Provide complete URLs for the available environments.

Production: https://api.example.com/v1
Development: http://localhost:3000/api

A relative path such as /api may be useful inside a project, but public consumers also need to know the host.

3. Authentication

Explain how protected endpoints are accessed.

For example:

Authorization: Bearer <access-token>

Document:

How users obtain credentials
Where the token or key should be supplied
Whether particular roles or permissions are required
The difference between 401 Unauthorized and 403 Forbidden

Never place real tokens or credentials in published examples.

4. Endpoint Groups

Organise endpoints by resource so they are easier to scan.

For the NC News API, the groups might be:

API information
Users
Topics
Articles
Comments

Each endpoint should follow the same structure.

5. Method and Path

Clearly show the HTTP method and complete route.

GET /api/users

The method matters because the same route may behave differently for GET, POST, PATCH, or DELETE.

6. Description

Explain what the endpoint does in one or two sentences.

Returns an array containing the public profile information for all users.

Avoid repeating the path without explaining the result or purpose.

7. Parameters

Separate parameters by where they appear in the request.

Path parameters

GET /api/users/:username

Name	Type	Required	Description
`username`	string	Yes	Username of the requested user

Query parameters

GET /api/articles?topic=coding&sort_by=created_at&order=desc

Name	Type	Required	Default	Description
`topic`	string	No	—	Filter articles by topic
`sort_by`	string	No	`created_at`	Field used for sorting
`order`	`asc` or `desc`	No	`desc`	Sort direction

Also document allowed values, limits, and validation rules.

8. Request Bodies

For endpoints that accept a body, document the expected content type and fields separately from URL parameters.

POST /api/articles
Content-Type: application/json

{
  "title": "Writing Better API Documentation",
  "body": "Clear documentation reduces integration time.",
  "topic": "coding",
  "author": "butter_bridge"
}

Include:

Required fields
Optional fields
Data types
Validation constraints
Whether unknown fields are accepted

9. Response Schemas

Examples are useful, but they should be supported by a description of the response structure.

Status: 200 OK
Content-Type: application/json
Body: Array<User>

A User response might contain:

Field	Type	Nullable	Description
`username`	string	No	Unique username
`name`	string	No	User’s display name
`avatar_url`	string	Yes	URL of the user’s avatar

Example:

[
  {
    "username": "butter_bridge",
    "name": "jonny",
    "avatar_url": "https://example.com/avatar.jpg"
  }
]

The schema explains what is guaranteed. The example shows what a real response may look like.

10. Error Responses

Document the important success and failure outcomes for each endpoint.

200 — Request succeeded
400 — Invalid request data
401 — Authentication required
403 — Insufficient permission
404 — Resource not found
409 — Request conflicts with existing data
500 — Unexpected server error

Include an example error body:

{
  "status": 404,
  "msg": "User does not exist"
}

Keep the error format consistent across endpoints where possible.

11. Pagination, Filtering, and Sorting

Collection endpoints often need more detail than a basic response example.

For an endpoint such as:

GET /api/articles

document:

Default page size
Maximum page size
Pagination parameters
Available filters
Sortable fields
Default ordering
Response metadata
Behaviour when no results are found

Example:

{
  "articles": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "total_pages": 0
  }
}

Advanced Documentation Tips

Use OpenAPI for Larger APIs

Markdown and manually maintained JSON can work for smaller projects.

For larger APIs, consider using an OpenAPI document as the source of truth. It can describe:

Servers
Endpoints
Parameters
Request bodies
Response schemas
Authentication
Examples
Deprecated operations

OpenAPI documents can also be used by documentation generators, API clients, testing tools, and development environments.

Define a Versioning Policy

API versioning and software release versioning are related, but they are not the same thing.

An API may expose versions through its URL:

https://api.example.com/v1

Your project releases may separately follow Semantic Versioning:

2.4.1

Document:

What counts as a breaking change
How long older versions are supported
How consumers will be notified
How users should migrate

Document Deprecations

When an endpoint or field is being replaced, clearly state:

What is deprecated
Why it is being deprecated
What should be used instead
When it will be removed
How to migrate

Example:

Deprecated: GET /api/posts

Use GET /api/articles instead.

Planned removal: 1 December 2026

Keep Documentation in Version Control

Documentation should change alongside the code.

Store it in the repository so changes can be:

Reviewed
Tracked
Updated in the same pull request as the implementation
Reverted when necessary

This reduces the chance of the documentation drifting away from the actual API behaviour.

Best Practices I’ve Learned

Balance Completeness with Clarity

Documentation should contain enough information for developers to use the API without making every endpoint difficult to scan.

A consistent template helps:

Method and path
Description
Authentication requirements
Parameters
Request body
Response schema
Example request
Example response
Possible errors

Show, Don’t Just Tell

For an endpoint such as GET /api/articles, include:

A complete request URL
The available filters
A response schema
A realistic response example
Common error cases

Examples help developers quickly understand how the documented pieces fit together.

Use Consistent Terminology

Choose one name for each resource and use it throughout the API and documentation.

For example, avoid switching between:

Articles
Posts
Stories

unless those terms represent genuinely different resources.

Keep Examples Safe

When copying requests from a browser or API client, remove:

Authorization headers
Cookies
API keys
Session identifiers
Personal data

Published examples should use obvious placeholder values.

Quickly Copy cURL Requests

Browser developer tools can help generate example requests.

Open the Network panel, right-click a request, and choose the relevant copy option, such as Copy as cURL.

Review the command before publishing it, as copied requests may contain tokens, cookies, or other sensitive headers.

Maintain a Changelog

Keep a CHANGELOG.md file that records:

Release version
Release date
Added features
Behaviour changes
Bug fixes
Deprecations
Breaking changes

Semantic Versioning can communicate whether a release contains breaking, additive, or corrective changes, provided your public API and compatibility policy are clearly defined.

Conclusion

Good API documentation is part of the product rather than an afterthought.

It should explain not only which endpoints exist, but also how to authenticate, what data to send, what responses to expect, how errors are represented, and how the API will change over time.

Clear schemas, realistic examples, consistent terminology, and an accurate changelog make an API easier to adopt and safer to maintain.

Great documentation does more than explain how an API works. It gives developers enough confidence to build against it without relying on guesswork.

Express Authentication and Team-Scoped RBAC with JWTs

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

Securing an API involves two separate concerns:

Authentication: identifying the user making the request
Authorisation: deciding whether that user can perform an action

In this article, we’ll create an Express authentication flow with:

Registration and login
Short-lived access tokens
Revocable refresh sessions
JWT authentication middleware
Team-scoped role checks for protected routes

The examples use TypeScript, Express, jsonwebtoken, bcryptjs, and express-validator.

1. Auth Routes and Validation

Create a dedicated authentication router:

import { Router } from "express";
import { body, validationResult } from "express-validator";

import {
  login,
  logout,
  refreshToken,
  register,
} from "../controllers/auth-controller";

const authRouter = Router();

const validateRequest = (req, res, next) => {
  const errors = validationResult(req);

  if (!errors.isEmpty()) {
    return res.status(400).json({
      status: "error",
      errors: errors.array(),
    });
  }

  next();
};

const registerValidation = [
  body("username")
    .trim()
    .isLength({ min: 3, max: 30 }),

  body("email")
    .trim()
    .isEmail()
    .normalizeEmail(),

  body("password")
    .isString()
    .isLength({ min: 15 })
    .custom((password: string) => {
      if (Buffer.byteLength(password, "utf8") > 72) {
        throw new Error(
          "Password exceeds the maximum size supported by bcrypt"
        );
      }

      return true;
    }),

  body("isEventOrganiser").optional().isBoolean(),

  body("teamName")
    .optional()
    .custom((value, { req }) => {
      if (
        req.body.isEventOrganiser &&
        (!value || value.trim() === "")
      ) {
        throw new Error(
          "Team name is required for event organisers"
        );
      }

      return true;
    }),
];

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

authRouter.post(
  "/login",
  [
    body("username").trim().notEmpty(),
    body("password").isString().notEmpty(),
  ],
  validateRequest,
  login
);

authRouter.post("/refresh-token", refreshToken);
authRouter.post("/logout", logout);

export default authRouter;

Do not call .trim() on passwords. Whitespace may be intentional, and changing it means hashing a different value from the one the user entered.

bcrypt also has a 72-byte input limit. For new applications, Argon2id is generally a stronger default.

2. Generating Tokens

JWT secrets should never fall back to public placeholder values.

import {
  createHash,
  randomUUID,
} from "node:crypto";
import jwt from "jsonwebtoken";

const JWT_SECRET = process.env.JWT_SECRET;
const JWT_REFRESH_SECRET =
  process.env.JWT_REFRESH_SECRET;

if (!JWT_SECRET || !JWT_REFRESH_SECRET) {
  throw new Error("JWT secrets must be configured");
}

const ISSUER = "events-api";
const AUDIENCE = "events-client";

function hashToken(token: string) {
  return createHash("sha256")
    .update(token)
    .digest("hex");
}

Use short-lived access tokens and longer-lived refresh tokens:

async function generateTokens(user: User) {
  const accessToken = jwt.sign(
    {
      username: user.username,
      email: user.email,
    },
    JWT_SECRET,
    {
      subject: String(user.id),
      expiresIn: "15m",
      algorithm: "HS256",
      issuer: ISSUER,
      audience: AUDIENCE,
    }
  );

  const tokenId = randomUUID();

  const refreshToken = jwt.sign(
    {},
    JWT_REFRESH_SECRET,
    {
      subject: String(user.id),
      jwtid: tokenId,
      expiresIn: "7d",
      algorithm: "HS256",
      issuer: ISSUER,
      audience: AUDIENCE,
    }
  );

  await createSession({
    userId: user.id,
    tokenId,
    tokenHash: hashToken(refreshToken),
    expiresAt: new Date(
      Date.now() + 7 * 24 * 60 * 60 * 1000
    ),
  });

  return {
    accessToken,
    refreshToken,
  };
}

Store a hash of the refresh token rather than the raw value. If the session table is compromised, the stored hash cannot be used directly as a valid token.

When a refresh token is used, revoke the existing session and issue a new token pair. This is known as refresh-token rotation.

Revoking a refresh session does not immediately invalidate an access token that has already been issued. The access token remains valid until its short expiry unless the API also checks server-side session state on every request.

3. Registration

Registration should hash the password and create related records inside a transaction:

import bcrypt from "bcryptjs";

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

    const passwordHash = await bcrypt.hash(
      password,
      12
    );

    const result = await withTransaction(
      async (client) => {
        const user = await insertUser(
          client,
          username,
          email,
          passwordHash
        );

        let team = null;
        let teamMember = null;

        if (isEventOrganiser) {
          team = await insertTeam(
            client,
            teamName,
            teamDescription
          );

          teamMember = await insertTeamMember(
            client,
            user.id,
            team.id,
            "team_admin"
          );
        }

        return {
          user,
          team,
          teamMember,
        };
      }
    );

    const tokens = await generateTokens(
      result.user
    );

    return res.status(201).json({
      status: "success",
      data: {
        user: {
          id: result.user.id,
          username: result.user.username,
          email: result.user.email,
        },
        ...tokens,
        ...(result.team && {
          team: result.team,
        }),
      },
    });
  } catch (error) {
    next(error);
  }
};

Allowing a user to become team_admin is safe only when the role applies to the new team they created. It must not grant global administrator access.

The database should also enforce unique usernames and emails:

ALTER TABLE users
ADD CONSTRAINT users_username_unique
UNIQUE (username);

ALTER TABLE users
ADD CONSTRAINT users_email_unique
UNIQUE (email);

Application-level checks alone cannot prevent duplicate records during concurrent requests.

4. Login

Return the same error whether the username or password is wrong:

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

    const user = await findUserByUsername(
      username
    );

    if (!user) {
      return res.status(401).json({
        status: "error",
        msg: "Invalid username or password",
      });
    }

    const passwordIsValid =
      await bcrypt.compare(
        password,
        user.password_hash
      );

    if (!passwordIsValid) {
      return res.status(401).json({
        status: "error",
        msg: "Invalid username or password",
      });
    }

    const tokens = await generateTokens(user);

    return res.json({
      status: "success",
      data: {
        user: {
          id: user.id,
          username: user.username,
          email: user.email,
        },
        ...tokens,
      },
    });
  } catch (error) {
    next(error);
  }
};

Different messages such as “username incorrect” and “password incorrect” allow attackers to determine which accounts exist.

5. Authentication Middleware

The authentication middleware verifies the access token and identifies its subject:

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

    if (!authHeader?.startsWith("Bearer ")) {
      return res.status(401).json({
        status: "error",
        msg: "Authentication required",
      });
    }

    const token = authHeader.slice(
      "Bearer ".length
    );

    const decoded = jwt.verify(
      token,
      JWT_SECRET,
      {
        algorithms: ["HS256"],
        issuer: ISSUER,
        audience: AUDIENCE,
      }
    );

    const userId = Number(decoded.sub);

    if (!Number.isInteger(userId)) {
      return res.status(401).json({
        status: "error",
        msg: "Invalid access token",
      });
    }

    req.user = {
      id: userId,
      username: decoded.username,
      email: decoded.email,
    };

    next();
  } catch (error) {
    return res.status(401).json({
      status: "error",
      msg:
        error instanceof Error &&
        error.name === "TokenExpiredError"
          ? "Access token expired"
          : "Invalid access token",
    });
  }
};

Verifying a JWT identifies the user represented by the token. It does not confirm that their role is still current.

Roles should therefore be checked against the database.

6. Team-Scoped Authorisation

A user may have different roles across different teams, so authorization should include both the user ID and team ID:

type TeamRole =
  | "team_admin"
  | "event_manager"
  | "team_member";

export const authorizeTeamRoles = (
  allowedRoles: TeamRole[]
) => {
  return async (req, res, next) => {
    try {
      if (!req.user) {
        return res.status(401).json({
          status: "error",
          msg: "Authentication required",
        });
      }

      const teamId = Number(
        req.params.teamId
      );

      const membership =
        await selectTeamMemberByUserAndTeam(
          req.user.id,
          teamId
        );

      if (
        !membership ||
        !allowedRoles.includes(
          membership.role
        )
      ) {
        return res.status(403).json({
          status: "error",
          msg: "Insufficient permissions",
        });
      }

      req.teamMembership = membership;
      next();
    } catch (error) {
      next(error);
    }
  };
};

Looking up a role using only the user ID is not enough in a multi-team application. A role held in one team must not grant access to another team’s resources.

7. Protecting Routes

Apply authentication and authorisation separately:

eventsRouter.post(
  "/teams/:teamId/events",
  authenticate,
  authorizeTeamRoles([
    "team_admin",
    "event_manager",
  ]),
  eventValidation,
  validateRequest,
  createEventHandler
);

The order is:

Verify the access token
Check the user’s role for the requested team
Validate the request body
Perform the operation

For update and delete routes, load the event first, determine which team owns it, and then check the user’s membership in that team.

Conclusion

This structure allows an Express API to:

Hash passwords securely
Issue short-lived access tokens
Rotate and revoke refresh sessions
Avoid storing raw refresh tokens
Identify users through JWT middleware
Check current roles against the database
Scope permissions to the relevant team
Return 401 for authentication failures and 403 for insufficient permissions

Authentication identifies the user. Authorisation determines whether that user can perform an action on a specific resource.

Keeping those responsibilities separate makes the system easier to understand and reduces the risk of accidentally exposing protected operations.

Managing Firebase Auth State with React Context in Next.js

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

Authentication state often needs to be available throughout an application. Navigation, profile settings, and authenticated UI may all need access to the currently signed-in user.

In this article, I’ll show how I use Firebase Authentication with React Context in a Next.js application to:

Make the current user available throughout the app
Wait for Firebase to restore the existing session
Handle authentication-based navigation
Read and update profile data in Firestore

Firebase Authentication handles session persistence. React Context simply makes the resolved authentication state available throughout the component tree.

This example uses Next.js App Router. The same Context approach can be used with Vite, but routing and provider placement may differ.

Creating the Auth Context

Create an auth context such as /context/AuthContext.tsx:

"use client";

import {
  createContext,
  useContext,
  useEffect,
  useState,
  type ReactNode,
} from "react";
import { onAuthStateChanged, type User } from "firebase/auth";
import { Loader2 } from "lucide-react";

import { auth } from "@/firebase/config";

type AuthContextValue = {
  user: User | null;
  loading: boolean;
};

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

export function useAuth() {
  const context = useContext(AuthContext);

  if (!context) {
    throw new Error("useAuth must be used within an AuthProvider");
  }

  return context;
}

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

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

  if (loading) {
    return (
      <div className="flex min-h-screen items-center justify-center">
        <Loader2
          className="animate-spin"
          size={24}
          aria-label="Checking authentication status"
        />
      </div>
    );
  }

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

onAuthStateChanged waits for Firebase to determine whether a session already exists. This prevents the application from treating the initial null value as a confirmed signed-out state.

The returned unsubscribe function also removes the listener when the provider unmounts.

Adding the Provider

Wrap your application with AuthProvider in the root layout:

import "./globals.css";

import type { Metadata } from "next";

import { AuthProvider } from "@/context/AuthContext";
import { ThemeProvider } from "@/components/ThemeProvider";
import Navbar from "@/components/Navbar";

export const metadata: Metadata = {
  title: "Firebase Auth with React Context",
  description: "Managing Firebase authentication state in Next.js",
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <AuthProvider>
          <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
            <Navbar />
            {children}
          </ThemeProvider>
        </AuthProvider>
      </body>
    </html>
  );
}

The suppressHydrationWarning property is commonly used with theme providers when server and client output may differ.

It suppresses the warning for an expected mismatch. It does not prevent hydration mismatches and is unrelated to Firebase Authentication.

Handling Auth-Based Navigation

Once Firebase has resolved the user state, a client component can redirect users based on their authentication status:

"use client";

import { useEffect } from "react";
import { useRouter } from "next/navigation";

import { useAuth } from "@/context/AuthContext";
import PromptLibrary from "@/components/PromptLibrary";

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

  useEffect(() => {
    if (!user) {
      router.replace("/auth");
      return;
    }

    if (!user.emailVerified) {
      router.replace("/verify-email");
    }
  }, [router, user]);

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

  return (
    <main className="min-h-screen">
      <PromptLibrary />
    </main>
  );
}

There is no need for an arbitrary timeout. The provider has already waited for Firebase to resolve the initial session.

Using router.replace also prevents the restricted route from remaining in the browser history.

Client Redirects Are Not Security

This redirect controls what the user sees, but it does not secure the underlying data.

Firestore documents, API routes, Server Actions, and other protected operations must perform their own authentication and authorisation checks.

For Firestore, this means using Security Rules.

Managing Firestore Profiles

Firebase Authentication stores basic information such as a display name, photo URL, and email address.

Additional profile data can be stored in Firestore:

import {
  doc,
  getDoc,
  serverTimestamp,
  setDoc,
  type DocumentData,
} from "firebase/firestore";

import { db } from "@/firebase/config";

type UserProfileUpdate = {
  displayName?: string;
  photoURL?: string;
  email?: string;
};

export async function getUserProfile(
  userId: string
): Promise<DocumentData | null> {
  const snapshot = await getDoc(doc(db, "users", userId));

  return snapshot.exists() ? snapshot.data() : null;
}

export async function updateUserProfile(
  userId: string,
  data: UserProfileUpdate
) {
  await setDoc(
    doc(db, "users", userId),
    {
      ...data,
      updatedAt: serverTimestamp(),
    },
    { merge: true }
  );
}

Using setDoc with { merge: true } creates the document if it does not exist or updates it without replacing unrelated fields.

It also avoids reading the document before every update.

serverTimestamp() is preferable to new Date() because it does not rely on the user’s device clock.

Updating a User Profile

You can update Firebase Authentication and Firestore from a profile form:

import { updateProfile, type User } from "firebase/auth";

async function saveProfile(
  user: User,
  displayName: string,
  photoURL: string
) {
  await updateProfile(user, {
    displayName,
    photoURL,
  });

  await updateUserProfile(user.uid, {
    displayName,
    photoURL,
    email: user.email ?? undefined,
  });
}

These are two separate requests, so one could succeed while the other fails.

The code attempts to keep both profiles aligned, but it cannot guarantee complete consistency. Production applications should decide which system is the source of truth and handle partial failures appropriately.

Email Verification

Use user.emailVerified for navigation and user messaging.

If a user verifies their email in another tab, reload the Firebase user before checking again:

await user.reload();

if (user.emailVerified) {
  router.replace("/");
}

Do not rely on a client-controlled Firestore field such as:

emailVerified: true

for security decisions.

Firestore Security Rules can use Firebase’s trusted authentication claim instead:

request.auth.token.email_verified

Basic Firestore Security Rules

A user profile should at least be restricted to its owner:

rules_version = "2";

service cloud.firestore {
  match /databases/{database}/documents {
    match /users/{userId} {
      allow read, create, update: if request.auth != null
        && request.auth.uid == userId;
    }
  }
}

Production rules may also need to restrict which fields users can update.

Conclusion

Firebase Authentication and React Context provide a straightforward way to share the current user across a Next.js application.

Firebase restores and maintains the session, while the context exposes that state to client components. From there, the application can handle navigation, authenticated UI, and profile forms without passing user data through multiple layers of props.

The important distinction is that client-side auth state controls the interface. Actual security must still be enforced through Firestore Security Rules and trusted server-side checks.

Restoring Chrome Bookmarks

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

Losing carefully organised Chrome bookmark folders can be frustrating, especially when an accidental deletion is quickly reflected across devices through Chrome’s bookmark syncing.

In this tutorial, I’ll explain the process I used to recover deleted bookmark folders manually using Chrome’s local backup file, Bookmarks.bak.

The method works on both macOS and Windows, provided the backup file still contains a version of your bookmarks from before they were deleted.

Important: Stop using Chrome as soon as you notice the deletion. Chrome may update or replace the backup file after further bookmark changes, so recovery is not guaranteed.

What You’ll Need

Access to your Chrome profile directory.
A Bookmarks.bak file containing the deleted bookmarks.
A temporary location where you can safely back up your existing bookmark files.
A little patience if you need to recover several individual folders.

General Overview

This method works by temporarily preventing Chrome from reconciling your local bookmarks with the version stored in your Google Account.

You restore the local backup while offline, copy the bookmark folder you want to recover, reconnect to the internet, allow Chrome to reload the current synced bookmark state, and then paste the recovered folder back into Bookmark Manager.

The main steps are:

Disconnect from the internet.
Quit Chrome completely.
Locate the correct Chrome profile folder.
Back up the existing Bookmarks and Bookmarks.bak files.
Replace the active Bookmarks file with a copy of Bookmarks.bak.
Open Chrome offline and confirm that the deleted folders are present.
Copy the folder you want to recover.
Reconnect to the internet and allow Chrome to update.
Paste the recovered folder back into Bookmark Manager.
Repeat for any additional folders.

Before You Begin: Find the Correct Chrome Profile

The examples below use Chrome’s Default profile directory.

However, if you use multiple Chrome profiles, your bookmarks may instead be stored in a folder named:

Profile 1
Profile 2
Profile 3

Before closing Chrome, open:

chrome://version

Look for the value labelled Profile Path. This shows the exact folder containing the bookmark files for your current profile.

Once you have noted the path, close Chrome completely before changing any files.

Detailed Steps for macOS

Prepare Your System

Turn off Wi-Fi or otherwise disconnect from the internet.
Quit Chrome completely.
Open Activity Monitor and confirm that no Google Chrome processes are still running.

Disconnecting prevents Chrome from immediately reconciling the restored local bookmark file with the bookmark state stored in your Google Account.

Locate Your Chrome Profile Folder

Open Finder.

From the menu bar, select:

Go → Go to Folder

For the default Chrome profile, enter:

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

If you use another profile, replace Default with the profile folder shown under chrome://version.

Inside the folder, look for:

Bookmarks
Bookmarks.bak

Back Up the Existing Files

Before changing anything, copy both files to another safe location, such as your Desktop:

Bookmarks
Bookmarks.bak

This gives you a way to restore the current state if the backup file is outdated, damaged, or does not contain the missing folders.

Restore the Bookmarks Backup

Rather than permanently deleting the current file:

Rename Bookmarks to something such as:

Bookmarks.current

Duplicate Bookmarks.bak.
Rename the duplicated file to:

Bookmarks

Make sure the copied file no longer has the .bak extension.

Launch Chrome Offline

With Wi-Fi still turned off, reopen Chrome.

Open Bookmark Manager by entering:

chrome://bookmarks

Check whether the deleted bookmark folders are visible.

If they are not present, the Bookmarks.bak file may already have been updated after the deletion.

Recover a Folder

Once you have confirmed that the deleted folders are present:

Select the bookmark folder you want to recover.
Copy it.
Reconnect to the internet.
Give Chrome a moment to reconcile the local bookmark state with your Google Account.
Return to Bookmark Manager.
Paste the copied folder into the desired location.

Repeat this process for each folder you need to restore.

Be careful not to copy anything else to your clipboard before pasting the recovered folder.

Detailed Steps for Windows

Prepare Your System

Turn off Wi-Fi or unplug your network cable.
Quit Chrome completely.
Open Task Manager using:

Ctrl + Shift + Esc

Confirm that no Google Chrome processes are still running.

Locate Your Chrome Profile Folder

Open File Explorer.

For the default Chrome profile, navigate to:

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

Replace [YourUsername] with your Windows account name.

If the AppData folder is not visible, enable hidden files from File Explorer’s View menu.

If you use multiple Chrome profiles, replace Default with the profile folder shown under:

chrome://version

Inside the profile folder, look for:

Bookmarks
Bookmarks.bak

Back Up the Existing Files

Copy both files somewhere safe before making any changes:

Bookmarks
Bookmarks.bak

For example, place copies in a temporary folder on your Desktop.

Restore the Bookmarks Backup

Rename the current Bookmarks file to:

Bookmarks.current

Copy the Bookmarks.bak file.
Rename the copied file to:

Bookmarks

Ensure that the .bak extension has been removed.

Launch Chrome Offline

While still disconnected from the internet, open Chrome.

Enter the following into the address bar:

chrome://bookmarks

Check whether the deleted folders have returned.

If they are missing, the backup may no longer contain the bookmark state from before the deletion.

Recover a Folder

If the folder is visible:

Select and copy the bookmark folder.
Reconnect to the internet.
Wait briefly for Chrome to update the bookmark state.
Return to Bookmark Manager.
Paste the recovered folder into the desired location.

Repeat these steps for each folder you need to restore.

Tips and Best Practices

Do Not Permanently Delete the Original Files

Rename or copy the existing files rather than immediately deleting them. This makes it easier to reverse the process if something goes wrong.

Act Quickly

The Bookmarks.bak file is not a permanent bookmark history. Chrome may update it after additional bookmark changes, so the deleted folders may eventually disappear from the backup as well.

Check the Correct Profile

Do not assume that your bookmarks are stored inside the Default folder. Use:

chrome://version

to confirm the exact profile path.

Consider Disabling Bookmark Sync Temporarily

Signing out or temporarily disabling bookmark syncing may reduce the chance of Chrome changing the bookmark state while you complete the recovery.

Make sure you understand what data is stored locally before changing any sync settings.

Export Your Bookmarks Afterwards

Once your bookmarks have been restored, open Bookmark Manager, select the three-dot menu, and choose:

Export bookmarks

Chrome will save your bookmarks as an HTML file that can be imported later.

Use System Backups

If Bookmarks.bak does not contain the missing folders, you may still be able to recover an older version using:

Time Machine on macOS.
File History or another backup service on Windows.
A full system or profile backup.

Conclusion

By restoring Chrome’s Bookmarks.bak file while offline, it may be possible to temporarily recover deleted bookmark folders before Chrome reloads the bookmark state stored in your Google Account.

From there, you can copy the required folders, reconnect to the internet, and paste them back into Bookmark Manager.

This method is not guaranteed to work because Chrome may update its backup file after a deletion. However, if the backup still contains the missing folders, it can provide a practical way to recover them without rebuilding everything manually.

Have you ever had to restore Chrome bookmarks manually? Share your experience or any additional recovery tips in the comments.

Building My First npm Package: A CLI for Scaffolding Backend Servers

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

Hello DEV Community! This is both my first npm package and my first DEV article.

After transitioning into full-stack development, I found myself repeating the same setup process whenever I started a new backend project: creating folders, configuring a database connection, adding environment variables, and setting up routes, controllers, and models.

I wanted to automate some of that repetitive work, so I created a CLI tool that scaffolds a backend application with a structured starting point and useful boilerplate.

In this post, I’ll walk through how I built my first npm package and how it can help reduce the time spent setting up a new project.

The Challenge

Many backend projects involve similar initial setup tasks, including creating routes, controllers, data models, database configuration, environment files, and error-handling utilities.

Without automation, developers can end up repeatedly copying boilerplate code or working through the same setup checklist for each project.

My CLI tool aims to reduce that repetition by generating a customisable project structure based on the framework, database, and language selected by the user. Developers still need to provision their database and provide their own credentials, but the initial application structure and connection code are generated for them.

Building the Package: Key Features

Here are some of the main features included in the tool:

Multiple database options: Scaffold a project using PostgreSQL, MySQL, SQLite, or MongoDB. Each template includes connection code and configuration suited to the selected database.
Generated configuration: The tool creates the project folders, database configuration, example environment variables, and starter application files. You still need to create or provision your database and provide the required credentials.
Layered project structure: Routes, controllers, models, database utilities, and error-handling logic are separated into clear folders, creating an MVC-inspired structure that is easier to navigate and maintain.
JavaScript and TypeScript support: Choose between JavaScript and TypeScript when generating your project.
Express and Hono support: Express templates are available across the supported databases, with Hono templates available for PostgreSQL projects.

How I Built It

I built the package using Node.js and used the prompts library to create an interactive command-line experience. Users can select their framework, database, language, and project configuration through a series of prompts.

The scaffolding approach was inspired by tools such as Vite, which generate projects from predefined templates. I followed a similar pattern by organising separate template folders for different framework, database, and language combinations.

The CLI uses minimist to parse command-line arguments. File operations, including copying templates and creating the generated project, are handled using Node.js file-system utilities and custom helper functions.

One of the main challenges was understanding how to reliably copy and transform the template files into the final generated project structure. I worked through this through experimentation, debugging, and repeated testing of the generated output.

Usage

To scaffold a new project, run:

npx create-mvc-server@latest

You can also provide the project name directly:

npx create-mvc-server@latest my-project

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

Enter a project name.
Choose a server framework.
Select a database:

PostgreSQL
MySQL
SQLite
MongoDB
1. Choose between JavaScript and TypeScript.
2. Confirm the selected configuration.

A generated project may include a structure similar to:

my-project/
├── __tests__/
├── controllers/
├── db/
├── errors/
├── models/
├── routes/
├── utils/
├── app.js
├── listener.js
├── endpoints.json
├── .env-example
└── package.json

The exact files and folders depend on the framework, database, and language selected.

After generation, you will still need to install or review the dependencies, provision your database where required, and add your own environment values.

Next Steps

The package is still evolving, and I plan to continue improving the available templates and generated boilerplate.

Possible future improvements include authentication templates, additional database configurations, more framework options, and stronger testing around the generated output.

I am also interested in exploring templates for other backend ecosystems, including Go-based HTTP servers, rather than limiting the project entirely to Node.js frameworks.

Conclusion

Building this package has been an educational introduction to creating CLI tools, managing project templates, and publishing packages to npm.

It has also helped me better understand command-line argument parsing, file-system operations, package configuration, and the challenges involved in generating reliable project structures.

I plan to continue improving the package and making it a more useful starting point for developers who want to reduce repetitive backend setup.

To try the package or contribute, you can visit the GitHub repository and share your feedback.

Your Feedback Matters

Do you have suggestions for improving the generated templates or ideas for additional features?

Contributions and feedback are welcome. You can find the source code on GitHub.

DEV Community: Terry W

Cursor Was Using 50GB of Memory - The Cause Was a Nested `.cursor` Folder

The Actual Cause

Why This Took So Long to Find

Quick Check

The Fix

The Lesson

Building My First Component Library: What Went Well, What Broke, and What AI Changed

Why I Started Building It

Why I Chose a Registry-Based Approach

Building Components Wasn't the Hard Part

What Broke

Architecture Lessons From a First-Time Build

What AI Actually Helped With

Where AI helped

Where AI needed guidance

The Biggest Thing I Learned

What's Next

Closing Thoughts

Fixing Playwright build errors on Render when browsers are missing

Background

Root Cause

The Fix That Worked

1. Install Chromium During postinstall

2. Use a Render Build Command

3. Configure the Browser Path

Why It Works

Missing Browser vs Missing System Libraries

Using Docker Instead

Extra Checks and Good Practices

Check the Installed Playwright Version

Log the Resolved Executable Path

Check the Installed Browsers

Monitor Disk Usage

Install Only What You Need

Install During Build, Not on Request

Checklist

Closing Notes

TL;DR

Fixing React Fast Refresh Issues in Vite by Splitting Your Auth Context

The Problem

The Fix

AuthContext.ts

AuthProvider.tsx

Why This Works

Takeaway

A Practical Guide to Writing Clear API Documentation

Introduction

What Is an API?

Why Good Documentation Matters

For API consumers

For API maintainers

Essential Parts of API Documentation

1. Introduction and Overview

2. Server and Base URLs

3. Authentication

4. Endpoint Groups

5. Method and Path

6. Description

7. Parameters

Path parameters

Query parameters

8. Request Bodies

9. Response Schemas

10. Error Responses

11. Pagination, Filtering, and Sorting

Advanced Documentation Tips

Use OpenAPI for Larger APIs

Define a Versioning Policy

Document Deprecations

Keep Documentation in Version Control

Best Practices I’ve Learned

Balance Completeness with Clarity

Show, Don’t Just Tell

Use Consistent Terminology

Keep Examples Safe

Quickly Copy cURL Requests

Maintain a Changelog

Conclusion

Express Authentication and Team-Scoped RBAC with JWTs

1. Install Chromium During `postinstall`

`AuthContext.ts`

`AuthProvider.tsx`