DEV Community: Msotafa Mohamed

Your skeleton screen is lying to your users

Msotafa Mohamed — Tue, 27 Oct 2026 07:00:00 +0000

Your skeleton screen is lying to your users.

It was drawn to match the card six months ago. Since then the card got a badge, a second line and a bigger avatar. The skeleton didn't. So the page jumps the moment the data arrives.

The usual fix is more work: keep a second layout in sync with the real one, forever. react-loadly 3.1 takes a different route with a new component called Skeletonize. Your real component becomes its own skeleton.

How it works

Wrap the real component and give it placeholder data. While loading is true, Skeletonize renders it as a skeleton:

import { Skeletonize } from "react-loadly";
import "react-loadly/styles.css";

const placeholderUser = { name: "Loading name", role: "Loading role", avatar: "" };

export function Profile() {
  const { data, isLoading } = useQuery({ queryKey: ["user"], queryFn: getUser });

  return (
    <Skeletonize loading={isLoading}>
      <UserCard user={data ?? placeholderUser} />
    </Skeletonize>
  );
}

Text, images, icons and form controls inside UserCard become skeleton blocks with the size and position of the real UI. Containers keep their background, borders and padding. If something else should become a block, add data-skeleton to that element.

Because the skeleton is the real component, there is no second layout to maintain. When someone adds a badge to the card, the skeleton gets the badge too, and there is no layout shift when the data arrives.

What you can tune

Skeletonize takes baseColor, highlightColor and speed, and can inherit them from a SkeletonGroupLoader. You can pick an animation (shimmer, wave, pulse or none) and set loadingLabel for the text screen readers hear.

Accessibility

While loading, the content is inert and aria-hidden. Screen readers hear one role="status" message instead of your placeholder text read out loud. Animations respect prefers-reduced-motion.

Works with the rest of your app

Children keep their state when loading toggles, so hooks and context behave normally. It works with Tailwind, SSR and the Next.js App Router, on React 17, 18 and 19 and Next.js 14, 15 and 16.

The rest of the package

react-loadly also has PulseLoader, SkeletonLoader, SkeletonGroupLoader and SkeletonSwitchLoader, which switches between loading, error, empty and content states.

Version 3.1 also fixes require() for CommonJS projects and makes the package much smaller. I wrote about how those bugs happened in another article.

Try it

npm install react-loadly

Try the live examples, and tell me where it breaks on GitHub.

Three bugs my npm packages shipped, and the checks that catch them now

Msotafa Mohamed — Mon, 26 Oct 2026 07:00:00 +0000

I maintain four small React libraries: react-loadly, accessly, compressly and tonely. This month I found three bugs in them that my own test suites never caught. They only showed up in other people's projects.

Here they are, with the check I now run before every publish.

1. The missing "use client"

The symptom. Someone imports <PermissionProvider> in a Next.js App Router layout and gets:

TypeError: createContext is not a function

The cause. In the App Router, every file is a Server Component unless it says otherwise. My React entry used createContext and hooks, but nothing in the published file marked it as client code. So Next.js ran it on the server, where those APIs don't exist.

The fix. The built file has to start with the directive:

"use client";

Putting it in your source isn't enough. Bundlers often merge modules and drop directives, and minifiers can strip them too. Add it as a banner in your bundler config (with terser, use format.preamble so it survives minification), and only on the entries that really need the client. Split anything that works without React into its own entry. For accessly that became accessly/core, which Server Components and Route Handlers can import safely.

The check.

head -c 20 dist/react/index.js   # must print "use client";

Then render a component from the package in a fresh create-next-app project, inside a server layout.

2. require() returned an empty object

The symptom. In Jest or an older SSR setup:

const { SkeletonLoader } = require("react-loadly"); // undefined

The cause. The package had "type": "module", and the CommonJS build was written to index.js. Node decides the format of a .js file from the nearest package.json, so it treated my CommonJS file as an ES module, and require() got nothing useful.

The fix. Give CommonJS files the .cjs extension and their types .d.cts, then point each condition at the right file:

"exports": {
  ".": {
    "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
    "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
  }
},
"main": "./dist/index.cjs"

The check.

node -e "console.log(Object.keys(require('./dist/index.cjs')))"
npx @arethetypeswrong/cli --pack .
npx publint

The first line must print your export names. The other two catch wrong types and wrong exports maps across node16, bundler and CommonJS resolution.

3. A 4 MB package for 4 kB of code

The symptom. No error at all, just a package that took 4 MB on every install.

The cause. Without a files field, npm publishes everything that isn't ignored. Mine included the docs site's images. Another package published a full copy of its type declarations in every subpath folder, which turned 32 files into 972.

The fix. An explicit allowlist:

"files": ["dist", "!dist/types", "AGENTS.md", "llms.txt"]

The check.

npm pack --dry-run

Read the file list every time. accessly went from 4 MB to 128 kB, and react-loadly from 972 files to 32.

The habit that ties it together

All three bugs lived in the gap between my repo and a real install. My tests imported the source. My users installed a tarball. So now, before every publish, I:

Run npm pack and install the .tgz into a scratch Next.js app and a scratch CommonJS project with Jest.
Render one component from a server layout, and require() the package from Jest.
Run publint and @arethetypeswrong/cli.- Read the npm pack --dry-run file list.

It takes ten minutes, and it would have caught every one of these.

A bonus for AI coding agents

While fixing these, I also added an AGENTS.md file to each package, with the exact API, when to use the library and the mistakes to avoid. Coding agents read it from node_modules, so they stop guessing method names. If you maintain a package, it's worth an afternoon.

The libraries, if you want to see the setup:

react-loadly: loaders, skeletons and the new Skeletonize
accessly: permissions for React and Next.js
compressly: image compression before upload
tonely: UI sounds without audio files

UI sounds without a single audio file

Msotafa Mohamed — Sun, 25 Oct 2026 07:00:00 +0000

Think of the apps that feel the most polished. Many of them make a small sound when a payment goes through, a message is sent or a switch flips. You don't notice the sound. You'd notice if it was missing.

On the web, most of us skip it. Adding sounds usually means finding .mp3 files, hosting them, preloading them, and dealing with browsers that block audio before the user interacts with the page.

tonely takes a different route. It doesn't ship audio files at all. It builds each sound when it plays, from oscillators and envelopes in the Web Audio API. The whole library is under 3 kB gzip and makes no network requests.

The basics

import { tonely } from "tonely";

tonely.success();
tonely.error();
tonely.click();
tonely.toggle(true); // rises for on, falls for off

The built-in sounds are success, error, warning, info, click, pop, toggle, delete, glass and bubble. There are five themes (modern, glass, minimal, playful and retro), and every call takes volume, pitch, playbackRate and theme:

tonely.setTheme("glass");
tonely.success({ volume: 0.6, pitch: 1.1 });

Sounds that follow your API

Most UI feedback is really "did that request work?". tonely can answer that from the HTTP status:

const res = await fetch("/api/orders", { method: "POST" });
tonely.fromStatus(res.status); // 2xx success, 3xx info, 4xx and 5xx error

Or wrap fetch once and forget about it:

const fetchWithSound = tonely.wrapFetch();
await fetchWithSound("/api/checkout");

If you already have a promise, tonely.track(promise) plays a sound when it settles and returns the same promise.

React and Next.js

"use client";
import { useTonely } from "tonely/react";

export function PayButton() {
  const { click, success, error } = useTonely({ theme: "glass" });

  return (
    <button
      onClick={async () => {
        click();
        try {
          await pay();
          success();
        } catch {
          error();
        }
      }}
    >
      Pay
    </button>
  );
}

On the server, every call is a safe no-op, so importing tonely in shared code won't break SSR. Version 0.1.1 also ships tonely/react with a "use client" directive, so it works in App Router files without extra setup.

Toasts with sound

If you use Sonner or shadcn/ui toasts, a small wrapper gives every toast a matching sound:

import { toast as base } from "sonner";
import { tonely } from "tonely";

export const toast = {
  success: (m: string) => { tonely.success(); return base.success(m); },
  error: (m: string) => { tonely.error(); return base.error(m); },
};

Use sound with care

Sound is easy to overdo. A few rules I follow:

Play sounds for outcomes (saved, paid, failed), not for every hover or keystroke.
Always offer a mute switch. tonely.setMuted(true) silences everything, so it's one line to wire up to a setting.
Never use sound as the only feedback. Someone with the sound off still needs to see that it worked.
Browsers only allow audio after the user has interacted with the page, so trigger sounds from event handlers.

Try it

npm install tonely

You can hear every sound and theme on the demo site. It works with React, Next.js, Vue, Svelte or plain JavaScript. Ideas for new sounds are welcome on GitHub.

Compress images in the browser before you upload them

Msotafa Mohamed — Sat, 24 Oct 2026 07:00:00 +0000

A modern phone photo is 4000 pixels wide and several megabytes. Your avatar slot is 128 pixels. Your product gallery shows images at 1600 pixels at most.

Most apps upload the full photo anyway, then resize it on the server. On a slow mobile connection, the user waits for megabytes they will never see, and you pay for the bandwidth and storage.

The browser can do the resizing itself before the upload starts. That's what compressly does.

The basic case

import { compressImage } from "compressly";

async function upload(file: File) {
  const small = await compressImage(file, {
    maxWidth: 1600,
    quality: 0.8,
    targetSizeMB: 0.5,
    mimeType: "image/webp",
  });

  const body = new FormData();
  body.append("photo", small);
  await fetch("/api/upload", { method: "POST", body });
}

compressImage returns a regular File, so the rest of your upload code doesn't change.

The details that usually go wrong

Sideways photos. Phones often store the camera orientation in EXIF data instead of rotating the pixels. Draw that image on a canvas naively and it comes out sideways. compressly reads the orientation and rotates the image first (autoRotate, on by default).

A frozen page. Decoding and re-encoding a large image takes time. compressly uses a Web Worker with OffscreenCanvas where the browser supports it, so the page keeps scrolling and the progress bar keeps moving.

Hitting a size limit. If your storage or API has a hard limit, pass targetSizeMB and compressly makes up to four passes, lowering the quality and then the dimensions, to get under it.

Small files. Files already under maxSizeMB (1 MB by default) and within the max dimensions are returned as they are, so you don't lose quality for nothing. Pass forceResize: true if you always want the max dimensions applied.

Showing the user what happened

import { compressImageWithDetails } from "compressly";

const result = await compressImageWithDetails(file, { maxWidth: 1600 });
console.log(result.originalSize, result.compressedSize, result.reductionPercentage);

You also get timeTakenMs and the final dimensions, which makes a nice "saved 87%" label.

Many files at once

import { compressImages } from "compressly";

const files = await compressImages(Array.from(input.files), {
  concurrency: 3,
  maxWidth: 1600,
  onBatchProgress: (percent, done, total) => console.log(`${done}/${total}, ${percent}%`),
});

Keep concurrency around 2 to 4 on phones, where memory is the limit.

React

"use client";
import { useImageCompressor } from "compressly/react";

export function AvatarInput({ onReady }: { onReady: (file: File) => void }) {
  const { compress, isCompressing, progress } = useImageCompressor({ maxWidth: 512, quality: 0.85 });

  return (
    <>
      <input
        type="file"
        accept="image/*"
        disabled={isCompressing}
        onChange={async (e) => {
          const file = e.target.files?.[0];
          if (file) onReady((await compress(file)).file);
        }}
      />
      {isCompressing && <progress value={progress} max={100} />}
    </>
  );
}

Version 0.1.1 ships the React entry with a "use client" directive, so it works in Next.js App Router files without extra setup.

One thing it doesn't do

Client-side compression saves bandwidth and makes uploads faster. It isn't a security check, because anyone can skip your JavaScript and upload directly. Keep validating file type and size on the server.

Try it

npm install compressly

It has zero dependencies and is about 2 kB gzip. Try it with your own photos on the demo site, and open an issue on GitHub if an image comes out wrong.

Permissions in React that explain themselves

Msotafa Mohamed — Fri, 23 Oct 2026 07:00:00 +0000

Every app with roles ends up with the same support ticket: "I can't see the Refund button."

Then someone opens the code and starts reading. Is it the role? A missing permission? A feature flag? Is the permission list still loading? The UI just shows nothing, and nothing tells you why.

I built accessly to make that question take seconds. It's a small permissions layer for React and Next.js, and every check returns a decision with a reason.

A check that answers "why"

import { checkPermission, formatDecision } from "accessly/core";

const access = { user: { id: "u_1", roles: ["support"] }, permissions: ["tickets.view"] };
const rolePermissions = { admin: ["*"], support: ["tickets.*", "users.view"] };

const decision = checkPermission(access, { permission: "payments.refund" }, { rolePermissions });
console.log(formatDecision(decision));

Allowed: false
Reason: missing_permission
Requested: payments.refund
Missing: payments.refund
Checked from: none

And when a check passes, it tells you which rule let it through:

Allowed: true
Reason: allowed
Requested: tickets.close
Matched: tickets.*
Checked from: role

The reason is one of allowed, missing_permission, missing_flag, unknown_permission, not_ready or invalid_request. That last pair matters more than it looks. While permissions are still loading, a check returns not_ready instead of a plain false, so you can show a spinner instead of flashing an "Access denied" page.

The React side

Wrap the app once with the current user's access:

"use client";
import { PermissionProvider } from "accessly";

export function Providers({ session, children }) {
  return (
    <PermissionProvider
      access={{
        user: { id: session.user.id, roles: session.user.roles },
        permissions: session.permissions,
        flags: session.flags,
      }}
      rolePermissions={{ admin: ["*"], editor: ["posts.*"] }}
    >
      {children}
    </PermissionProvider>
  );
}

Then gate UI with components or hooks:

import { Can, usePermissions, useAccessDecision, formatDecision } from "accessly";

<Can permission="posts.delete" fallback={null}>
  <button>Delete</button>
</Can>

const { canEdit, canPublish } = usePermissions({
  canEdit: "posts.edit",
  canPublish: { all: ["posts.edit", "posts.publish"] },
});

const refund = useAccessDecision("payments.refund");
if (!refund.allowed) console.debug(formatDecision(refund));

Permissions are dot-separated strings. Wildcards work per segment: users.* matches users.create but not users.profile.edit, and * matches everything. A check can be a single permission, { any: [...] }, { all: [...] } or { flag: "..." }.

New in 0.2: the same rules on the server

The main accessly entry is React. Until 0.2, that meant you couldn't reuse your rules in a Server Component or a Route Handler. Now there is accessly/core, with no React import at all:

// app/api/refunds/route.ts
import { createAccessChecker } from "accessly/core";

export async function POST(req: Request) {
  const session = await getSession(req);
  const access = createAccessChecker(session.access, { rolePermissions });

  if (!access.can("payments.refund")) {
    return new Response("Forbidden", { status: 403 });
  }
  // ...
}

It also has filterNavigation, which takes your menu items and returns only the ones the user can open. That way the sidebar and the route guard use the same rules.

What it is not

accessly controls what your UI shows. It doesn't replace authorization on your API, so keep enforcing permissions on the server too. With accessly/core you can at least use the same rule definitions in both places. It also isn't a policy engine for conditions like "only the author can edit their own post". For that, use CASL or a dedicated policy engine.

Try it

npm install accessly

It has zero dependencies and is about 4 kB gzip. The docs cover adapters for different backend shapes, ProtectedRoute, and debugging with inspectAccess. Issues and ideas are welcome on GitHub.

Stop Writing Clunky if/else Checks: Scalable Access Control (RBAC) in React & Next.js

Msotafa Mohamed — Sun, 11 Oct 2026 17:05:00 +0000

Building enterprise web applications or multi-tenant SaaS dashboards almost always leads to a complex challenge: Role-Based Access Control (RBAC).

As applications grow, embedding raw conditional statements like if (user.role === 'admin') directly inside UI components rapidly creates technical debt. It scatters authorization logic across your codebase, making audits and policy changes a maintenance nightmare.

To solve this, I built Accessly — a lightweight, zero-dependency access-control library built for React and Next.js applications.

Key Architecture Highlights:

Declarative Control: Clean UI components ( / ) to conditionally render elements based on permissions.

Wildcard Matching: Support for granular permissions like reports:* or users:delete without manual mapping.

Explainable Authorization: Built-in .explain() decisions so developers can instantly debug why a user was allowed or denied access during runtime.

Framework Agnostic Foundations: Seamlessly integrates with SSR, Next.js Middleware, and App Router.

https://www.npmjs.com/package/accessly

https://accessly-website.vercel.app/

javascript, #react, #webdev, #opensource, #architecture

How Web Workers & OffscreenCanvas Made Client-Side Image Compression 10x Faster

Msotafa Mohamed — Sun, 11 Oct 2026 07:04:25 +0000

Allowing users to upload uncompressed 15MB smartphone photos directly to your cloud storage destroys bandwidth, increases server costs, and delivers a sluggish User Experience (UX).

Traditional client-side compression libraries execute heavy pixel manipulations on the Main Thread, freezing the DOM and causing noticeable UI lag.

To address this performance bottleneck, I created Compressly — a zero-dependency, micro-sized (<3KB) image compression library that offloads processing away from the main thread.

How It Works Under the Hood:

Web Worker Offloading: Offloads heavy mathematical image transformations to a background Web Worker thread, keeping the main thread running smoothly at 60 FPS.

OffscreenCanvas API: Utilizes hardware-accelerated canvas rendering directly inside worker threads without DOM dependencies.

Smart Formatting: Auto-converts heavy JPEGs/PNGs into optimized WebP formats while preserving EXIF orientations.

Performance Impact:

File Reduction: Converts a 14.2 MB raw smartphone photo down to ~380 KB in under 800ms.

Main Thread Blocking: 0ms (completely asynchronous).


TypeScript

import { compressImage } from 'compressly';

const optimizedFile = await compressImage(file, {
  quality: 0.8,
  maxWidth: 1920,
  convertFormat: 'webp',
});

Offload compression to the client without sacrificing frame rates.

🔗 Try Compressly on npm: npmjs.com/package/compressly

javascript, #react, #webdev, #opensource, #architecture

Eliminating Layout Shifts: Modern Skeleton Loaders and Deferred UI States in React

Msotafa Mohamed — Sun, 11 Oct 2026 07:00:27 +0000

A poor loading experience directly harms user retention. Replacing sudden layout shifts or generic full-screen spinners with subtle, skeleton placeholders improves perceived application performance by up to 40%.

However, implementing skeleton loaders often introduces subtle bugs, such as UI flickering when API responses resolve too fast (e.g., under 100ms).

I built React Loadly to provide a production-ready toolkit for managing complex loading states, skeleton screens, and fluid transitions in React.

Core Features:

Zero-Flicker Hooks: useDeferredLoading delays skeleton displays until an API request exceeds a specified threshold (e.g., 200ms), eliminating jarring UI flashes on fast connections.

Accessible Skeletons: Built-in ARIA support (aria-busy, aria-live) to ensure accessibility for screen readers.

Adaptive Theme Support: Automatic dark/light mode adaptations with customizable pulse and wave animations.

TypeScript

import { Skeleton, useDeferredLoading } from 'react-loadly';

function UserProfile({ isLoading, data }) {
const showSkeleton = useDeferredLoading(isLoading, { delay: 200 });

if (showSkeleton) return ;
return ;
}

Upgrade your application's loading experience effortlessly.

🔗 Explore React Loadly on npm: npmjs.com/package/react-loadly

javascript, #react, #webdev, #opensource, #architecture

Synthesizing Procedural UI Micro-Interactions via the Web Audio API

Msotafa Mohamed — Sun, 11 Oct 2026 06:59:21 +0000

Tactile, auditory feedback significantly elevates web user interactions—think of the subtle "click" of a button, the crisp notification pop, or a success chime on task completion.

However, loading external audio assets (MP3s/WAVs) introduces extra HTTP requests, network latency, and browser autoplay restriction headaches.

I developed Tonely to synthesize UI micro-interaction sound effects procedurally in real-time directly inside the browser using the native Web Audio API—requiring zero external audio files.

Why Procedural Audio?

Zero Asset Overhead: No MP3 downloads, no asset hosting, and zero network latency.

Instantaneous Playback: Synthesized instantly via Web Audio Oscillators for 0ms trigger latency.

Microscopic Footprint: Adds virtually no bundle size to your application.

Global Mute & Pitch Controls: Easily configurable volume and pitch controls to respect user preference settings.

TypeScript

import { tonely } from 'tonely';

// Trigger subtle UI feedback on button click
const handleButtonClick = () => {
tonely.play('pop');
};

// Trigger procedural success chime
const handleFormSubmit = () => {
tonely.play('success');
};

Add tactile polish to your web applications without fetching a single audio file.

🔗 Discover Tonely on npm: npmjs.com/package/tonely

javascript, #react, #webdev, #opensource, #architecture