Forem: Mohamed Idris

Stop Fighting Your AI About shadcn Components: Install the Skill

Mohamed Idris — Sun, 03 May 2026 11:21:29 +0000

If you use Cursor, Claude Code, GitHub Copilot, or any AI coding assistant with shadcn/ui, you probably hit this wall:

You ask the AI to add a Combobox using Base UI. It generates code with asChild. But Base UI does not have asChild, it uses render. You correct it. Next prompt, same mistake. You correct again. The cycle never ends.

Or you ask for "a login form with shadcn". The AI invents components that don't exist in your registry, or it imports from @radix-ui/react-dialog when your project uses Base UI.

The reason is simple: the AI does not know your project. It has no idea which framework you use, which components you already installed, which engine (Radix or Base UI) you picked, or how shadcn's APIs evolved this year. It guesses based on training data that might be a year old.

There are two tools that fix this. Let me walk you through both.

Tool 1: The shadcn skill

A skill is a small bundle of instructions and helpers that gets injected into your AI assistant's context whenever you work in a project. The shadcn skill specifically tells your AI:

which framework you use (Next.js, Vite, Remix, Astro, etc.)
which components are already installed in your project
which engine you chose (Radix or Base UI)
the correct, current API patterns

Behind the scenes, the skill activates when it sees a components.json file in your project, runs shadcn info --json, and feeds the result to your assistant. So instead of guessing, the AI reads your actual setup.

How to install the skill

In your project root, run:

pnpm dlx skills add shadcn/ui

Or if you use npm, yarn, or bun:

npm dlx skills add shadcn/ui
yarn dlx skills add shadcn/ui
bun dlx skills add shadcn/ui

That is it. Restart your AI editor, and now when you ask it for a component, it knows your context.

What changes after you install it

Before the skill, you would write:

"Add a button using shadcn"

And get something close, but maybe wrong import, maybe outdated API, maybe a component you didn't install yet.

After the skill, you can write things like:

"Add a login form with email and password and a submit button"

"Build a dashboard page with a sidebar, three stat cards, and a data table"

"Create a settings page where the user can update their profile"

And the AI generates code that uses exactly the components in your project, with the correct API for the engine you picked.

This is what fixes the asChild vs render problem mentioned earlier. The skill tells the AI "this project uses Base UI, use render", and the AI listens.

Tool 2: The shadcn MCP server

The skill is great for context, but it does not add new components for you. That is what the MCP server does.

MCP stands for Model Context Protocol. It is a standard that lets AI assistants talk to external tools and services. The shadcn MCP server gives your AI a direct connection to component registries (the official shadcn registry, plus any custom ones you add).

With it installed, the AI can:

search across thousands of blocks and components
preview a component before installing
actually run the install command for you

Install for Claude Code

In your project root:

pnpm dlx shadcn@latest mcp init --client claude

After it finishes, restart Claude Code and run /mcp to confirm the shadcn server shows up.

Install for Cursor

Add the shadcn server to .cursor/mcp.json in your project. Check the shadcn MCP docs for the exact JSON since the format updates.

Install for VS Code with GitHub Copilot

Add the shadcn server to .vscode/mcp.json in your project.

What changes after you install it

You can ask:

"Show me all available components in the shadcn registry"

"Add the button, dialog, and card components to my project"

"Find me a pricing page block"

And it just works. No more "what is the install command for X again", no more searching the docs in another tab.

Skill or MCP, which one do I need?

Honestly, install both. They solve different problems:

	Skill	MCP server
Knows your project setup	yes	partial
Generates correct API code	yes	yes (via registry)
Can install new components for you	no	yes
Searches registries	no	yes

The skill is "give my AI context about my project". The MCP server is "give my AI hands to actually do registry stuff". Together they make your AI feel like it actually works on your team.

A real example

Here is the difference in practice. Junior dev has a Base UI shadcn project, and asks the AI:

Without skill or MCP:

import { Dialog } from '@radix-ui/react-dialog';

<Dialog.Trigger asChild>
  <Button>Open</Button>
</Dialog.Trigger>

Wrong import (project uses Base UI, not Radix), and asChild does not exist in Base UI. The dev now spends 10 minutes fixing it.

With skill installed:

import { Dialog } from '@/components/ui/dialog';

<Dialog.Trigger render={<Button>Open</Button>}>
  Open
</Dialog.Trigger>

Correct import path, correct API. Zero fighting.

Quick troubleshooting

A few things that bit me when I tried this:

The skill needs components.json in your project. If you never ran shadcn init, the skill has nothing to read. Run pnpm dlx shadcn@latest init first.
Restart your AI editor after install. Hot reload does not pick up new skills or MCP servers.
Check /mcp in Claude Code to confirm the server is connected. If it is not, the install probably failed silently. Run it again and watch the output.

Final thought

The first time AI auto installs the right shadcn component, with the right API, on the right engine, it feels like cheating. It is not cheating, it is just giving the AI the same context a human team member would have.

If you are on shadcn/ui in 2026 and your AI is still generating wrong code, you are working with one hand tied behind your back. Spend 5 minutes installing the skill. Future you will thank you.

shadcn vs Radix vs Base UI: Which One Should a Junior Pick in 2026?

Mohamed Idris — Sun, 03 May 2026 11:20:16 +0000

If you spent any time on React Twitter or LinkedIn lately, you saw three names everywhere: shadcn/ui, Radix, and Base UI. People talk about them like they compete with each other, but they don't really. Let me explain what each one actually is, and when you should reach for which.

First, what is a "headless" UI library?

Before we compare anything, you need this idea.

A normal UI library like Bootstrap or Material UI gives you components that already look a certain way. You import a <Button> and it comes with colors, padding, hover effects, the full package. You can override the styles, but you are fighting the library.

A headless library does the opposite. It gives you the behavior of a component (open and close, keyboard navigation, focus management, accessibility) without any styling at all. You bring your own CSS. You decide how it looks.

Think of it like this: a headless library is the engine of a car. shadcn, Bootstrap, MUI are full cars. You can swap the engine, but the car already has paint.

This is important because the boring part of building a UI is not the colors. It is making a dropdown that closes when you press Esc, returns focus to the right place, traps focus in a modal, supports arrow keys in a menu, and works with screen readers. That stuff is HARD. Headless libraries solve it once so you don't have to.

Radix UI

Radix is a headless library by the team behind WorkOS (they bought Radix). It gives you primitives like <Dialog>, <DropdownMenu>, <Tabs>, and so on, fully accessible, no styles.

It became the default choice in the React ecosystem over the past few years. Vercel, Linear, Supabase, and a huge chunk of modern apps use it under the hood.

Why people love it:

battle tested, used in millions of production apps
great accessibility out of the box
clean API with the asChild pattern (more on this below)

The honest downside:

Updates have slowed down a lot since the WorkOS acquisition. Many devs feel it has reached its peak and won't get major new features. It is stable, but stable can mean "frozen".

Base UI

Base UI is the new kid, started in 2024 by people from Radix, MUI, and Floating UI (so basically the dream team of headless React). It is also a headless primitives library, very similar API to Radix, but with some upgrades.

Why people are excited:

actively developed (7+ engineers shipping new releases regularly)
ships components Radix doesn't have, like Combobox and Autocomplete
better focus on performance and tiny modern a11y wins (for example, accordions automatically open when the user does Ctrl+F to search hidden text)
API is close enough to Radix that migrating is mostly find and replace

The honest downside:

Newer means smaller community, fewer Stack Overflow answers, and your AI assistant might not know it as well (we will fix that in the next post).

The asChild vs render difference

This is one of the few API differences worth knowing.

Radix uses asChild:

import * as Dialog from '@radix-ui/react-dialog';

<Dialog.Trigger asChild>
  <button className="my-custom-button">Open</button>
</Dialog.Trigger>

The asChild tells Radix: "don't render your own element, merge your behavior into my child instead".

Base UI uses render:

import { Dialog } from '@base-ui-components/react/dialog';

<Dialog.Trigger render={<button className="my-custom-button">Open</button>}>
  Open
</Dialog.Trigger>

Same idea, different shape. Base UI's render prop is a bit more flexible because you can also pass a function for full control.

shadcn/ui

Now the third name. shadcn/ui is not a headless library. It is also not really a library at all in the npm sense.

It is a collection of pre-styled, copy paste components built on top of Radix or Base UI, using Tailwind CSS. When you want a Button or Dialog, you run a CLI command and it copies the component code directly into your project.

pnpm dlx shadcn@latest add button

You now own that component. You can edit it, delete props, add variants. There is no node_modules/shadcn-ui to fight with.

Why this changed everything:

you get gorgeous defaults that you can fully customize because the code is yours
a11y is handled by the underlying Radix or Base UI primitive
you don't carry the weight of components you never use

Big news from late 2025:

shadcn/ui now supports both Radix and Base UI as the underlying engine. When you start a project, you pick one. Every component was rebuilt for Base UI while keeping the same API.

So what should you actually pick?

Here is my honest junior friendly advice:

If you are starting a new project today:

Use shadcn/ui with Base UI. You get pretty defaults you control, accessibility for free, and you are betting on the library that is actively growing instead of the one that is frozen.

If you are joining an existing team:

Use whatever they already use. If it is Radix, don't migrate just because Base UI is trendy. Radix in production today is fine. It works.

If you need a component Radix doesn't have:

Like Combobox or Autocomplete, just go with Base UI. You will save yourself a week of building it from scratch.

If you want a fully styled out of the box library:

Then you don't want any of these three. Look at MUI, Mantine, or Chakra. shadcn, Radix, and Base UI all assume you are styling things yourself with Tailwind or CSS.

A simple decision tree

Need full control over styles?
├── Yes
│   └── Want a copy paste starter with nice defaults?
│       ├── Yes → shadcn/ui (pick Base UI as the engine)
│       └── No → Base UI directly (or Radix if your team uses it)
└── No → MUI, Mantine, or Chakra

Final thought

The whole "Radix vs Base UI" debate online is loud, but in practice the difference is small for a junior. Both give you accessible, headless primitives. Both work great. Base UI is the safer long term bet because the team is shipping, but you cannot go wrong with either.

The real win is just stopping yourself from building a custom modal from scratch in 2026. That is the bug.

Web Accessibility (A11y) for Juniors: What It Is and Why It Matters

Mohamed Idris — Sun, 03 May 2026 11:18:36 +0000

You probably saw the word a11y on Twitter, in a job post, or in a code review comment, and wondered what it actually means. So let me explain it the way I wish someone explained it to me when I started.

What is A11y?

A11y is a short way of writing accessibility. The number 11 is just the count of letters between the a and the y in the word accessibility. That is it. No hidden meaning.

Accessibility means building websites and apps that everyone can actually use, including people who:

can't see well or can't see at all and use a screen reader
can't use a mouse and only navigate with the keyboard
have low color vision and can't tell red from green
have motor issues and can't click tiny buttons
are on a slow phone, in bright sunlight, or in a noisy room

So a11y is not a "feature for blind users". It is just good engineering that respects how different humans interact with your UI.

Why should you care as a junior?

Three honest reasons:

1. It is the law in many places. In the EU, the European Accessibility Act started applying in 2025. In the US, the ADA Title II deadline hits in April 2026 for public sector sites. Big clients will not hire teams that ship inaccessible products.

2. Better a11y means better UX for everyone. Captions help deaf users, but they also help anyone watching a video on the bus without headphones. Keyboard support helps blind users, but it also helps power users who hate touching the mouse.

3. It makes you stand out. Most juniors do not know a11y. If you do, you are already different from 80% of the candidates applying to the same job.

The 4 principles (POUR)

WCAG (the official accessibility guidelines, currently version 2.2) groups everything under 4 ideas. The acronym is POUR:

Perceivable: users can sense the content (with eyes, ears, or fingers)
Operable: users can interact with it (mouse, keyboard, touch, voice)
Understandable: users can read it and predict what happens next
Robust: it keeps working in different browsers and assistive tech

Don't memorize this. Just remember: if a real human can't perceive, operate, understand, or rely on your UI, you have an a11y problem.

Real examples you can fix today

Let me show you the most common mistakes I see in junior code, and the fix.

1. Using `div` for buttons

This looks fine in the browser, but a screen reader will not announce it as a button, and you can't reach it with the Tab key.

<!-- bad -->
<div class="btn" onclick="submit()">Save</div>

<!-- good -->
<button type="button" onclick="submit()">Save</button>

The native <button> gives you keyboard focus, Enter and Space activation, and the right ARIA role for free. You get all that by typing 4 letters less. Use it.

2. Images with no alt text

<!-- bad -->
<img src="profile.jpg" />

<!-- good -->
<img src="profile.jpg" alt="Mohamed smiling at his graduation" />

<!-- also good if the image is just decoration -->
<img src="sparkle.svg" alt="" />

Empty alt="" is not lazy, it is correct for decorative images. It tells screen readers to skip them. Missing alt completely is the bug.

3. Form inputs with no label

<!-- bad -->
<input type="email" placeholder="Email" />

<!-- good -->
<label for="email">Email</label>
<input id="email" type="email" />

Placeholders disappear when the user types and they are usually low contrast. A real <label> stays, gets read by screen readers, and lets the user click the label to focus the input.

4. Color as the only signal

Look at this error message:

<p style="color: red">Email is invalid</p>

A user with color blindness might not see the red at all. Add an icon or text:

<p style="color: red">
  <span aria-hidden="true">✗</span> Email is invalid
</p>

5. Low contrast text

Light grey text on white looks "clean and minimal" but it is unreadable for many users. WCAG asks for a contrast ratio of at least 4.5:1 for normal text. Use a tool like WebAIM Contrast Checker or your browser DevTools to check.

6. Custom components without keyboard support

If you build a custom dropdown, modal, or tabs component, ask yourself:

Can I open and close it with only the keyboard?
Does Tab move focus in a logical order?
Does Esc close the modal?
Does focus return to the trigger button when the modal closes?

If the answer to any of these is no, your component has a bug. This is exactly why headless libraries like Radix and Base UI exist. They handle this for you (more on that in another post).

Tools that will save you

You don't have to memorize WCAG. Use tools.

axe DevTools browser extension: scans your page and lists violations with fixes
Lighthouse (built into Chrome): gives you an a11y score
VoiceOver (Mac, Cmd+F5) or NVDA (Windows, free): try using your own site with eyes closed for 60 seconds. Trust me, you will feel every bug
Tab key: just press Tab through your page. If focus disappears or jumps around weirdly, you have an issue

A simple checklist before you ship

[ ] Every image has alt (or alt="" if decorative)
[ ] Every form input has a real <label>
[ ] You can use the whole page with only the keyboard
[ ] Focus is always visible (don't kill the focus ring with outline: none and nothing else)
[ ] Color contrast is 4.5:1 or higher for text
[ ] Headings go in order (h1, then h2, then h3, no skipping)
[ ] Buttons are <button>, links are <a>. Don't mix them up

Final thought

A11y is not a separate phase you do at the end. It is part of writing good HTML. Most of the fixes above cost you nothing extra and take 10 seconds. Start with semantic HTML, test with your keyboard, and you are already ahead of most devs.

In the next post I will show how libraries like Radix, Base UI, and shadcn handle the harder a11y patterns for you, so you don't have to reinvent a focus trap every time you build a modal.

A No-Build Markdown Site for Study Notes (or any docs)

Mohamed Idris — Fri, 01 May 2026 16:59:15 +0000

I needed a way to study a stack of notes I had written for a job interview. Eight markdown files, plus some code examples, plus a couple of reference pages. I wanted to read them in a browser with a sidebar, dark mode, and clickable navigation between files. But I did not want to install a static site generator, run a dev server, or maintain a build pipeline for what is basically a personal study folder.

So I built a single-page viewer in one HTML file that reads the markdown directly. The whole site is one index.html plus the markdown files. You open the HTML in a browser, it fetches the markdown, renders it with marked, and you have a real navigable site.

This post walks you through the whole pattern. By the end you will be able to drop the same setup into any folder of notes you want to read like a website.

What we are building

A folder that looks like this:

my-notes/
├── README.md
├── index.html
├── docs/
│   ├── 01-introduction.md
│   ├── 02-setup.md
│   └── 03-deeper-topics.md
└── code-examples/
    └── hello.ts

When you open index.html in a browser you get a sidebar on the left listing every doc, and the rest of the page renders the selected markdown file with code highlighting, tables, and proper typography. Click a link in the sidebar, the URL changes to index.html#docs/02-setup.md, and the content swaps. No page reload, no build step, no node_modules.

Why this approach

Most "docs as code" setups are heavier than they need to be for a small personal project. They assume you want a public site, search, versioning, or a custom theme. For a study folder or a small team handbook, you do not need any of that. You need:

Markdown files you can edit in any editor.
A way to read them in a browser without typing cat file.md in a terminal.
Navigation between files that does not require remembering which folder you are in.
Something that works the same on Windows, macOS, and Linux.

A single HTML file that renders markdown gives you all four. It is also harder to break than a tooling chain, because there is almost nothing to break.

The folder structure

Before the code, let us talk about the organising principles. The exact names do not matter; what matters is the pattern.

One README at the top, as an index

The top-level README.md is not the first chapter. It is a table of contents. Its job is to tell a new reader where to start and what each file contains.

A good index README has:

A one-paragraph description of what this folder is.
A small table linking each file with a short hook ("what you will learn") and an estimated reading time.
Maybe a "TL;DR" if you only have ten minutes.

Here is a snippet of what mine looks like:

## Read in this order

| # | Document | What you'll learn | Time |
|---|----------|-------------------|------|
| 1 | [Introduction](docs/01-introduction.md) | What this is for | 5 min |
| 2 | [Setup](docs/02-setup.md) | How to install everything | 10 min |
| 3 | [Deeper topics](docs/03-deeper-topics.md) | The interesting bits | 25 min |

A reader who lands on the folder for the first time can immediately tell where to go.

Numbered file names for ordering

Notice the 01-, 02-, 03- prefixes. They serve two purposes:

The OS sorts the files alphabetically, so the reading order is also the file-listing order.
The number is a stable handle. You can refer to "doc 04" in conversation and find it instantly.

If you later want to insert a new file between 02 and 03, name it 02b-... or just renumber. Renumbering is annoying but rare in practice.

Group by purpose, not by file type

I see a lot of folders where everything goes in /docs/ because it is markdown. That is fine when you have five files. When you have twenty it stops being fine.

Group by what the content does for the reader, not by file extension:

my-notes/
├── docs/             <- the actual narrative documents
├── code-examples/    <- runnable snippets the docs reference
├── reference/        <- looked-up not read-through (glossary, cheat sheet)
└── assets/           <- images and diagrams

A reader reaches for code-examples/ because they want code, not because it is markdown.

One file per concept, short and focused

If a doc is over 600 lines, split it. Each markdown file should answer one question. The interview prep had eight files, each between 100 and 400 lines. None of them tried to be a textbook.

Writing principles I used in the docs

A quick aside before the HTML viewer.

Lead with a sentence that previews the doc

Every doc opens with a single sentence in italics or quotes that tells you what to expect. That way a reader skimming the index can decide whether to commit five minutes to reading.

Tables for reference, prose for narrative

Tables are great for "look up what this does." They are terrible for "explain this concept." Mixing both keeps a doc readable. The tech-stack page in my prep folder is mostly prose with one or two tables. The glossary is one big table.

Show code with the why

Every code block should be preceded by a sentence that says what it is and why. Code without context is just decoration.

Avoid em dashes and other typography tricks

I deliberately stick to commas, parentheses, and full stops. Em dashes look fancy but they often hide a sentence that should have been split in two.

The single-file HTML viewer

Now the fun part. Here is the whole HTML file in pieces.

The skeleton

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>My Notes</title>
    <style>
      /* styles go here */
    </style>
  </head>
  <body>
    <nav>
      <h1>My Notes</h1>
      <a href="#README.md">Home</a>
      <ol>
        <li><a href="#docs/01-introduction.md">Introduction</a></li>
        <li><a href="#docs/02-setup.md">Setup</a></li>
        <li><a href="#docs/03-deeper-topics.md">Deeper topics</a></li>
      </ol>
    </nav>
    <main id="content">
      <div class="loader">Loading...</div>
    </main>

    <script src="https://cdn.jsdelivr.net/npm/marked@13.0.0/marked.min.js"></script>
    <script>
      /* router goes here */
    </script>
  </body>
</html>

That is it for the structure. Two main blocks (a sidebar and a content pane), one CDN script for markdown rendering, one script for the routing logic.

Layout with CSS Grid

The sidebar plus content layout is one CSS Grid declaration:

body {
  margin: 0;
  font: 16px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
  display: grid;
  grid-template-columns: 280px 1fr;
  min-height: 100vh;
}

280px 1fr means the sidebar is a fixed 280 pixels wide, and the rest of the row stretches to fill the remaining space. Three lines, no flexbox, no media queries needed at this stage.

Sticky sidebar

You want the sidebar to stay visible when the content scrolls:

nav {
  position: sticky;
  top: 0;
  height: 100vh;
  overflow-y: auto;
}

position: sticky plus top: 0 plus height: 100vh makes the sidebar pin itself to the top and become its own scroll container. Three properties, no JavaScript.

Dark mode for free

You can detect the user's system preference with prefers-color-scheme:

:root {
  --bg: #0e1116;
  --text: #e6edf3;
  --link: #58a6ff;
  --border: #30363d;
  --code-bg: #1c2128;
}

@media (prefers-color-scheme: light) {
  :root {
    --bg: #ffffff;
    --text: #1f2328;
    --link: #0969da;
    --border: #d1d9e0;
    --code-bg: #f6f8fa;
  }
}

body {
  background: var(--bg);
  color: var(--text);
}

Define your colours as CSS custom properties (variables) once. Override them inside a prefers-color-scheme: light block. Use the variables everywhere else. The OS theme switch flips the whole page automatically.

If you want a manual toggle, you can store a class on <html> (light or dark) and override the variables based on the class instead of the media query. But for a personal study folder, following the OS preference is enough.

Mobile responsive in three lines

@media (max-width: 800px) {
  body { grid-template-columns: 1fr; }
  nav { position: static; height: auto; }
  main { padding: 24px; }
}

On narrow screens, collapse the grid to a single column, unstick the sidebar, and shrink padding. Done.

The router (the JavaScript part)

The interesting trick is using the URL hash as the route. When you click <a href="#docs/01-introduction.md">, the browser changes the hash but does not reload the page. We listen for that change and load the right markdown file.

Step 1: load and render

async function load(path) {
  if (!path) path = 'README.md';
  const content = document.getElementById('content');
  content.innerHTML = '<div class="loader">Loading...</div>';

  const response = await fetch(path);
  if (!response.ok) {
    content.innerHTML = `<h2>Could not load ${path}</h2>`;
    return;
  }

  const markdown = await response.text();
  content.innerHTML = marked.parse(markdown);
  window.scrollTo(0, 0);
}

fetch(path) reads the markdown file from disk (or rather, from wherever the HTML is being served). marked.parse(markdown) turns the markdown text into HTML. We dump that HTML into the content area.

Step 2: react to URL changes

function onHashChange() {
  const path = location.hash.slice(1); // strip the leading "#"
  load(path);
}

window.addEventListener('hashchange', onHashChange);
onHashChange(); // also run once on initial page load

When the user clicks a sidebar link, location.hash changes, the hashchange event fires, and we reload the content. When they reload the page, the same code runs once and shows the right doc based on the URL.

Step 3: rewrite relative links inside the markdown

This is the bit that trips most people up. If your doc says:

See [setup](02-setup.md) for details.

That link, after rendering, points to 02-setup.md, which the browser tries to fetch as a real page. It will fail (or load the raw markdown), not navigate inside our viewer.

We need to rewrite those links to use the hash:

content.querySelectorAll('a[href]').forEach((anchor) => {
  const href = anchor.getAttribute('href');
  if (href.startsWith('http') || href.startsWith('#')) return;
  if (!href.endsWith('.md') && !href.includes('.md#')) return;

  // Resolve relative to the current doc's directory
  const currentDir = (location.hash.slice(1) || 'README.md').split('/').slice(0, -1);
  const segments = href.split('/');
  for (const seg of segments) {
    if (seg === '..') currentDir.pop();
    else if (seg !== '.') currentDir.push(seg);
  }
  anchor.setAttribute('href', '#' + currentDir.join('/'));
});

This walks every link the renderer just produced. If it points to a markdown file with a relative path, we resolve it relative to the current doc's directory and prepend a #. Now [setup](02-setup.md) from inside docs/01-introduction.md becomes #docs/02-setup.md, which our router knows how to handle.

You only need this if you write relative links between your docs. If every link in the markdown is absolute (/docs/...), you can skip it.

The one caveat: file:// and CORS

If you double-click index.html in your file manager, the browser opens it from file://. Some browsers (Chrome, in particular) block fetch() from file:// for security reasons. Your viewer will load with the sidebar, then show "Could not load" when it tries to fetch the markdown.

There are two easy fixes.

Fix 1: serve the folder with any tiny HTTP server

# Pick whichever you have
npx http-server .
python -m http.server 8000

Open http://localhost:8080 (or :8000) instead of the file path. Done.

Fix 2: use Firefox

Firefox allows fetch() from file:// by default. If you do not want a server, just use Firefox.

I documented this clearly in the loader's error message so a reader is never confused:

content.innerHTML =
  `<h2>Could not load ${path}</h2>` +
  `<p>If you opened this file directly via <code>file://</code>, ` +
  `your browser may be blocking <code>fetch</code>. Run a tiny ` +
  `server in this folder instead:</p>` +
  `<pre>npx http-server .</pre>`;

A graceful error message is the best documentation.

Styling tips for nice rendering

Marked outputs plain HTML (<h1>, <table>, <pre>, <code>). You can style them like any other page. A few things make the result look more like GitHub or a real docs site:

main h1, main h2 {
  border-bottom: 1px solid var(--border);
  padding-bottom: 6px;
}
main pre {
  background: var(--code-bg);
  padding: 14px 16px;
  border-radius: 6px;
  border: 1px solid var(--border);
  overflow-x: auto;
  line-height: 1.5;
}
main code {
  background: var(--code-bg);
  padding: 2px 6px;
  border-radius: 4px;
  font-size: 0.92em;
}
main blockquote {
  border-left: 4px solid var(--accent);
  padding: 4px 16px;
  color: var(--muted);
}
main table {
  border-collapse: collapse;
  width: 100%;
}
main th, main td {
  border: 1px solid var(--border);
  padding: 8px 12px;
}

Underlined H1 and H2, padded code blocks with rounded corners, blockquotes with a left accent stripe, properly bordered tables. Maybe twenty lines of CSS gets you a result that looks intentional.

When you outgrow this

This pattern is great until you need:

Search across all docs.
Build-time syntax highlighting (the marked CDN does not include it, although you can add highlight.js the same way).
Versioning (multiple snapshots of the same docs).
A public site with a domain and analytics.

At that point, take a look at:

MkDocs with the Material theme. Best balance of "barely any config" and "production-ready output."
Docusaurus if you want React components inside your markdown.
Astro if you want a faster site with more flexibility.
GitHub Pages plus Jekyll if you just want to publish a folder of markdown to the internet.

For everything else, the no-build approach holds up surprisingly well.

Wrap up

A folder of markdown plus a single HTML viewer gets you most of what a docs site does, with no install step and no maintenance burden. The pattern is:

Numbered markdown files in a docs/ folder.
A README.md at the top that is an index, not a chapter.
One index.html with CSS Grid layout, a sticky sidebar, and CSS variables for dark mode.
A small router that listens to hashchange, fetches the markdown, parses it with marked, and rewrites relative links.
A clear error message when file:// blocks fetch.

If you want to study something, document something, or share notes with a small team, this is the smallest amount of effort that gets you a real navigable site. Try it on your next folder of notes.

Happy writing.

How to Reset Your MySQL Root Password on Ubuntu (When Nothing Works)

Mohamed Idris — Fri, 01 May 2026 13:25:13 +0000

I was working on a Laravel task and got this error in my logs:

SQLSTATE[HY000] [1045] Access denied for user 'root'@'localhost' (using password: YES)

My .env file had DB_PASSWORD=password, but MySQL was rejecting it. I tried the usual tricks and ran into a wall. Here is what was happening, what fixed it, and a few small things that confused me along the way. If you are a junior dev and any of this sounds familiar, this post is for you.

Step 1: Check if your Laravel .env is the problem first

Before anything wild, open your .env file and check these lines:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=my_app
DB_USERNAME=root
DB_PASSWORD=password

If your password is blank or wrong, just fix it and run:

php artisan config:clear

Done. If the password really is what you think it is and MySQL still rejects it, keep reading.

Step 2: Try the classic Ubuntu trick

On a lot of Ubuntu installs, the MySQL root user does not use a password at all. It uses something called socket authentication, which means you log in by being a Linux superuser. So this usually works:

sudo mysql

If that opens a MySQL prompt, great. You can set a real password from inside:

ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'password';
FLUSH PRIVILEGES;

But in my case I got this:

ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)

That means root already had a password set, just not one I knew. Time for the real recovery.

Step 3: Reset the password using an init file

The safest way to reset a forgotten root password is to start MySQL with a special init file. The init file runs SQL the moment MySQL boots, so you can change the password without ever logging in.

Here is a small bash script that does the whole thing. Save it as mysql-reset.sh:

#!/bin/bash
set -e

NEW_PASS='password'
INIT_FILE=$(mktemp /tmp/mysql-init-XXXXXX.sql)

cat > "$INIT_FILE" <<SQL
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '${NEW_PASS}';
FLUSH PRIVILEGES;
SQL

sudo chown mysql:mysql "$INIT_FILE"
sudo chmod 600 "$INIT_FILE"

echo "Stopping mysql..."
sudo systemctl stop mysql

echo "Starting mysql with the init file..."
sudo mysqld --user=mysql --init-file="$INIT_FILE" --daemonize

sleep 3

echo "Stopping the temporary mysqld..."
sudo pkill -f "mysqld --user=mysql --init-file=$INIT_FILE" || true
sleep 2

echo "Starting mysql normally..."
sudo systemctl start mysql

sudo rm -f "$INIT_FILE"

echo "Testing the new password..."
mysql -u root -p"$NEW_PASS" -e "SELECT 'OK' AS status;"

Then run it:

bash mysql-reset.sh

It will ask for your sudo password. After it finishes, root has the password you set. Mine is now password, which matches my Laravel .env.

Step 4: Create your database if it does not exist yet

mysql -u root -ppassword -e "CREATE DATABASE IF NOT EXISTS my_app;"

You will see a warning that goes like this:

mysql: [Warning] Using a password on the command line interface can be insecure.

That is just a warning, not an error. Your command still ran. We will fix that warning in the last step.

Now run your migrations:

php artisan migrate

If your tables get created, you are back in business.

Two confusing errors that tripped me up

After the reset I tried a couple of things that looked broken but were actually fine. If you see these, do not panic.

"sudo mysql" stops working

sudo mysql -e "ALTER USER 'root'@'localhost' ..."
ERROR 1045 (28000): Access denied for user 'root'@'localhost' (using password: NO)

This is correct now. We changed root from socket login to password login. So sudo mysql cannot just walk in anymore. You have to give the password:

mysql -u root -p

Just typing "mysql" fails

mysql
ERROR 1045 (28000): Access denied for user 'your_username'@'localhost' (using password: NO)

When you run mysql with no flags, it tries to log in using your Linux username with no password. There is no MySQL user with your Linux name, so it fails. This is normal. You need -u root -p.

Step 5: Stop typing your password every time

This was the nicest little win. You can put your client credentials in a config file and the mysql command will read it automatically.

Create ~/.my.cnf:

[client]
user=root
password=password

Lock down the permissions so other users on the machine cannot read it:

chmod 600 ~/.my.cnf

Now this just works:

mysql

No prompt, no flags, no warning. Quick test:

mysql -e "SELECT CURRENT_USER();"

You should see root@localhost.

A safer setup for real projects

Using root for your app is fine on a learning machine, but on anything you care about, make a dedicated user with access to one database only:

CREATE DATABASE IF NOT EXISTS my_app;
CREATE USER 'my_app_user'@'localhost' IDENTIFIED BY 'a_real_password';
GRANT ALL PRIVILEGES ON my_app.* TO 'my_app_user'@'localhost';
FLUSH PRIVILEGES;

Then point your .env at that user. If the app password ever leaks, your other databases are still safe.

Quick recap

Check the .env first. The simplest fix is usually the right one.
Try sudo mysql. If it works, you are using socket auth and you can set a password right there.
If root already has a password you do not know, reset it with an init file. Do not edit mysql.user by hand and do not run with --skip-grant-tables if you can avoid it.
After the reset, remember that sudo mysql will not work anymore. Use mysql -u root -p.
Drop a ~/.my.cnf with mode 600 so you can just type mysql and get in.
For real projects, do not use root. Make an app user with access to one database.

Hope this saves someone an hour. Forgetting a database password feels scary, but the recovery is short once you know the steps.

I made a swing boat that reacts to doom scrolling

Mohamed Idris — Sat, 25 Apr 2026 15:53:48 +0000

When I was a kid, I tried the swing boat a few times and hated it. It made me dizzy. The kind of dizzy where you are not sure if it is fun anymore. You start slow, then someone keeps pushing, and before you know it you are too high and your stomach does not agree.

I got that same feeling recently, but from scrolling.

Doom scrolling is that thing you do when you open your phone for no reason and close it twenty minutes later having seen nothing worth remembering. Your finger goes up and down, up and down, the same motion as a swing. Your brain sits there getting rocked back and forth until it is numb. That is the brain rot part. Not dramatic, just slow and quiet. Your attention gets shorter. Your mood gets worse. You feel tired but you also cannot stop.

I kept thinking about how the finger movement looks exactly like a swing. Up and down, rhythm, momentum. The more you do it, the harder it is to stop. Same physics, different damage.

So I made a small thing to show that.

What it does

It is a red swing boat hanging in the dark. When you scroll, it swings. Keep scrolling and it goes higher. Stop, and it slowly dies down the way a real swing does. Short messages appear below the boat as the energy builds up. They start gentle. They do not stay that way.

How it works

The whole thing is a single HTML file with no dependencies. The boat is an inline SVG so CSS and JavaScript can interact with it directly. The swing uses real pendulum physics, gravity and damping included, so it coasts and rocks naturally after you stop. Scroll speed feeds into the angular velocity, which means the harder you scroll the higher the swing goes.

The scroll itself is captured with a wheel event and preventDefault, so the page never actually scrolls. There is nothing to read. Just the boat.

Try it

Demo: github.com/edriso/doomswing

My bot stopped sending questions the day Egypt turned on Daylight Saving Time

Mohamed Idris — Sat, 25 Apr 2026 08:16:24 +0000

I built a Telegram bot that sends math questions to kids every day at 2:30 PM Egypt time. It had been live for two weeks, running every single day without a problem, questions going out on time, kids answering, streaks building up. Then recently I ran /admin_health in the bot and saw 0 scheduled questions. That's when I knew something was wrong and went digging through the logs.

The last successful run was April 23. That night, Egypt turned on Daylight Saving Time.

Let me walk you through how the whole thing worked, what broke, and how I fixed it.

How the bot schedules questions

The bot has two main daily jobs:

01:30 AM Cairo: prepare today's questions for every user (pick 3 questions based on each kid's weak topics, save them to the database)
2:30 PM Cairo: send the first question to everyone

I use a library called node-cron for scheduling. It supports timezones, so I just tell it "run this at 00:30 Cairo time" and it figures out the UTC equivalent automatically.

cron.schedule('30 0 * * *', async () => {
  await prepareScheduledQuestions();
}, { timezone: 'Africa/Cairo' });

How "Cairo time" works in the code

The bot server runs on Railway (cloud), so it lives in UTC. Every time I need to know "what day is it in Cairo?", I use this function:

function todayCairoAsUtcMidnight(): Date {
  // Get today's date as a string in Cairo timezone, e.g. "2026-04-23"
  const dateStr = new Intl.DateTimeFormat('en-CA', {
    timeZone: 'Africa/Cairo',
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
  }).format(new Date());

  // Return that date as UTC midnight so we can compare with database values
  return new Date(dateStr + 'T00:00:00.000Z');
}

So "today in Cairo" becomes a fixed timestamp I can store in the database and compare against later. A question prepared at 01:30 AM Cairo gets tagged with 2026-04-23T00:00:00.000Z. When the 2:30 PM cron runs, it looks up questions tagged with that same date. If they match, the question gets sent.

This works great as long as Cairo is always UTC+2.

What is Daylight Saving Time?

DST is when a country moves its clocks forward by 1 hour in summer to make better use of daylight. Egypt reinstated DST in 2023 after not using it for about 10 years.

In Egypt:

Last Friday of April at midnight → clocks jump from 00:00 to 01:00 (spring forward)
Last Thursday of October at midnight → clocks go back from 01:00 to 00:00 (fall back)

The key phrase is "clocks jump from 00:00 to 01:00". That means 00:30 literally does not exist on that night.

The bug

My prepare-questions cron was set to run at 00:30 Cairo time.

On April 24, 2026 (the DST transition day), at midnight Cairo, clocks skipped forward one hour. The time went from 00:00 directly to 01:00. There was no 00:30.

node-cron saw that 00:30 didn't exist that night and silently skipped the job. No error, no warning, nothing in the logs. But it gets worse. After that skip, node-cron's internal scheduler got into a broken state. It was not just the prepare job that stopped. Every single cron job stopped firing. The 2:30 PM send job never ran on April 24. Or April 25. The bot process was alive on Railway, no crashes, no restarts, just complete silence for two days.

Here are the actual logs. Everything stops on April 23:

[2026-04-22T22:30:00.006Z] [INFO] [CRON] Preparing daily questions...
[2026-04-22T22:30:31.408Z] [INFO] Prepared adaptive questions for 9 users
[2026-04-23T12:30:00.025Z] [INFO] [CRON] Sending first question...
[2026-04-23T12:30:25.042Z] [INFO] First question sent {"sent":8,"failed":1,"total":9}
[2026-04-23T17:30:00.016Z] [INFO] [CRON] Sending reminders...
[2026-04-23T17:30:05.120Z] [INFO] Reminders sent {"sent":8,"total":9}

(silence after this)

Notice 22:30 UTC = 00:30 Cairo (UTC+2), and that was the last time questions were prepared. After that, the clocks changed and 00:30 disappeared.

Why there were no errors

This is the sneaky part. node-cron doesn't throw an error when a scheduled time is skipped due to DST. And when the scheduler breaks internally, it also does not throw an error. The bot process just keeps running, healthy from Railway's point of view, with zero indication that all the scheduled work stopped.

No crash to investigate. No alert to wake you up. Just kids not getting their questions.

Fix 1: Move the cron to a safe time

The simplest fix: change 00:30 to 01:30.

Egypt's clocks spring from 00:00 to 01:00, so 01:30 always exists, even on DST transition day. Problem solved.

// Before (broken on DST spring-forward day):
cron.schedule('30 0 * * *', handler, { timezone: 'Africa/Cairo' });

// After (safe):
cron.schedule('30 1 * * *', handler, { timezone: 'Africa/Cairo' });

One more thing: on the fall-back day in October, clocks go from 01:00 back to 00:00, so 01:30 actually happens twice that night. That means the job runs twice. But that is totally fine, because at the start of prepareScheduledQuestions() there is a check: if a user already has questions prepared for today, skip them. So the second run just finds everyone already done and exits. No duplicates, no problems.

Fix 2: Add a fallback inside the send job

The cron time fix handles DST. But what if the prepare job fails for any other reason, like a server hiccup, a deploy at the wrong time, whatever?

I added one line at the top of the send-questions job:

export async function sendFirstQuestion(bot) {
  // If questions weren't prepared for any reason, prepare them now before sending
  await prepareScheduledQuestions();

  // ... rest of the send logic
}

prepareScheduledQuestions() already skips users who have questions today, so calling it here costs nothing on a normal day. But on a broken day, it saves everyone from getting nothing.

The lesson

If your cron jobs use a timezone that observes DST, avoid scheduling at times that get skipped during the spring-forward transition. In Egypt that means avoid 00:01 through 00:59. Use 01:30 or later to be safe.

More generally: cron + timezones is a place where things can go silently wrong. The job doesn't crash, there's no alert, users just don't hear from your app. Always add a fallback or at least an explicit log when your main jobs find zero work to do. That's usually a sign something upstream failed.

if (prepared === 0) {
  logger.warn('No questions prepared, double check the prepare-questions job ran today');
}

That one log line would have caught this immediately.

The bot is now fixed and sending questions again. And next April, when Egypt springs forward, it'll handle it quietly.

A question:

Someone may ask: what if you really wanted the job to always run at exactly 00:30 Cairo, no matter what happens to the clock?

Short answer: you can't. Not on spring-forward night.

00:30 Cairo on that night does not exist. The clock jumps from 00:00 directly to 01:00. There is no UTC value that maps to 00:30 Cairo on that specific night. It was erased. No library, no trick, no workaround can schedule something at a time that literally never happens.

The closest you can get is one of two things.

First option is what we already did: move to 01:30. It always exists, even on the transition night. On 364 days a year it runs at 01:30 Cairo. On that one spring-forward night it also runs at 01:30 Cairo, which is just one hour later than you wanted. Not a big deal.

Second option is to schedule at two UTC times, one for winter and one for summer. Winter Cairo is UTC+2, so 00:30 Cairo = 22:30 UTC. Summer Cairo is UTC+3, so 00:30 Cairo = 21:30 UTC. You run both. Since the prepare function skips users who already have questions today, only one of the two actually does any work on a normal night. On the transition night, 22:30 UTC lands at 01:30 Cairo so you again get one hour late, but questions are still prepared. This gets you 00:30 on all regular nights in both seasons.

But honestly the real safety net is the fallback we added inside the send job. Even if the prepare cron runs late, or gets skipped, or breaks entirely, questions get prepared right before they are sent at 2:30 PM. That is what actually protects users, not the exact minute the prepare job fires.

Stop arguing about formatting in code reviews. Use Husky and lint-staged instead.

Mohamed Idris — Fri, 24 Apr 2026 19:52:09 +0000

If your team has ever left a comment like "missing semicolon" or "wrong quote style" on a pull request, this post is for you.

Formatting is not a code review topic. It should be handled automatically before the code even reaches a PR. Here is how to do that cleanly using Husky and lint-staged.

What are we actually solving?

The problem is simple: developers format code differently, editors have different defaults, and without enforcement, you end up with inconsistent style that creates noisy diffs and unnecessary review comments.

The goal is to auto-format and auto-lint staged files right before every commit, so bad formatting never reaches the repo.

Two tools make this easy:

Prettier handles formatting (spacing, quotes, semicolons, line length)
ESLint handles code quality (unused variables, missing dependencies, bad patterns)
Husky lets you run scripts automatically on git events like pre-commit
lint-staged runs those scripts only on staged files, not your entire codebase

Running tools on the full project on every commit would be slow. lint-staged keeps it fast by scoping to only what you changed.

Step 1: Install the tools

npm install --save-dev husky lint-staged

If you do not already have Prettier and ESLint set up:

npm install --save-dev prettier eslint eslint-config-prettier eslint-plugin-prettier

eslint-config-prettier disables ESLint rules that conflict with Prettier. eslint-plugin-prettier makes ESLint report Prettier violations as lint errors. Without these two, ESLint and Prettier will fight each other.

Step 2: Initialize Husky

npx husky init

This creates a .husky/ folder and adds a prepare script to your package.json:

"scripts": {
  "prepare": "husky"
}

The prepare script runs automatically on npm install. That means anyone who clones your repo and installs dependencies gets the pre-commit hook set up without doing anything manually. This is the key to making it work across a team.

Step 3: Set up the pre-commit hook

Open .husky/pre-commit and replace whatever is in it with:

npx lint-staged

That is all. Every time you run git commit, Husky will run lint-staged before the commit goes through.

Step 4: Configure lint-staged

Add this to your package.json:

"lint-staged": {
  "src/**/*.{js,jsx,ts,tsx}": "eslint --fix",
  "src/**/*.{css,json,md}": "prettier --write"
}

This says: on staged JS and JSX files inside src/, run ESLint with auto-fix. On staged CSS, JSON, and Markdown files, run Prettier.

Why split them? Because eslint-plugin-prettier already runs Prettier internally when you run eslint --fix on JS files, so you do not need to run both. For CSS and other file types, Prettier handles it directly since ESLint does not cover them.

If you are working on a plain HTML or CSS project without ESLint, simplify to just:

"lint-staged": {
  "**/*.{html,css,js,json,md}": "prettier --write"
}

Step 5: Add a .prettierignore file

Create .prettierignore in your project root:

dist/
node_modules/

This prevents Prettier from formatting compiled or generated output. Without this, it might reformat your minified CSS or bundled JS, which is not what you want.

How it works in practice

You make changes to a few files, stage them with git add, and run git commit. Husky fires the pre-commit hook. lint-staged checks which staged files match your patterns and runs the tools only on those. If ESLint finds an error it cannot auto-fix, the commit is blocked and you see the error. If everything passes, the commit goes through with clean, formatted code.

The first time you set this up, you will probably want to run a full format pass on the whole project so everything starts from a clean state:

npx prettier --write "src/**/*.{js,jsx,css,json}"

Commit that as a single formatting commit, then the pre-commit hook keeps things clean going forward.

VS Code integration (the finishing touch)

The pre-commit hook is your safety net. But you can also make formatting happen as you type by adding a .vscode/settings.json to your project:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "always"
  },
  "eslint.validate": ["javascript", "javascriptreact"],
  "files.autoSave": "off"
}

With this, every time you hit save, VS Code runs Prettier and ESLint automatically. By the time you stage your files, they are already formatted. The Husky hook just confirms nothing slipped through.

Commit this file to the repo so the whole team gets the same editor behavior without any manual setup.

The result

No more formatting comments in code reviews
Clean diffs that show only real changes
Commits that are always consistent, regardless of who made them
New team members get the full setup just by running npm install

It takes about ten minutes to set up and saves hours of back-and-forth over style issues. Worth it.

Resume Update!

Mohamed Idris — Thu, 23 Apr 2026 16:01:33 +0000

A while back I shared that I built my resume as a website so I can update it in one place without re-uploading files or changing links everywhere.

Now that I'm looking for a new job, I ran into a new problem; I wanted to tailor my resume depending on the role I'm applying to. Sending the same resume to a Magento recruiter and a frontend recruiter doesn't really make sense.

So I fixed that by adding a query param to the resume URL:

edriso.github.io?r=fullstack
edriso.github.io?r=frontend
edriso.github.io?r=php
edriso.github.io?r=magento

Each one shows a different version; different title, different bio, different skills order 😃.

And it saves to localStorage, so if the recruiter refreshes the page or comes back later without the param, they still see the right version.

Same thing on my portfolio site. The resume link in the footer automatically includes the right role param based on which version of the portfolio the recruiter is viewing.

One link per recruiter. No confusion.

Alhamdulillah 🙌

How to Undo a Git Commit Without Losing History

Mohamed Idris — Thu, 23 Apr 2026 13:43:41 +0000

We've all been there — you made a commit, pushed it, and then realized: that was a mistake.

The good news? Git has a safe way to undo it without rewriting history.

The Problem

You might think of using git reset to go back in time. But if you've already pushed the commit to a shared branch, resetting and force-pushing can cause problems for everyone else on the team.

The Better Way: `git revert`

git revert creates a new commit that undoes the changes from a previous commit. Your history stays intact — you just add an undo step on top.

How to Do It

Step 1: Find the commit you want to undo

git log --oneline

You'll see something like:

a8636a4 Tailor portfolio for e-commerce role
d56677a Fix hover effect
5315182 Add new project

Copy the hash of the commit you want to revert (e.g. a8636a4).

Step 2: Revert it

git revert a8636a4 --no-edit

a8636a4 — the commit hash you want to undo
--no-edit — skips the editor and uses the default revert message

Git will create a new commit like:

bf880c5 Revert "Tailor portfolio for e-commerce role"

That's it. Your mistake is undone and your history is clean.

When to Use `git revert` vs `git reset`

	`git revert`	`git reset`
Creates a new commit	Yes	No
Safe for shared branches	Yes	No
Rewrites history	No	Yes

Rule of thumb: If the commit is already pushed, use git revert. If it's only local, git reset is fine.

Summary

# See your commits
git log --oneline

# Revert the one you don't want
git revert <commit-hash> --no-edit

Simple, safe, and no drama. That's the Git way.

The 3-Second Rule: How to Write a Freelance Proposal That Gets Read (and Gets Replies)

Mohamed Idris — Wed, 22 Apr 2026 17:27:58 +0000

A friend told you to use "a 3-second role point" in your proposal. Good advice. But what does that actually mean?

This post breaks it down in plain English — with real examples, clear comparisons, and things you can use today on Upwork, Freelancer, Toptal, or any similar platform.

Why "3 Seconds" at All?

When a client posts a job on Upwork, they might get 20, 50, or even 100 proposals. They are not reading every word. They are scanning.

Studies and freelance coaches consistently say the same thing: a client decides in the first 3 to 8 seconds whether your proposal is worth reading — or worth skipping.

Those first few seconds happen at the very first line of your proposal. That is where you either win their attention or lose it forever.

This is the "3-second rule": your opening must be so relevant, so specific, and so interesting that the client stops scrolling and reads the rest.

The Biggest Mistake Freelancers Make

Before we get to the good stuff, let us look at what most people write.

A typical (losing) proposal opening:

"Hello, my name is Ahmed and I am a full-stack developer with 5 years of experience. I have worked with React, Node.js, MongoDB, and more. I am very passionate about coding and I believe I am the perfect candidate for this job..."

Sound familiar? This is what 80% of proposals look like.

The client does not care about your name in the first sentence. They do not care about your years of experience yet. They care about their problem.

You spent the first 3 seconds talking about yourself. They moved on.

The 3-Second Rule Point: Make It About Them First

Your opening line — your "3-second point" — should do one thing: show the client that you actually read their job post and you understand their specific problem.

Not a general problem. Their specific, stated problem.

Here is the formula for that opening line:

[Specific observation about their project] + [How you can help with that specific thing]

That is it. One or two sentences. Sharp and relevant.

Good vs Bad: Side by Side

Let us look at a real job post and compare proposals.

Job Post:

"I need a developer to fix my WooCommerce checkout page. Customers are abandoning at the payment step — I think it is a PayPal integration bug. My site is slow too. Budget: $200."

Bad proposal opening:

"Hi, I am a WordPress and WooCommerce expert with 6 years of experience. I can help you with your website. I am very hardworking and deliver on time. Please check my profile."

What is wrong here?

It is generic. This could be sent to any WooCommerce job.
It does not mention the PayPal bug.
It does not mention the checkout abandonment problem.
It does not mention the slow site.
The client feels like you did not read their post at all.

Good proposal opening:

"Checkout abandonment at the PayPal step is almost always a redirect loop or a mismatched IPN URL — I have fixed this exact issue three times this month. I can also audit your page speed in the same session since slow checkout pages make abandonment worse."

What is different here?

It names the exact problem: checkout abandonment.
It names the exact tool: PayPal.
It shows specific knowledge: "redirect loop or mismatched IPN URL" — this is credible.
It connects the two problems they mentioned (PayPal bug + slow site) in one sentence.
The client thinks: "This person actually read what I wrote."

That is 3 seconds well spent.

The Full Proposal Structure (After the Hook)

The 3-second opening is just the beginning. Here is the full structure that converts attention into replies:

1. The Hook (Seconds 1-3)

Your one or two sentence opener. Specific, relevant, and about them.

2. The Bridge (Your Relevant Experience)

Now — and only now — you talk about yourself. But keep it tied to their problem.

"I have been building WooCommerce sites for 4 years, and payment gateway bugs are one of the most common things I fix. Here is a similar case: a client's Stripe checkout was silently failing and costing them $3,000/month. I found it in under an hour."

Notice: one data point, one number, tied directly to their situation.

3. The Plan (What You Will Do)

Tell them how you will solve it. Not in vague words — in concrete steps.

"Here is my plan:

Reproduce the checkout error and check the PayPal IPN logs (1-2 hours)

Fix the integration and test on staging (1-2 hours)

Run a quick speed audit using GTmetrix and apply the top 3 fixes (1 hour)

Full test before handover"

This builds trust. It shows you have a process, not just "I will figure it out."

4. The Proof (Why Trust You)

A portfolio link, a relevant result, or a short testimonial quote. Keep it to one thing — do not list 10 projects.

"Here is a WooCommerce project where I fixed a similar Stripe issue: [link]"

5. The Call to Action (CTA)

End with a clear, low-pressure next step. Do not just say "let me know."

"Happy to jump on a 15-minute call to look at the issue together — no cost, just to confirm I can help before you commit. Or if you prefer, send me a test account and I can start today."

Full Example: Putting It All Together

Here is a complete proposal for the WooCommerce job above (under 200 words):

Checkout abandonment at the PayPal step is almost always a redirect loop or a mismatched IPN URL — I have fixed this exact issue three times this month.

I have been building WooCommerce stores for 4 years. Last month I helped a client in a similar situation: their PayPal checkout was silently failing for mobile users only, and they had no idea. I found it in the PayPal sandbox logs in about an hour.

My plan for your project:
1. Reproduce the error and check your PayPal IPN and webhook settings
2. Fix the bug and test on staging
3. Run a GTmetrix speed audit and apply the top fixes
4. Deliver with a short Loom video explaining what I found and fixed

Portfolio: [link to similar WooCommerce project]

I am available to start today. Want to do a quick 10-minute call so I can see the error myself before we start? Or just send me a staging login and I will take a look.

Clean. Specific. Confident. Under 200 words.

More Hook Examples You Can Adapt

Here are 5 quick openers for different situations. Notice each one names a specific detail from a hypothetical job post.

For a React performance job:

"A 4-second load time on the dashboard is almost always a missing memo or a useEffect firing too often — both are straightforward to diagnose with React DevTools."

For a landing page redesign:

"If your current page is converting at under 2%, the problem is usually the headline or the CTA placement — the design is secondary. I would start there before touching anything visual."

For a Node.js API bug:

"A race condition on concurrent requests is one of the trickier Node bugs because it does not always reproduce in dev. I would start with your async/await error handling and check if you have any unhandled promise rejections in production logs."

For a WordPress migration:

"Moving 1,200 posts from Wix to WordPress without losing SEO rankings is totally doable if you set up 301 redirects correctly from day one — I have done three migrations like this in the last two months."

For a Python scraping job:

"If the site blocks you after 50 requests, it is almost certainly rate-limiting by IP. Rotating proxies plus random delays between requests fixes this 90% of the time."

The Things That Kill Good Proposals

Even with a great hook, these common mistakes will lose you the job:

Too long. If your proposal is over 300 words, most clients will not finish reading it. Say less, say it better.

Copy-paste feel. Clients can tell when you sent the same proposal 50 times. Even one tiny detail from their post makes it feel personal.

No proof. Saying "I am an expert" means nothing. One relevant link, one number, one past result — that means something.

Weak ending. "Looking forward to your response" is not a CTA. Give them something to do: a question to answer, a call to book, a next step to take.

Starting with "I." The very first word of your proposal should never be "I." It signals immediately that you are about to talk about yourself.

Quick Checklist Before You Send

Before hitting send on any proposal, run through this list:

[ ] Does my first sentence name something specific from their job post?
[ ] Did I avoid starting with my name or years of experience?
[ ] Did I explain what I will do, not just that I can do it?
[ ] Did I include one concrete result or proof point?
[ ] Did I end with a clear, specific next step?
[ ] Is it under 250 words?
[ ] Does it sound like a human wrote it, not a template?

If all boxes are checked, send it.

TL;DR

The "3-second rule point" your friend mentioned is simply this: your first sentence must prove you read the job post and understand the client's actual problem — before you say a single word about yourself.

Structure your proposal like this:

Hook — one specific, relevant sentence about their problem
Bridge — your experience, tied to their situation
Plan — concrete steps, not vague promises
Proof — one link or result
CTA — a simple, clear next step

Most freelancers write about themselves. You write about the client. That is the difference.

What is the hardest part of writing proposals for you? Drop a comment — I read every one.

Sources:

If You Were a Server: How to Detect Issues and Keep Things Running Smoothly

Mohamed Idris — Wed, 22 Apr 2026 17:26:15 +0000

Here is a question that often pops up in senior web developer and backend interviews:

"If you were a server, how would you detect that you're having issues, and what would you do next to make things run smoothly?"

At first, it sounds a little weird. Be a server? But that is actually the whole point. The interviewer wants to know if you can think like infrastructure — can you see problems before they become disasters, and do you know how to respond?

This post breaks it all down in simple English. Whether you are a junior developer hearing these concepts for the first time, or someone preparing for a senior interview, you will walk away with a solid mental model.

First: What Is the Question Really Asking?

The question is covering two things:

Detection — How does a server (or you, the developer/SRE watching it) know something is wrong?
Response — What actions do you take to fix it or at least keep things stable?

Think of it like being a doctor for your own body. You check your temperature, blood pressure, and pulse. If something is off, you take medicine, rest, or call a specialist. Servers work the same way.

Part 1: How Does a Server Detect It Has Issues?

The Four Core Vitals

Just like a doctor checks your basic vitals, a server has its own set of core health signals. These are the first things to look at.

1. CPU Usage

CPU (Central Processing Unit) is the brain of your server. It handles every calculation, request, and operation.

Healthy: Under 60-70% usage during normal load.
Warning: Consistently above 80%.
Critical: Sustained 90%+ means your server is struggling to breathe.

When CPU is maxed out, your server starts slowing down responses, queuing requests, or dropping them entirely.

How to check it: top, htop, vmstat, or any cloud monitoring dashboard like AWS CloudWatch or Datadog.

2. Memory (RAM) Usage

Memory is your server's short-term workspace. Every running process uses RAM.

Healthy: Enough free RAM to handle spikes.
Warning: When RAM fills up, your OS starts using swap — which is disk space acting as fake RAM. Disk is much slower than RAM.
Critical: If swap fills up too, processes start crashing.

A common mistake is ignoring memory leaks — situations where an application keeps grabbing more memory and never releasing it. Over time, this silently kills your server.

3. Disk Usage and I/O

Disk usage is how much of your storage is full. Disk I/O is how fast data is being read and written.

Best practice: Keep at least 20-30% disk space free at all times.
A full disk can crash your database, stop logging, and break deployments.
High disk I/O (lots of reads/writes happening at once) can make everything slow, even if CPU and RAM look fine.

4. Network Bandwidth

Your server talks to the outside world through the network. If the pipe gets clogged:

Requests take longer to arrive and respond.
Large file uploads or downloads can saturate the connection.
You may see packet loss — data literally gets dropped mid-transfer.

Beyond the Core Vitals: Application-Level Signals

The four core vitals tell you about the hardware. But you also need to watch what your application is doing.

5. Response Time / Latency

How long does your server take to respond to a request?

A healthy API might respond in 100ms.
If latency jumps to 2-3 seconds, something is wrong — maybe a slow database query, a blocked thread, or an overloaded service.

Why it matters: Users notice latency before they notice anything else. A slow page feels broken.

6. Error Rate

What percentage of your requests are returning errors?

5xx errors (500, 502, 503, 504) mean your server is the problem.
If your error rate goes from 0.1% to 5%, something just broke.
Spikes in 4xx errors (404, 403) can also signal broken deployments or misconfigured routes.

7. Throughput / Request Rate

How many requests per second is your server handling?

A sudden drop in traffic can be as alarming as a spike — it might mean your server is down and clients are not even reaching it.
A sudden spike might mean a traffic surge, a bot attack, or a viral moment — all of which need different responses.

Health Checks: The Server Checking Itself

Modern servers do not wait for humans to notice something is wrong. They self-report through health check endpoints.

There are two main types used in systems like Kubernetes:

Liveness Probe

"Am I still alive?"

This is a simple check: is the process running at all? If a liveness probe fails, the orchestrator (like Kubernetes) will restart the container.

Example endpoint: GET /health/live → returns 200 OK if running.

Readiness Probe

"Am I ready to receive traffic?"

This is more nuanced: is the server running and fully ready to handle requests? Maybe it is warming up a cache, waiting for a database connection, or doing startup migrations.

If a readiness probe fails, the load balancer stops sending traffic to that instance — without killing it. Once it recovers, traffic resumes.

Example endpoint: GET /health/ready → checks DB connection, cache, etc.

Logging: The Server's Diary

Logs are your best friend when something goes wrong. A server should write meaningful logs that tell a story.

Structured logging means logging in a consistent format (usually JSON) so machines can read it:

{
  "timestamp": "2026-04-22T10:30:00Z",
  "level": "error",
  "message": "Database connection failed",
  "service": "api",
  "request_id": "abc-123",
  "duration_ms": 5000
}

Without good logs, debugging is like trying to solve a crime with no evidence. With good logs, you can trace exactly what happened, when, and why.

Log levels to know:

DEBUG — detailed developer info (not for production usually)
INFO — normal operations ("User logged in")
WARN — something is off but not broken yet
ERROR — something broke, needs attention
FATAL / CRITICAL — the server cannot continue

Alerting: Getting Notified Before It's Too Late

Monitoring without alerting is useless. You cannot stare at dashboards 24/7.

Set up alerts with smart thresholds:

Metric	Warning Threshold	Critical Threshold
CPU Usage	> 80% for 5 min	> 90% for 2 min
Memory Usage	> 85%	> 95%
Disk Space	< 25% free	< 10% free
Error Rate	> 1%	> 5%
Response Time	> 500ms avg	> 2s avg

Do not alert on every small blip. Use time windows (e.g., "CPU > 80% for 5 consecutive minutes") to avoid alert fatigue — a flood of noisy alerts that people start ignoring.

Tools: PagerDuty, OpsGenie, Slack alerts, AWS CloudWatch Alarms, Grafana Alerts.

Part 2: What Do You Do Next to Keep Things Running Smoothly?

You detected the problem. Now what? Here are the key strategies — from automatic to manual.

1. Auto-Scaling: Get More Help

If your server is overloaded, the simplest answer is: add more servers.

Auto-scaling is when your infrastructure automatically spins up new server instances when load is high, and shuts them down when load drops.

Normal traffic:   [Server 1]
Traffic spike:    [Server 1] [Server 2] [Server 3]
Traffic drops:    [Server 1]

This works with a load balancer sitting in front — it distributes incoming requests across all available instances so no single server gets crushed.

Horizontal scaling = more instances (this is what auto-scaling does).
Vertical scaling = bigger instance (more CPU/RAM on the same machine). Harder to do automatically.

Cloud providers (AWS, GCP, Azure) all have auto-scaling built in.

2. Circuit Breaker: Stop the Bleeding

Imagine your server calls another service (a payment API, a database, a third-party service). That service is slow or down. Your server keeps waiting... and waiting... and all your threads are now stuck waiting for something that will never respond. Your whole server grinds to a halt because of someone else's problem.

The Circuit Breaker pattern prevents this.

It works in three states:

CLOSED (Normal)
  → Requests pass through
  → Failures are counted

OPEN (Problem detected)
  → Requests immediately fail fast
  → No waiting, no timeout
  → Returns an error or fallback instantly

HALF-OPEN (Testing recovery)
  → A few test requests get through
  → If they succeed → back to CLOSED
  → If they fail → back to OPEN

It is called a circuit breaker because it works exactly like the electrical circuit breaker in your house — when something goes wrong, it cuts the connection to stop further damage.

Libraries: opossum (Node.js), resilience4j (Java), polly (.NET).

3. Graceful Degradation: Do Less, Not Nothing

When part of your system is broken, the goal is to keep the core experience working, even if some features are temporarily unavailable.

Real-world examples:

YouTube goes down? Show the homepage with a "video unavailable" message instead of crashing entirely.
Recommendation engine fails? Show generic popular content instead of personalized picks.
Payment service is slow? Disable the "buy now" button and show a "try again shortly" message instead of hanging the page.

This is better than an error page that says "500 Internal Server Error" with nothing else.

The key idea: degrade gracefully, fail loudly only when you have no other choice.

4. Caching: Avoid Repeating Work

Many server problems come from doing the same expensive work over and over. Caching stores the result of expensive operations so you can reuse them.

Without cache:
User → Server → Database (100ms) → User

With cache:
User → Server → Cache (1ms) → User  (if cached)
User → Server → Database (100ms) → Cache → User  (if not cached)

Types of caching:

In-memory cache: Redis, Memcached — extremely fast.
HTTP caching: Cache-Control headers tell browsers and CDNs to store responses.
Database query caching: Cache frequently run queries.

When your server is struggling, a well-configured cache can reduce database load by 80% or more.

5. Rate Limiting: Control Incoming Traffic

If traffic spikes and you cannot scale fast enough, you need to protect yourself by limiting how many requests any single client can make.

Example: Allow 100 requests per minute per IP. After that, return 429 Too Many Requests.

This protects against:

Accidental infinite loops in client code
DDoS (Distributed Denial of Service) attacks
Scrapers hammering your API

It is not just about bad actors — rate limiting is also good for your own internal services to prevent one slow consumer from starving everyone else.

6. Retry with Exponential Backoff: Be Patient, Not Aggressive

Sometimes a service is temporarily down and recovers in seconds. Clients should retry — but smart retries, not aggressive ones.

Bad retry:

Fail → Retry immediately → Fail → Retry immediately → Fail...
(This makes the overloaded server worse)

Good retry with exponential backoff:

Fail → Wait 1s → Retry
Fail → Wait 2s → Retry
Fail → Wait 4s → Retry
Fail → Wait 8s → Retry (give up after X attempts)

Each retry waits twice as long as the last. Add a bit of random delay (called jitter) so thousands of clients do not all retry at the exact same moment, which would cause another spike.

7. Rollbacks: Undo What Broke It

Sometimes the issue is a bad deployment. The fastest fix is often to roll back to the previous working version.

Blue-green deployment and canary releases are strategies to reduce this risk:

Blue-Green: You have two identical environments (blue = live, green = new). Deploy to green, test it, then switch traffic. If something breaks, switch back to blue instantly.
Canary Release: Roll out the new version to 5% of users first. If metrics look good, increase to 20%, then 50%, then 100%. If something breaks, only 5% of users were affected.

These patterns let you catch problems early without taking down everything.

8. Runbooks: The Human Response Plan

All the automation in the world cannot cover every scenario. You need a runbook — a documented set of steps that a human follows when a specific alert fires.

A good runbook answers:

What does this alert mean?
How urgent is it?
What are the first three things to check?
How do I escalate if I cannot fix it?
What commands should I run?

Example runbook entry:

Alert: High Memory Usage (> 90% for 10 minutes)

1. SSH into the affected server
2. Run: `ps aux --sort=-%mem | head -20` to find the top memory consumers
3. Check for memory leaks in the app logs: `grep "OutOfMemory" /var/log/app.log`
4. If a rogue process is found: restart the service
5. If memory does not recover: trigger a scale-out event
6. Escalate to on-call engineer if unresolved after 15 minutes

A runbook turns a stressful incident into a checklist. It is boring when things are calm and invaluable at 3am during an outage.

Putting It All Together: The Full Answer Framework

If an interviewer asks you this question, here is the structure of a great answer:

Detection (Observability):

I would monitor core metrics: CPU, memory, disk, network
I would track application metrics: latency, error rate, throughput
I would have health check endpoints (liveness and readiness)
I would use structured logging for traceability
I would set up smart alerts with meaningful thresholds

Response (Resilience):

Auto-scaling to handle load spikes
Circuit breakers to prevent cascading failures from downstream services
Graceful degradation to keep core features working
Caching to reduce repeated expensive work
Rate limiting to protect against traffic floods
Retry with exponential backoff for transient failures
Rollback strategies (blue-green, canary) for bad deployments
Runbooks so on-call engineers know exactly what to do

Real-World Tools Worth Knowing

Category	Popular Tools
Metrics & Dashboards	Grafana, Datadog, Prometheus, AWS CloudWatch
Logging	ELK Stack (Elasticsearch, Logstash, Kibana), Loki, Splunk
Alerting	PagerDuty, OpsGenie, Grafana Alerts
APM (App Performance)	Datadog APM, New Relic, Sentry
Uptime Monitoring	UptimeRobot, Pingdom, Checkly
Circuit Breakers	Resilience4j, Opossum (Node.js), Polly (.NET)
Caching	Redis, Memcached, Varnish
Load Balancing / Scaling	AWS ALB + Auto Scaling, Kubernetes HPA, NGINX

TL;DR

The interview question is asking you to think like a system that observes itself and heals itself.

Detect with metrics (CPU, memory, disk, network), application signals (latency, error rate), health checks, and structured logging.
Respond with auto-scaling, circuit breakers, graceful degradation, caching, rate limiting, smart retries, rollbacks, and runbooks.

The best systems do not just survive failures — they are designed to expect them and handle them without waking anyone up at 3am.

Found this useful? Drop a comment with the trickiest server question you have faced in an interview — I would love to hear it.

Sources:

Forem: Mohamed Idris

Stop Fighting Your AI About shadcn Components: Install the Skill

Tool 1: The shadcn skill

How to install the skill

What changes after you install it

Tool 2: The shadcn MCP server

Install for Claude Code

Install for Cursor

Install for VS Code with GitHub Copilot

What changes after you install it

Skill or MCP, which one do I need?

A real example

Quick troubleshooting

Final thought

shadcn vs Radix vs Base UI: Which One Should a Junior Pick in 2026?

First, what is a "headless" UI library?

Radix UI

Base UI

The asChild vs render difference

shadcn/ui

So what should you actually pick?

If you are starting a new project today:

If you are joining an existing team:

If you need a component Radix doesn't have:

If you want a fully styled out of the box library:

A simple decision tree

Final thought

Web Accessibility (A11y) for Juniors: What It Is and Why It Matters

What is A11y?

Why should you care as a junior?

The 4 principles (POUR)

Real examples you can fix today

1. Using div for buttons

2. Images with no alt text

3. Form inputs with no label

4. Color as the only signal

5. Low contrast text

6. Custom components without keyboard support

Tools that will save you

A simple checklist before you ship

Final thought

A No-Build Markdown Site for Study Notes (or any docs)

What we are building

Why this approach

The folder structure

One README at the top, as an index

Numbered file names for ordering

Group by purpose, not by file type

One file per concept, short and focused

Writing principles I used in the docs

Lead with a sentence that previews the doc

Tables for reference, prose for narrative

Show code with the why

Avoid em dashes and other typography tricks

The single-file HTML viewer

The skeleton

Layout with CSS Grid

Sticky sidebar

Dark mode for free

Mobile responsive in three lines

The router (the JavaScript part)

Step 1: load and render

Step 2: react to URL changes

Step 3: rewrite relative links inside the markdown

The one caveat: file:// and CORS

Fix 1: serve the folder with any tiny HTTP server

Fix 2: use Firefox

Styling tips for nice rendering

When you outgrow this

Wrap up

How to Reset Your MySQL Root Password on Ubuntu (When Nothing Works)

Step 1: Check if your Laravel .env is the problem first

Step 2: Try the classic Ubuntu trick

Step 3: Reset the password using an init file

Step 4: Create your database if it does not exist yet

Two confusing errors that tripped me up

"sudo mysql" stops working

Just typing "mysql" fails

Step 5: Stop typing your password every time

A safer setup for real projects

1. Using `div` for buttons

The Better Way: `git revert`

When to Use `git revert` vs `git reset`