Coder Legion - Recent posts tagged javascript

🧩 JavaScript Promises Inside Promises: The Hidden Bugs, Execution Flow and How to Fix Them

Sat, 31 Oct 2026 12:38:32 +0000

Have you ever debugged JavaScript code where a function says “Done!”, but the operation it depends on is still running?

Or perhaps an API request fails, but the error never reaches the catch() block you expected to handle it.

You inspect the code. You see .then(), another .then(), maybe a new Promise() inside another Promise and suddenly the execution flow becomes difficult to follow.

Sound familiar?

As JavaScript developers, we use Promises for API calls, database operations, file processing, authentication, background tasks and countless other asynchronous operations. Yet some of the bugs we encounter aren't caused by Promises themselves. They're caused by how we connect them.

Consider this example:

fetchUser()
  .then((user) => {
    saveUser(user);
  })
  .then(() => {
    console.log("User saved successfully!");
  });

Looks reasonable, right?

But what if saveUser() returns a Promise?

The success message can appear before the save operation finishes. Worse, if saving fails, the error might not reach the error handler you intended to use.

The problem isn't that Promises are outdated or that nested Promises are always bad. The problem is understanding which asynchronous operation the current chain is actually waiting for.

In this article, we'll work through these issues step by step:

What really happens when a Promise is created inside another Promise?
How does JavaScript execute synchronous code, Promise callbacks and timers?
Why does forgetting return break a Promise chain?
How do nested Promises differ from normal Promise chaining?
Does the same bug happen with async/await?
When should you use Promises, async/await, Promise.all(), or a background task?
How can you debug these problems in a real application?

Let's start with a bug we can reproduce.

1. First, let's reproduce the bug

Imagine you're building a user registration API.

After a user registers, your application needs to:

Save the user's information.
Send a welcome email.
Confirm that registration has completed.

For simplicity, we'll simulate the database and email operations using Promises.

The buggy implementation

function saveUser() {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log("1. User saved to database");
      resolve({ id: 101, name: "Fazal" });
    }, 1000);
  });
}

function sendWelcomeEmail(user) {
  return new Promise((resolve) => {
    setTimeout(() => {
      console.log(`2. Welcome email sent to ${user.name}`);
      resolve();
    }, 2000);
  });
}

function registerUser() {
  return saveUser()
    .then((user) => {
      sendWelcomeEmail(user);
    })
    .then(() => {
      console.log("3. Registration completed successfully");
    });
}

registerUser();

What do you expect to happen?

A reasonable expectation is:

1. User saved to database
2. Welcome email sent to Fazal
3. Registration completed successfully

But the actual output is:

1. User saved to database
3. Registration completed successfully
2. Welcome email sent to Fazal

Wait. Why?

We called sendWelcomeEmail(user) before logging the success message. Shouldn't JavaScript wait for it?

No. Calling an asynchronous function that returns a Promise does not automatically make the surrounding code wait for that Promise.

Let's understand exactly where the execution flow goes wrong.

What JavaScript actually does

Look at this callback:

.then((user) => {
  sendWelcomeEmail(user);
})

The function calls sendWelcomeEmail(user), which starts the email operation and returns a Promise.

But the callback doesn't return that Promise.

From the Promise chain's perspective, this callback returns undefined.

That means the next .then() doesn't need to wait for the email operation.

saveUser()
    |
    | Promise fulfills
    v
First .then()
    |
    | Starts email operation
    | Does NOT return its Promise
    v
First .then() fulfills with undefined
    |
    v
Second .then()
    |
    | Runs immediately after the previous
    | Promise reaction completes
    v
"Registration completed successfully"
    |
    | Email operation is still running
    v
"Welcome email sent to Fazal"

The exact wording matters here: the next .then() doesn't run synchronously inside the previous callback. It runs as a Promise reaction after the preceding chain Promise fulfills. But because the preceding callback returned undefined, that fulfillment doesn't depend on the email Promise.

This is the central bug.

The fix: return the Promise

function registerUser() {
  return saveUser()
    .then((user) => {
      return sendWelcomeEmail(user);
    })
    .then(() => {
      console.log("3. Registration completed successfully");
    });
}

Now the output is:

1. User saved to database
2. Welcome email sent to Fazal
3. Registration completed successfully

We changed only one thing: we returned the inner Promise.

JavaScript can now connect the two asynchronous operations into one chain.

A shorter version works too:

function registerUser() {
  return saveUser()
    .then((user) => sendWelcomeEmail(user))
    .then(() => {
      console.log("3. Registration completed successfully");
    });
}

When an arrow function has an expression body, that expression is returned implicitly. Here, the expression is the Promise returned by sendWelcomeEmail().

Keep this rule in mind throughout the article:

If the next step must wait for an asynchronous operation, make sure that operation's Promise is returned or awaited.

But why does returning a Promise work? To understand that, we need to look at how Promises actually behave.

2. What is a Promise, really?

A Promise represents the eventual outcome of an asynchronous operation.

It can be in one of three states:

Pending: The operation hasn't settled yet.
Fulfilled: The operation completed successfully.
Rejected: The operation failed.

A Promise that has fulfilled or rejected is called settled.

For example:

const result = new Promise((resolve, reject) => {
  setTimeout(() => {
    resolve("Data loaded");
  }, 1000);
});

result.then((value) => {
  console.log(value);
});

Output after approximately one second:

Data loaded

The Promise starts pending. After the timer callback runs, it fulfills with "Data loaded".

The .then() callback runs as a Promise reaction, rather than being invoked immediately by the call to resolve().

One important distinction: a Promise doesn't make an operation asynchronous by itself. The operation may involve a timer, network request, or other asynchronous API. A Promise provides a way to represent and compose its outcome.

Also, the Promise executor—the function passed to new Promise()—runs synchronously.

Let's verify that.

console.log("1. Before");

const promise = new Promise((resolve) => {
  console.log("2. Inside executor");
  resolve("Done");
});

promise.then((value) => {
  console.log("4.", value);
});

console.log("3. After");

Output:

1. Before
2. Inside executor
3. After
4. Done

Why?

JavaScript logs "Before".
The Promise constructor immediately invokes its executor, so "Inside executor" appears next.
resolve("Done") fulfills the Promise, but its .then() reaction doesn't run inline.
JavaScript continues with the remaining synchronous code.
The Promise reaction runs as a microtask.

This distinction becomes important when you see a Promise inside another Promise.

3. What happens when a Promise is inside another Promise?

There are two patterns that developers often confuse.

Pattern A: Returning a Promise from another Promise

const outerPromise = new Promise((resolve) => {
  resolve(
    new Promise((innerResolve) => {
      setTimeout(() => {
        innerResolve("Inner operation completed");
      }, 1000);
    })
  );
});

outerPromise.then((result) => {
  console.log(result);
});

Output after approximately one second:

Inner operation completed

Notice something important: outerPromise doesn't fulfill with the inner Promise object as its final value.

When a Promise is resolved with another Promise, it adopts the inner Promise's eventual state and outcome.

In this example:

The outer Promise's executor starts synchronously.
The inner Promise is created and its executor also starts synchronously.
resolve(innerPromise) resolves the outer Promise to follow the inner Promise.
The timer eventually fulfills the inner Promise.
The outer Promise then fulfills with "Inner operation completed".
The outer Promise's .then() reaction receives that string.

Conceptually:

Outer Promise
     |
     | resolved with inner Promise
     v
Inner Promise
     |
     | pending for 1 second
     v
Fulfilled with a string
     |
     v
Outer Promise fulfills with the same outcome
     |
     v
.then() receives the string

This behavior is part of Promise resolution. It's why Promise chains can be composed without manually inspecting whether each returned value is itself a Promise.

Pattern B: Creating a Promise but not returning it

Now compare that with:

const outerPromise = new Promise((resolve) => {
  new Promise((innerResolve) => {
    setTimeout(() => {
      innerResolve("Inner operation completed");
    }, 1000);
  });

  resolve("Outer operation completed");
});

outerPromise.then((result) => {
  console.log(result);
});

Output:

Outer operation completed

The inner Promise still runs. After approximately one second, it fulfills with "Inner operation completed", but nothing consumes that result.

The outer Promise doesn't wait for it because the inner Promise was neither returned from a relevant callback nor used to resolve the outer Promise.

This is a subtle but important distinction:

Creating a Promise starts the executor and establishes an asynchronous result.
Returning a Promise from a .then() callback connects its outcome to the chain.
Resolving a Promise with another Promise makes the first Promise adopt the second Promise's outcome.

These are related concepts, but they aren't interchangeable.

A complete execution-order example

Let's combine synchronous execution, nested Promise creation, a timer and .then().

console.log("0. Start");

function getUser() {
  return new Promise((resolve) => {
    console.log("1. Outer executor");

    resolve(
      new Promise((innerResolve) => {
        console.log("2. Inner executor");

        setTimeout(() => {
          console.log("4. Inner timer");
          innerResolve({ id: 1, name: "Fazal" });
        }, 1000);
      })
    );
  });
}

getUser().then((user) => {
  console.log("5. User:", user.name);
});

console.log("3. End");

Output:

0. Start
1. Outer executor
2. Inner executor
3. End
4. Inner timer
5. User: Fazal

The two executor messages appear immediately because both executors run synchronously. The "End" message follows because JavaScript continues running synchronous code. The timer callback executes later and the .then() callback runs after the Promise has fulfilled.

You don't need to memorize this particular output. You need to understand which operations are synchronous, which callbacks are scheduled and which Promise outcomes are connected.

4. Nested `.then()` callbacks vs. Promise chaining

Let's return to the registration example.

A nested version might look like this:

function registerUser() {
  return saveUser().then((user) => {
    return sendWelcomeEmail(user).then(() => {
      console.log("Email step completed");
      return user;
    });
  });
}

registerUser().then((user) => {
  console.log("Registration flow completed for", user.name);
});

This is valid JavaScript. The inner .then() returns a Promise and the outer callback returns that Promise. The whole chain waits for the email operation.

But nesting adds indentation and makes longer flows harder to follow.

We can express the same dependency using a flat chain:

function registerUser() {
  let registeredUser;

  return saveUser()
    .then((user) => {
      registeredUser = user;
      return sendWelcomeEmail(user);
    })
    .then(() => {
      console.log("Email step completed");
      return registeredUser;
    });
}

registerUser().then((user) => {
  console.log("Registration flow completed for", user.name);
});

Both versions wait for the email operation.

The flat chain makes the sequence easier to scan, although it uses a variable to preserve the user value. In production, you should consider whether that extra state is necessary and whether it makes the flow clearer.

You can also preserve the user value without an outer variable:

function registerUser() {
  return saveUser().then((user) => {
    return sendWelcomeEmail(user).then(() => user);
  });
}

Or, using async/await:

async function registerUser() {
  const user = await saveUser();
  await sendWelcomeEmail(user);
  return user;
}

There isn't a universal rule that every nested .then() is wrong. Nesting is sometimes natural when a local operation has its own result handling. The problem is accidental nesting that hides dependencies, loses return values, or makes error handling confusing.

5. The missing `return`: a small mistake with several consequences

Let's examine the most common version of this bug more closely.

Case 1: The next step starts too early

function processOrder(order) {
  return chargePayment(order)
    .then((payment) => {
      updateOrderStatus(order.id, payment);
    })
    .then(() => {
      console.log("Order processing completed");
    });
}

If updateOrderStatus() returns a Promise, the final callback doesn't wait for it.

Correct version:

function processOrder(order) {
  return chargePayment(order)
    .then((payment) => {
      return updateOrderStatus(order.id, payment);
    })
    .then(() => {
      console.log("Order processing completed");
    });
}

Now the next step waits for the status update.

Case 2: Errors don't propagate through the expected chain

Suppose an inner operation rejects.

function processOrder(order) {
  return chargePayment(order)
    .then((payment) => {
      updateOrderStatus(order.id, payment);
    })
    .catch((error) => {
      console.error("Order processing failed:", error);
    });
}

If updateOrderStatus() returns a Promise that rejects, the .catch() above won't catch that rejection through this chain because its Promise was never returned.

Correct version:

function processOrder(order) {
  return chargePayment(order)
    .then((payment) => {
      return updateOrderStatus(order.id, payment);
    })
    .catch((error) => {
      console.error("Order processing failed:", error);
      throw error;
    });
}

Notice the throw error.

Without it, the .catch() callback would fulfill the chain with undefined if it simply logged the error and returned nothing. Downstream code could then mistake the failure for success.

You should decide whether to rethrow, recover with a fallback, or handle the error and intentionally return a successful result. The right choice depends on the application.

Case 3: The caller receives a result too early

Imagine a function that should return the saved record:

function updateProfile(profile) {
  return saveProfile(profile).then((savedProfile) => {
    refreshSearchIndex(savedProfile);
  });
}

The caller receives a Promise that fulfills with undefined after the callback finishes—not with the search-index operation's result.

If the caller expects to wait for indexing too, return its Promise:

function updateProfile(profile) {
  return saveProfile(profile).then((savedProfile) => {
    return refreshSearchIndex(savedProfile);
  });
}

If the caller needs the saved profile as its result after indexing finishes:

function updateProfile(profile) {
  return saveProfile(profile).then((savedProfile) => {
    return refreshSearchIndex(savedProfile).then(() => savedProfile);
  });
}

This makes the intended result explicit.

Important: Don't return a Promise just to make every operation sequential. Return it when the caller needs to wait for that operation or depend on its outcome. Independent work may be better handled concurrently or in the background.

6. Is this bug specific to Promises, or does it also happen with `async/await`?

This is an excellent question because async/await often makes asynchronous code easier to read, but it doesn't eliminate the underlying problem.

The bug is generic to asynchronous control flow. It happens whenever the program starts work but fails to connect that work to the sequence that depends on it.

Let's translate the registration example.

Incorrect `async/await` implementation

async function registerUser() {
  const user = await saveUser();

  sendWelcomeEmail(user);

  console.log("Registration completed successfully");
}

registerUser();

The output can still be:

1. User saved to database
3. Registration completed successfully
2. Welcome email sent to Fazal

Why?

Because sendWelcomeEmail(user) starts the operation, but the function doesn't await its Promise.

The async keyword does not automatically wait for every Promise created inside the function.

Correct implementation

async function registerUser() {
  const user = await saveUser();

  await sendWelcomeEmail(user);

  console.log("Registration completed successfully");
}

registerUser();

Now the function waits for the email operation before logging success.

The difference is not that async/await has magical asynchronous behavior. It provides syntax for expressing the dependency clearly.

Compare the two patterns:

// Promise chaining
return saveUser()
  .then((user) => sendWelcomeEmail(user))
  .then(() => {
    console.log("Registration completed");
  });

// async/await
async function registerUser() {
  const user = await saveUser();
  await sendWelcomeEmail(user);

  console.log("Registration completed");
}

Both can represent the same sequence of operations.

A useful rule

If a later step must wait for an asynchronous operation:

With Promise chaining, return the Promise from the callback.
With async/await, await the Promise.

The underlying principle is the same: explicitly connect the operation to the control flow that depends on it.

7. Error handling: `.catch()` vs. `try/catch`

Correct sequencing is only half the story. We also need to understand how failures propagate.

Promise-based error handling

function registerUser() {
  return saveUser()
    .then((user) => {
      return sendWelcomeEmail(user);
    })
    .then(() => {
      console.log("Registration completed");
    })
    .catch((error) => {
      console.error("Registration failed:", error);
      throw error;
    });
}

A rejection from saveUser() or sendWelcomeEmail() can propagate to the final .catch() because each operation is connected to the chain.

If the email operation rejects, the success callback is skipped and the error handler runs.

The equivalent `async/await` approach

async function registerUser() {
  try {
    const user = await saveUser();
    await sendWelcomeEmail(user);

    console.log("Registration completed");
  } catch (error) {
    console.error("Registration failed:", error);
    throw error;
  }
}

The try/catch handles rejections from the awaited operations.

However, consider this:

async function registerUser() {
  try {
    const user = await saveUser();

    sendWelcomeEmail(user);
    console.log("Registration completed");
  } catch (error) {
    console.error("Registration failed:", error);
    throw error;
  }
}

If sendWelcomeEmail() returns a Promise that rejects, this catch won't catch that rejection through the try block because the Promise wasn't awaited. It may instead become an unhandled rejection, depending on what else handles it.

Correct:

async function registerUser() {
  try {
    const user = await saveUser();

    await sendWelcomeEmail(user);

    console.log("Registration completed");
  } catch (error) {
    console.error("Registration failed:", error);
    throw error;
  }
}

There is one additional nuance: try/catch catches synchronous exceptions thrown while executing the try block, as well as rejections from awaited Promises. It doesn't automatically catch failures from unrelated asynchronous operations that you start and leave unawaited.

That is why await matters for error handling as well as sequencing.

Should you always rethrow an error?

No.

Rethrow when the caller needs to know the operation failed. Recover when you have a meaningful fallback. Handle the error without rethrowing only when the function's contract says the failure has been dealt with and downstream code should continue.

For example, an optional analytics event might fail without preventing an order from being completed. A payment failure should not be silently swallowed.

Error handling should reflect the business requirement, not just the syntax.

8. Promise vs. `async/await`: which should you use?

This isn't a competition in which one syntax is always correct. async/await is built on Promises and is often easier to read for sequential workflows, while Promise methods remain valuable for composition and concurrency.

Here's a practical comparison.

Scenario A: Sequential operations

Suppose you need to fetch a user, then fetch that user's orders.

Promise chaining:

function getUserOrders(userId) {
  return fetchUser(userId)
    .then((user) => fetchOrders(user.id));
}

Using async/await:

async function getUserOrders(userId) {
  const user = await fetchUser(userId);
  const orders = await fetchOrders(user.id);

  return orders;
}

Both are valid. The second version can be easier to follow when the workflow contains many steps, conditions, or intermediate variables.

Scenario B: Several independent operations

Suppose a dashboard needs user information, notifications and recommendations. None depends on the others.

This version unnecessarily runs the operations sequentially:

async function loadDashboard() {
  const user = await fetchUser();
  const notifications = await fetchNotifications();
  const recommendations = await fetchRecommendations();

  return { user, notifications, recommendations };
}

If each operation takes time, the total duration can approach the sum of their durations.

Instead, start the independent operations together:

async function loadDashboard() {
  const [user, notifications, recommendations] =
    await Promise.all([
      fetchUser(),
      fetchNotifications(),
      fetchRecommendations()
    ]);

  return { user, notifications, recommendations };
}

Promise.all() fulfills when all supplied Promises fulfill. If one rejects, the returned Promise rejects with that failure, though the other operations aren't automatically cancelled and may continue running.

This is a common example of using async/await and Promise composition together. You don't need to choose one or the other.

Scenario C: Independent operations where partial results matter

Suppose you're loading data from five optional integrations. One failing shouldn't prevent you from displaying the successful results.

Use Promise.allSettled():

async function loadIntegrations() {
  const results = await Promise.allSettled([
    fetchCalendar(),
    fetchTasks(),
    fetchNotifications()
  ]);

  for (const result of results) {
    if (result.status === "fulfilled") {
      console.log("Loaded:", result.value);
    } else {
      console.error("Integration failed:", result.reason);
    }
  }

  return results;
}

This waits for every supplied Promise to settle and gives you the outcome of each one.

Scenario D: You want a Promise chain without an `async` function

Sometimes a small function can be expressed naturally as a chain:

function getDisplayName(userId) {
  return fetchUser(userId)
    .then((user) => user.name)
    .catch((error) => {
      console.error("Unable to load user:", error);
      throw error;
    });
}

You don't have to introduce async/await just because it exists. Promise chaining is still useful, particularly when transforming results or composing functions.

A practical decision guide

Situation	A useful approach
Several dependent steps	`async/await` or a returned Promise chain
Several independent operations	`Promise.all()` with `async/await`
Need the outcome of every operation	`Promise.allSettled()`
Simple result transformation	Promise chaining
Complex branching and intermediate values	Often `async/await`
Background work that shouldn't block the caller	Explicit background-task handling
Need to handle each operation's failure separately	Local `try/catch` or per-Promise `.catch()`

These are guidelines, not strict rules. Readability, error-handling requirements, cancellation needs and the behavior expected by the caller all matter.

9. One real-world decision: should the email block registration?

Our registration example assumes that registration isn't complete until the email has been sent.

But is that always the correct design?

Imagine the database save succeeds and the email provider takes five seconds to respond. Should the user wait five seconds before receiving a successful registration response?

Not necessarily.

This is where we must distinguish a JavaScript bug from a product or architecture decision.

Option A: Email is part of the required workflow

If the operation must finish before the caller can proceed, return or await the email Promise.

async function registerUser(input) {
  const user = await saveUser(input);
  await sendWelcomeEmail(user);

  return user;
}

The caller receives the user only after the awaited email operation fulfills. If it rejects, the function rejects unless the error is handled.

Option B: Registration should succeed independently of email delivery

If the user should be registered even when the email provider is temporarily unavailable, don't pretend that the email is part of the same success condition.

A simple illustrative approach is:

async function registerUser(input) {
  const user = await saveUser(input);

  try {
    await sendWelcomeEmail(user);
  } catch (error) {
    console.error("Welcome email failed:", error);
    // Record or schedule a retry if the application supports it.
  }

  return user;
}

This waits for the email attempt but doesn't let its failure reject registration. It is not truly non-blocking, though, because the function still waits for the attempt to settle.

If email delivery should happen independently, a background job or durable queue is usually more appropriate:

Registration request
       |
       v
Save user + record email job
       |
       v
Return registration result
       |
       v
Background worker
       |
       v
Send email and retry if needed

In a production system, you would need to consider how the job is persisted, retried and monitored. A simple fire-and-forget call such as sendWelcomeEmail(user) is not a reliable substitute for a durable background-work mechanism.

This illustrates an important lesson: waiting for an operation, handling its failure and deciding whether it belongs in the critical path are three separate decisions.

10. How to debug confusing Promise execution flow

When asynchronous code behaves unexpectedly, don't start by rewriting everything with async/await. First establish which Promise represents which operation.

Here is a practical checklist.

Step 1: Add logs at the boundaries

function updateProfile(profile) {
  console.log("Starting update");

  return saveProfile(profile).then((savedProfile) => {
    console.log("Profile saved");

    return refreshSearchIndex(savedProfile);
  }).then(() => {
    console.log("Index refreshed");
  });
}

Log before and after each important operation. This helps you see whether the unexpected order is caused by missing Promise composition or by the operation itself.

Step 2: Inspect every asynchronous callback

For every .then() callback, ask:

Does this callback start another asynchronous operation?
Does the next step need to wait for it?
If yes, am I returning its Promise?
Does this callback need to preserve a value for a later step?

For every async function, ask:

Is the relevant operation awaited?
Does the function return the value the caller expects?
Is the rejection handled at the correct level?

Step 3: Inspect the returned value

A callback with braces doesn't implicitly return its contents:

.then((result) => {
  transformResult(result);
})

This callback returns undefined unless it explicitly returns something.

Compare:

.then((result) => {
  return transformResult(result);
})

And:

.then((result) => transformResult(result))

The latter two return the result of transformResult(), including its Promise if it returns one.

Step 4: Check rejection paths, not just successful execution

A chain may appear correct when every operation succeeds but fail when one rejects.

Test:

The first operation rejects.
An inner asynchronous operation rejects.
A callback throws synchronously.
A fallback handles an error.
A caller expects a result but receives undefined.

A successful manual test alone isn't enough to establish correct error propagation.

Step 5: Write down the intended dependency

Before changing code, express the desired workflow:

Save user
   ↓ must finish before
Send email
   ↓ must finish before
Return success

If the actual requirement is different, draw that flow instead. This helps distinguish a missing return or await from an incorrect assumption about which operations must be sequential.

11. Common misconceptions worth remembering

Misconception 1: Every Promise runs asynchronously.

The executor passed to new Promise() runs synchronously. Promise reactions, such as .then() callbacks, run asynchronously.

Misconception 2: Creating a Promise means the current function waits for it.

It doesn't. You must connect its outcome to the relevant Promise chain or await it.

Misconception 3: async automatically waits for all Promises inside a function.

It doesn't. async makes the function return a Promise. Individual asynchronous operations still need to be awaited or explicitly composed when their completion matters.

Misconception 4: Nested Promises are always bad code.

Not true. Resolving a Promise with another Promise and returning Promises from callbacks are normal parts of Promise composition. Deeply nested callbacks may hurt readability, but nesting itself isn't proof of a bug.

Misconception 5: Promise.all() cancels the other operations when one rejects.

It doesn't automatically cancel them. Its returned Promise rejects when one of its inputs rejects, but the remaining operations may continue.

Misconception 6: Converting everything to async/await fixes asynchronous bugs.

It can improve readability, but forgetting await creates the same fundamental problem as forgetting to return a Promise from a chain.

12. A final debugging challenge

Before finishing, predict the output of this example:

console.log("A");

Promise.resolve()
  .then(() => {
    console.log("B");

    Promise.resolve().then(() => {
      console.log("C");
    });
  })
  .then(() => {
    console.log("D");
  });

console.log("E");

What order do you expect?

The correct output is:

A
E
B
C
D

Here's why:

A runs synchronously.
The first .then() callback is scheduled as a Promise reaction.
E runs before Promise reactions are processed.
The first callback runs and logs B. It creates another Promise reaction but doesn't return that inner Promise.
The inner reaction logs C.
The next callback in the outer chain logs D after the first callback's returned value—undefined—fulfills the preceding chain Promise.

This example shows why you can't simply assume that all nested Promise callbacks execute before the next step in the outer chain. Their scheduling and Promise dependencies both matter.

Try modifying the example to return the inner Promise:

console.log("A");

Promise.resolve()
  .then(() => {
    console.log("B");

    return Promise.resolve().then(() => {
      console.log("C");
    });
  })
  .then(() => {
    console.log("D");
  });

console.log("E");

The output is still:

A
E
B
C
D

The visible output happens to be the same in this example, but the Promise dependency is different. With the return, the outer chain explicitly waits for the inner Promise. Without it, the two branches are not connected, even though this particular output order looks identical.

That's an important debugging lesson: a log sequence alone doesn't always prove that asynchronous operations are correctly connected. Test the behavior and rejection paths, not just the happy-path output.

Conclusion

Promises aren't inherently complicated, but their behavior becomes much easier to understand once you distinguish creating an operation from connecting its outcome to the rest of your code.

If you take only a few lessons from this article, remember these:

Return a Promise from a .then() callback when the chain must wait for that operation.
Await a Promise inside an async function when subsequent code depends on its outcome.
Propagate or handle errors intentionally instead of accidentally converting failures into successful results.
Use Promise.all() for independent operations that can run concurrently and choose Promise.allSettled() when you need every operation's outcome.
Don't assume every asynchronous task should block the caller. Decide whether it belongs in the critical path or should be handled by a background-work mechanism.
Debug the dependency between operations, not just the order of console messages.

And remember: the same control-flow bug can appear with Promise chains and async/await. Changing syntax can make code easier to read, but it doesn't replace understanding the behavior you need.

The next time your application logs “Done” before the work is actually done, look for the missing return, the missing await, or an operation that was never connected to the flow in the first place.

That's often where the real bug begins.

💬 Your turn: Have you ever encountered a missing return or await that caused a race condition or made an error disappear? Share the scenario in the comments. Real debugging experiences are often the best way for all of us to learn.

Embeds: Putting a Live NitroIDE Playground Inside Your Docs

Sat, 31 Oct 2026 12:32:01 +0000

Every tutorial has the same weak spot: the code sample. A static block shows what the code looks like. It cannot show what the code does. The reader has to copy it, open an editor, paste it, and run it — and every step in that chain is a step where a reader leaves.

A month ago I wrote about NitroIDE's share engine: the Share button compresses an entire workspace into a ?code= URL parameter, and opening that link rebuilds the workspace locally in the reader's browser. Nothing is uploaded to a server. That post was about sending code to one person. This one is about the layer on top of it: embedding that workspace inside a page, so the reader never has to leave the tutorial at all.

Take any NitroIDE share URL and add ?embed=1 to it. That is the whole API:

<iframe src="https://nitroide.com/tools/codebox.html?embed=1&code=YOUR_SHARE_CODE" width="100%" height="500" frameborder="0"></iframe>

The embed loads a stripped-down, read-only viewer. The full IDE chrome is gone — no file explorer, no console panel, no settings menus. What remains is the two things a reader actually needs: the editor and the live preview, side by side. The reader sees the code and its output in the same frame, on the same page, with nothing to install and no account to create.

Read-only is a deliberate choice, not a missing feature. A tutorial embed is not a workspace; it is a demonstration. If the reader could edit the code in place, every edit would be a fork of the author's example with no way back — and the next reader would see someone else's experiment, not the tutorial. So the embed shows, and the escape hatch handles editing: every embed carries a footer link reading "Built with NitroIDE — open & edit". One click opens the exact workspace in the full editor, where the reader can change anything. Show first, edit second, and never confuse the two.

Where this actually belongs

The honest answer is: anywhere that renders an iframe and where the reader is there to learn. Blog posts, documentation pages, tutorial sites, course material — anywhere a code sample currently sits as a dead block.

It does not belong in a GitHub README. GitHub strips iframes from rendered Markdown, so an embed pasted into a README renders as nothing. That is what the "Open in NitroIDE" badge is for — a link, not a frame — and knowing which of the two a surface accepts is the difference between an embed that works and one that silently vanishes. If the page cannot render an iframe, do not force the embed in; link out instead.

The second place it belongs is less obvious: your own changelog and release notes. A new feature described in prose is a claim; the same feature embedded as a running demo is evidence. When a release note says "the preview now updates without flicker," an embedded playground running the new behaviour lets the reader verify it in ten seconds instead of trusting the sentence.

The details that make an embed feel native, not bolted on

A bare iframe works. A few attributes make it feel like part of the page:

width="100%" and a fixed height around 500px. The embed is a window into a workspace, and a window needs a predictable frame. Let it fill the content column and keep the height tall enough that the preview is readable without scrolling inside a scrolling page.
loading="lazy" on embeds below the fold. A tutorial with five demos should not load five editors before the reader reaches the first one. Lazy loading defers each embed until it scrolls into view.
A title attribute on the iframe. It costs nothing and it is what a screen reader announces; "Live demo: responsive card layout" is a better experience than an unnamed frame.
One demo per concept. An embed is a heavyweight element — a whole editor and a live preview. Three embeds proving the same point are two embeds too many; one well-chosen demo per idea keeps the page fast and the argument sharp.

None of these are NitroIDE features. They are the hosting page's job, and they are the difference between an embed that feels like part of the tutorial and one that feels pasted in.

The limits, stated plainly

An embed inherits every limit of the share link it is built on. The workspace travels inside the URL itself, compressed into the ?code= parameter, so a very large project makes a very long URL. For a tutorial demo — a handful of files, a single concept — that is never a problem. For a full application, it is: use ZIP export for the project and embed a small, focused demo of the idea instead. The embed is for the example, not the app.

The second limit comes from the preview's sandbox. NitroIDE's preview runs in a sandboxed iframe with an opaque origin, which is what keeps code in a shared link from touching the reader's saved projects. The tradeoff is that localStorage, sessionStorage, and cookies are unavailable inside the preview — and in Safari, touching them throws a SecurityError. Demo code that reads localStorage unguarded will crash inside the embed while working fine in a normal tab. Wrap storage access in try/catch in any code you plan to embed, and the same demo runs everywhere.

The third limit is the read-only viewer itself. It hides the console, so a demo whose point is console output — logging, errors, debugging — loses its punchline inside an embed. That is a real constraint, and the honest response is to pick the right surface: embed the demos whose output is visual, and link out to the full editor for the ones whose output lives in the console.

Why this matters more than a nicer code block

Syntax highlighting made code readable. Embeds make it runnable, and that is a different category of change. A readable sample asks the reader to trust the author. A runnable sample lets the reader check the author — change a value, watch the preview move, break it, fix it. That is the feedback loop NitroIDE is built around, except now it happens inside someone else's docs, for a reader who never opened the IDE at all.

The embed is also the quietest distribution NitroIDE has. Every embed carries its own attribution in the footer, and every footer click is a reader who arrived at the full editor from inside a tutorial they were already reading — not from a post, not from an ad, from a working demo. That is the growth loop that does not look like a growth loop: make the tool useful inside other people's pages, and let the pages do the talking.

One parameter, one iframe, one running demo where a dead code block used to be. Try it with the docs example above — paste a share code into the snippet, drop it into a page, and the tutorial stops describing the code and starts running it.

I build NitroIDE — a browser-based IDE where your code never leaves your machine: https://nitroide.com?utm_source=coderlegion&utm_medium=article&utm_campaign=daily-2026-10-31

Don't Let Your Node.js Apps Drown: A Guide to Backpressure

Sat, 31 Oct 2026 09:58:48 +0000

What is Backpressure?

In the world of software development, backpressure is a communication signal sent from a data consumer (the part of the system receiving information) back to a data producer (the part sending it) to tell it to slow down. It occurs when the receiver is being overwhelmed with more data than it can process at that moment. Instead of letting the system crash or run out of memory, backpressure acts as a safety valve to keep the data flow manageable.

The Fast-Food Kitchen Analogy

To understand backpressure, imagine a busy fast-food restaurant. You have a chef (the producer) and a cashier (the consumer). The chef can flip burgers incredibly fast—let's say ten burgers every minute. However, the cashier can only bag the burgers and hand them to customers at a rate of three burgers per minute.

If the chef keeps cooking at full speed, burgers will start piling up on the counter. Eventually, there is no more room on the counter, burgers start falling on the floor, and the kitchen becomes a chaotic mess.

In this scenario, backpressure is the cashier shouting, "Hey, stop cooking for a second! I've run out of counter space!" Once the cashier clears some of the backlog, they give the chef the green light to start cooking again. This feedback loop ensures the "buffer" (the counter) never overflows.

Why Backpressure Matters in Tech

As a senior developer working with Node.js, backpressure is a daily reality. Because Node.js is asynchronous and event-driven, it is very easy to read data from a source—like a massive log file or a database—much faster than we can write it to a destination, like a network socket or another file.

Engineers use backpressure management to prevent "Memory Leaks" or "Buffer Bloat." Without it, Node.js would attempt to store all the incoming data in your system's RAM (Random Access Memory) while waiting for the slow destination to catch up. If the file is 10GB and your server only has 4GB of RAM, your application will crash with an OutOfMemory error. By implementing backpressure, we ensure the server only reads what it can actually handle, maintaining a low memory footprint and high stability.

Implementation in Node.js

In Node.js, backpressure is built into the Stream API. When you use the .write() method on a writable stream, it returns a boolean value. If it returns false, that is the signal that backpressure is occurring and you should stop sending data.

const fs = require('fs');

// Create a readable stream (The Producer)
const readable = fs.createReadStream('./massive-video-file.mp4');

// Create a writable stream (The Consumer)
const writable = fs.createWriteStream('./copy-of-video.mp4');

// The 'pipe' method automatically handles backpressure for us!
// It pauses the readable stream when the writable stream is full.
readable.pipe(writable);

// If we were doing this manually, it would look like this:
/*
readable.on('data', (chunk) => {
  const canContinue = writable.write(chunk);
  if (!canContinue) {
    // Backpressure detected! Pause the producer
    readable.pause();
  }
});

// Listen for the 'drain' event to know when it is safe to resume
writable.on('drain', () => {
  readable.resume();
});
*/

The Takeaway

Backpressure isn't a bug; it's a fundamental feature of robust system design. It represents the wisdom of knowing when to say "enough for now," ensuring that your fast components don't accidentally destroy your slower ones by being too efficient. Master the flow, and you master the stability of your entire stack.

Enjoyed this breakdown? Support my open-source work on Buy Me a Coffee or explore react-hook-lab!

Originally published on my blog. You can read the alternative breakdown here.

Your Tests Are Green and Prove Nothing: 4 Signs You're Testing the Mock

Sat, 31 Oct 2026 03:38:56 +0000

Coverage says 94%. Every test is green. You deploy on Friday afternoon, and by Monday a customer has found a bug in the exact function you "tested".

When you open the test, the reason is obvious in hindsight. The test never ran your code. It ran a fake version of everything around it and then asserted that the fake behaved like a fake.

Here are four ways this happens, and a check you can do in a minute to see how many of your own tests are guilty.

1. You Mocked the Thing You Are Testing

// pricing.ts
export function applyDiscount(total: number, code: string) {
  return code === 'SAVE10' ? total * 0.9 : total;
}

// checkout.test.ts
import * as pricing from './pricing';

vi.spyOn(pricing, 'applyDiscount').mockReturnValue(90);

test('applies discount at checkout', () => {
  expect(checkout(100, 'SAVE10')).toBe(90);
});

This passes if applyDiscount is correct. It also passes if applyDiscount returns NaN, because the test replaced it with a hard-coded 90. You are testing that checkout can return the number you handed it.

Fix: mock what is outside your code, such as network, clock and payment providers. Run your own logic for real.

2. You Assert the Calls, Not the Outcome

test('saves the user', async () => {
  await createUser({ email: '*Emails are not allowed*' });
  expect(db.insert).toHaveBeenCalledWith('users', { email: '*Emails are not allowed*' });
});

This test proves the function called insert with those arguments. It does not prove a user exists. If someone renames the table, adds a required field or changes the query, this test keeps passing against the mock while real users stop being saved.

It also fails for the wrong reason. Refactor the internals without changing behavior, and it turns red, so people learn that failing tests are noise.

Fix: assert what a user or caller would observe.

test('saves the user', async () => {
  await createUser({ email: '*Emails are not allowed*' });
  const user = await findUserByEmail('*Emails are not allowed*');
  expect(user?.email).toBe('*Emails are not allowed*');
});

3. The Fake Database Only Says Yes

A mocked database returns whatever you tell it to. A real one has rules:

A unique index rejects duplicate emails.
A required field rejects a missing value.
A foreign key rejects an ID that does not exist.
A query with a typo in a field name returns nothing.

None of these exist in a mock, so none of these bugs can appear in your tests. They show up in production, on the first real duplicate signup.

Fix: for anything that touches storage, test against a real database, either a throwaway local instance or an in-memory one with the same engine, reset between tests. It is slower than a mock, but it is the only thing that can fail the way production fails.

test('rejects a duplicate email', async () => {
  await createUser({ email: '*Emails are not allowed*' });
  await expect(createUser({ email: '*Emails are not allowed*' })).rejects.toThrow();
});

You cannot write that test against a mock that always resolves.

4. Snapshots Approved Without Reading

expect(renderInvoice(order)).toMatchSnapshot();

A snapshot records whatever the output is today and fails when it changes. It does not know whether today's output is correct. When it fails, the usual reaction is to press "update" and move on, so the test stores bugs as the expected answer.

Fix: use snapshots for small, stable things, and assert the fields that matter for anything involving money, permissions or dates:

const invoice = renderInvoice(order);
expect(invoice.total).toBe(118.0);
expect(invoice.lines).toHaveLength(2);

The 60-Second Sabotage Check

Here is how to find out whether a test protects you. Take a function you care about, break it on purpose, and run its tests.

export function applyDiscount(total: number, code: string) {
  return total; // sabotage: discount never applies
}

Then ask one question: did a test fail?

If yes, that test is doing its job.
If no, you have found a test that would have stayed green while the feature was broken in production.

Revert the change, and fix or delete the test that did not notice. Try this on three important functions and you will learn more about your suite than coverage ever told you. The formal version of this idea is called mutation testing, and tools exist that automate it, but doing it by hand on your most critical code is a good start.

What to Mock, and What Not To

Mock it	Run it for real
Network calls to third parties	Your own business logic
The clock and random numbers	Your database queries
Email and SMS sending	Validation and permission rules
Payment providers	Anything that can fail on real data

The rule is that you mock the edges, the places where your code talks to someone else, and keep everything in the middle real.

The Rule

A test that cannot fail when the code is wrong is not a test. Mock the world outside your app, assert outcomes instead of calls, and use sabotage to check whether your tests notice.

Quick audit: pick the three functions that would hurt most if they broke, such as pricing, permissions and sign-up. Break each one on purpose. Count how many tests turn red. If the answer is zero for any of them, that is your next ticket.

If you want a Next.js starting point to build and test on, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

What is the most misleading green test you have ever found? Share it in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Building a static blog with Sitelo, one function per page

Fri, 30 Oct 2026 14:35:56 +0000

In my last post on DEV I explained why I built Sitelo: most websites are documents, and documents shouldn't need a JavaScript application to reach the browser. That post was the argument. This one is the practice.

We'll build a small blog from an empty folder: a home page, post pages generated from JSON files, and a comments section that stays fresh on an otherwise static page. Along the way I'll point out what Sitelo is doing at each step, and what it deliberately doesn't do.

The whole framework fits in one sentence, and it's worth keeping in mind as we go:

Files are routes. Functions return HTML. Browser code is explicit.

Everything below is that sentence, applied.

Step 1: one page is one function

Start with an empty folder and install Sitelo. It needs Node 20.19+ or 22.12+, and Vite is bundled, so there's nothing else to install or configure.

npm init -y
npm pkg set type=module
npm install -D sitelo

Add two scripts to package.json:

"scripts": {
  "dev": "sitelo",
  "build": "sitelo build"
}

Now the first page. Any file in src/ ending in .ht.js is a page, and its default export returns HTML:

// src/index.ht.js
export default () => `
  <html lang="en">
    <head>
      <title>My blog</title>
      <link rel="stylesheet" href="/styles.css">
    </head>
    <body>
      <h1>Hello world</h1>
    </body>
  </html>
`

Create a src/styles.css with a few rules, then run npm run build and you get:

dist/
  index.html   ← your HTML, with <!DOCTYPE html> added
  styles.css   ← bundled and minified, because the page linked it
  404.html     ← a default one, until you write src/404.ht.js

The function ran once, at build time, in Node. The browser gets the string it returned and nothing else: no runtime, no hydration, no bundle of page code. If you want JavaScript in the browser, you add a <script> tag, the same as you would in a hand-written HTML file.

Template literals aren't the only option. A page can also return JSX from a .ht.jsx or .ht.tsx file, which is rendered to a static string with react-dom/server. Or you can use my companion library javascript-to-html, where every element is a function. I'll stick with template literals here because they need no explanation.

Step 2: a layout is just another function

A blog needs the same <head> and header on every page. There's no layout system to learn for this, because a layout is a function that takes some HTML and wraps it:

// src/lib/layout.js
export const layout = ({ title, children }) => `
  <html lang="en">
    <head>
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width, initial-scale=1">
      <title>${title} · My blog</title>
      <link rel="stylesheet" href="/styles.css">
    </head>
    <body>
      <header><a href="/">My blog</a> · <a href="/blog">Posts</a></header>
      <main>${children}</main>
    </body>
  </html>
`

// src/index.ht.js
import { layout } from './lib/layout.js'

export default () => layout({
  title: 'Home',
  children: '<h1>Hello world</h1><p>Welcome to my blog.</p>',
})

layout.js doesn't end in .ht.js, so it isn't a page. It also never ends up in dist/. Sitelo only emits a JavaScript or TypeScript file when your HTML references it with a <script src>; a module you only import from page code stays on the build side. That rule matters more later, when the helpers you import hold API keys or database code. They can't leak into the browser by accident.

The same rule works in the other direction. Write <script type="module" src="/main.ts"></script> and Sitelo bundles src/main.ts with esbuild, emits main.js, and rewrites the tag to match. Browser code exists only where you asked for it.

Step 3: posts from JSON files

Now for the posts. I'll keep them in the repo as JSON, one file per post, outside src/ because they're content rather than code:

// data/posts/hello-world.json
{
  "title": "Hello, world",
  "date": "2026-10-01",
  "body": "<p>My first post.</p>"
}

The post page lives at src/blog/[slug].ht.js. The square brackets make it a dynamic route, and it exports two more functions next to the page itself:

generateStaticParams() lists the pages to build, one per post.
data() loads what one page needs. Whatever it returns arrives in the page function as data.

// src/blog/[slug].ht.js
import { readJsonCollection } from 'sitelo/data'
import { layout } from '../lib/layout.js'

const posts = () => readJsonCollection('data/posts', { sort: '-date' })

export async function generateStaticParams() {
  return (await posts()).map((post) => ({ slug: post.slug }))
}

export async function data({ params }) {
  return (await posts()).find((post) => post.slug === params.slug)
}

export default ({ data: post }) => layout({
  title: post.title,
  children: `
    <article>
      <h1>${post.title}</h1>
      <time datetime="${post.date}">${post.date}</time>
      ${post.body}
    </article>
  `,
})

readJsonCollection reads every .json file in the folder and takes each slug from its file name. It parses each file once per build, however many pages ask for it, and two posts with the same slug fail the build instead of one silently overwriting the other.

The index page is the same idea without the brackets:

// src/blog/index.ht.js
import { readJsonCollection } from 'sitelo/data'
import { layout } from '../lib/layout.js'

export const data = () => readJsonCollection('data/posts', { sort: '-date' })

export default ({ data: posts }) => layout({
  title: 'Posts',
  children: `
    <h1>Posts</h1>
    <ul>
      ${posts.map((post) => `<li><a href="/blog/${post.slug}">${post.title}</a></li>`).join('')}
    </ul>
  `,
})

A build now writes dist/blog/index.html and one dist/blog/<slug>/index.html per post. In the dev server (npm run dev) pages render on request through Vite, so editing a JSON file reloads the browser, and an error points at the exact line of your page in the terminal.

If your posts live in a CMS instead, data() can fetch them. Sitelo exports fetchWithCache, a drop-in for fetch that caches responses during the build. A 500-page site then doesn't make 500 identical requests to your API.

Step 4: fresh comments on a static page

Comments are the classic reason static blogs reach for a client-side widget or give up and go server-rendered. Sitelo's answer is a server island: the page stays static, and one marked region is rendered on the server when someone views it.

An island is a module in src/islands/ whose default export returns HTML. Islands are fragments rather than pages, so the file is plain .js, not .ht.js:

// src/islands/comments.js
import { getComments } from '../lib/comments.js'

const escape = (s) => String(s).replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`)

export default async function comments({ props }) {
  const list = await getComments(props.postId)
  if (!list.length) return '<p>No comments yet.</p>'
  return `<ul>${list.map((c) => `<li><b>${escape(c.author)}</b> ${escape(c.text)}</li>`).join('')}</ul>`
}

getComments is whatever your comment store is: a database query, a call to a hosted service. Comments are user input, hence the escape.

Place the island in the post page with island(). The third argument is the fallback HTML that ships in the static build, and when: 'visible' waits until the reader scrolls near the comments before making the request:

// src/blog/[slug].ht.js (the page function)
import { island } from 'sitelo/islands'

export default ({ params, data: post }) => layout({
  title: post.title,
  children: `
    <article>…</article>
    ${island('comments', { postId: params.slug }, '<p>Loading comments…</p>', { when: 'visible' })}
    <script type="module" src="/islands.js"></script>
  `,
})

The script tag loads a two-line client that finds the placeholders and fetches them:

// src/islands.js
import { mountIslands } from 'sitelo/islands/client'

mountIslands()

In npm run dev and sitelo preview this already works: Sitelo serves islands at /_sitelo/islands/<name>. In production your static host serves the pages, and you mount a small handler wherever you can run server code. createIslandsHandler from sitelo/islands/server takes a Web Request and returns a Response, so it fits a serverless or edge function. The repo has Netlify and Vercel versions.

A few details I cared about getting right:

Props are untrusted. They're embedded in the page and sent back on the request, so anyone can edit them. Set SITELO_ISLANDS_SECRET and the build signs every placeholder with HMAC-SHA256, and the handler rejects edited props with a 403.
Islands are server-only. The rule from Step 2 applies: nothing references comments.js from HTML, so it never reaches dist/, and neither does your database code.
Failure is graceful. If the island endpoint is down or slow (10 seconds by default), the fallback HTML stays where it was. The page still works.

Step 5: let the build check your work

The blog works. The last step is a config file, and it's where Sitelo earns its keep on a real site:

// sitelo.config.js
export default {
  site: 'https://myblog.example',
  rss: {
    site: 'https://myblog.example',
    title: 'My blog',
    description: 'Latest posts',
    routePrefix: '/blog',
  },
  images: true,
  linkCheck: 'error',
  lighthouse: {
    thresholds: { accessibility: 100, 'best-practices': 95, seo: 100 },
  },
}

Here's what each line buys you:

site generates dist/sitemap.xml from every route, including the ones generateStaticParams produced.
rss writes dist/rss.xml with an item for every page under /blog.
images turns each <img> into a resized, WebP srcset with width and height set, so a 3000px hero photo no longer ships to phones. It needs sharp installed, and it works in the dev server too, so what you see is what you ship.
linkCheck: 'error' resolves every internal <a href> against the files the build actually wrote, the way a static host would. A typo like /blgo fails the build with the page it's on.
lighthouse gives sitelo lighthouse thresholds to enforce. Any score under its threshold exits non-zero, so it can gate CI. Like sharp, Lighthouse is an optional install.

I left performance out of the thresholds on purpose. It depends on the machine running the audit, and a page that scores 100 on a laptop can score around 60 on a shared CI runner. Accessibility, best practices and SEO are properties of the HTML itself, so they score the same anywhere.

One check needs no config. If a page links a script or stylesheet that doesn't exist in src/ or public/, the build fails and lists the paths it tried. That's why Step 1 asked you to create styles.css first.

Every build ends with a report of what you're shipping: file counts and sizes per type, the largest files, and how long each phase took. On a static site, "how much JavaScript am I sending?" should be a number you see every time, not something you go looking for.

Building it with a coding agent

I designed Sitelo with coding agents in mind, and the small surface area matters even more for them than for people. Ask an agent to add a page to an unfamiliar framework and it reaches for whatever it has seen most: React components, Next.js conventions, Astro frontmatter. With Sitelo there's less to get wrong, because there's less of everything. A page is a function, a route is a file, and browser code is a <script> tag.

To close the remaining gap, Sitelo ships two Agent Skills: one for the framework (pages, routing, data, islands, deployment) and one for its component library. Install them into your project and Claude Code, Cursor, Codex and other agents load them when a task needs them:

npx skills add Paul-Browne/sitelo

The skills also ship inside the npm package, matching the version you installed. Sitelo's test suite checks every API the skills mention against the package's real exports, so a renamed or removed API fails the tests before it reaches a release. For agents that prefer to read a URL, the docs publish sitelo.dev/llms.txt, plus a single-file llms-full.txt with every guide in Markdown.

The build checks from Step 5 help here too. An agent that invents a stylesheet path or links to a page that doesn't exist gets a failed build naming the problem, not a site that quietly ships broken.

What we built, and when not to use it

In five steps we went from an empty folder to a blog with:

a home page, a post index and one page per JSON file
comments rendered on the server at view time, on otherwise static pages
a sitemap, an RSS feed and responsive images
a build that fails on broken links and missing assets, plus a Lighthouse gate for accessibility and SEO

The browser receives HTML, one stylesheet and a 1.7 kB island loader. That's all, because those are the only things we asked for.

Sitelo isn't the right tool for everything. JSX pages render to static HTML only, so onClick handlers and hooks do nothing in the browser. If you're building an application, with client-side state and routing, use an application framework. Astro, Next.js and Eleventy are all excellent at what they do. Sitelo is for docs, blogs, marketing sites and content sites, where "view source" should show what you wrote.

If that sounds like your next project:

Docs: sitelo.dev/docs
Code (MIT licensed): github.com/Paul-Browne/sitelo
Package: npmjs.com/package/sitelo

The repo includes a complete blog example that goes further than this post, with Markdown posts. And if you find something that makes Sitelo more complicated than it needs to be, please open an issue. Keeping it boring is the whole point.

Your Next.js redirect() Silently Does Nothing Because It's Inside a try/catch

Fri, 30 Oct 2026 10:08:42 +0000

A user fills in your form and clicks "Create post". The post is saved in the database. And the page shows "Could not create post".

They try again. Now there are two posts.

Nothing is wrong with your database. Your error handling caught something it was never supposed to catch.

The Code That Causes It

// app/actions.ts
'use server';

import { redirect } from 'next/navigation';

export async function createPost(formData: FormData) {
  try {
    const post = await db.post.create({
      data: { title: String(formData.get('title')) },
    });

    redirect(`/posts/${post.id}`);
  } catch (err) {
    return { error: 'Could not create post' };
  }
}

It reads perfectly. Save the post, go to its page, and if anything fails, return an error. A tidy, defensive pattern that you have probably written a hundred times in other frameworks.

Why It Breaks

In Next.js, redirect() does not return. It throws a special error, and the framework catches that error higher up and turns it into a redirect response.

That means your catch block receives it first. Your code swallows the redirect, returns { error: ... }, and the framework never sees it.

The same is true for notFound(), which also works by throwing. Both are written to stop execution immediately, which is why TypeScript treats them as functions that never return.

Why It Is Hard to Catch

The data is saved. The only visible symptom is a wrong error message, so it looks like a UI bug, not a logic bug.
It is inconsistent in your head. The same redirect() works fine outside a try, so you assume it is fine everywhere.
Your logs are confusing. If you log the caught error, you will see a strange error with a NEXT_REDIRECT digest and think something crashed.
It tempts you to retry. Users see an error, submit again and create duplicates.

Fix 1: Keep redirect() Outside the try Block

Only wrap the code that can genuinely fail, and redirect afterwards:

export async function createPost(formData: FormData) {
  let postId: string;

  try {
    const post = await db.post.create({
      data: { title: String(formData.get('title')) },
    });
    postId = post.id;
  } catch (err) {
    return { error: 'Could not create post' };
  }

  redirect(`/posts/${postId}`);
}

The try now covers only the database call. If it fails, you return the error. If it succeeds, execution continues to redirect(), which is outside any catch, so it can do its job.

This is the cleanest option, and it is the one I use by default.

Fix 2: Rethrow If You Must Catch Everything

Sometimes the redirect() sits deep inside a helper, and restructuring is awkward. Then let the framework's own errors pass through your catch. Newer Next.js versions provide a helper for exactly this:

import { redirect, unstable_rethrow } from 'next/navigation';

try {
  // ...work that may call redirect() or notFound() somewhere inside
} catch (err) {
  unstable_rethrow(err); // lets redirect/notFound errors continue upward
  return { error: 'Something went wrong' };
}

The name says it is not final, so check the documentation for the version you use. If it is not available in yours, structure your code as in Fix 1.

Fix 3: Do Not Use Catch-All to Control Flow

A broader habit helps here. A catch (err) with no check is a very wide net. Catch what you expect:

catch (err) {
  if (err instanceof DuplicateTitleError) {
    return { error: 'You already have a post with that title' };
  }
  throw err; // anything else is not yours to handle here
}

Rethrowing what you do not recognize means the framework's own signals, real crashes and bugs all reach the place that is meant to handle them.

Where Else This Bites

notFound() inside try. A missing record becomes your generic error instead of a 404 page.
Route handlers and Server Components. The same rule applies: any try/catch around a call that can redirect or 404 will swallow it.
.catch() on a promise. somePromise.catch(() => null) has the same effect if the promise's code calls redirect().
Wrapper functions. A helper like withErrorHandling(fn) that catches everything will break redirects in every function it wraps.

Quick Checklist

Situation	What to do
`redirect()` after a database write	Put the write in `try`, `redirect()` after it
`notFound()` when a record is missing	Call it outside the `try`, or rethrow
A shared error-handling wrapper	Make it rethrow framework errors
Unsure	Catch specific error types, rethrow the rest

The Rule

redirect() and notFound() signal by throwing, so a catch around them will eat the signal. Keep them outside try blocks, or rethrow what you do not recognize.

Quick audit: search your project for redirect( and notFound(. For each hit, look upward. If it sits inside a try, you have either a bug now or one waiting for the day the code path is used.

If you want a Next.js starting point where forms and actions are set up sensibly from day one, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Have you ever shipped a form that showed an error after it had succeeded? Tell me in the comments how long it took you to find it.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Building Shiori GLOBAL: How We Created an AI-Powered Circular Learning Network for Students

Thu, 29 Oct 2026 20:04:38 +0000

Hey CoderLegion community! 👋

Millions of educational books sit unused on shelves after a student completes a academic year, while millions of other students struggle to afford high-quality learning resources.

To solve this, I built Shiori GLOBAL 🌿—an AI-powered circular learning platform designed to help students buy, sell, donate, swap, and discover educational books while tracking their environmental and social impact.

Here is a quick breakdown of how we engineered Shiori GLOBAL to transform book sharing for students:

🤖 1. The AI Book Scanner: Frictionless Listing
Manually filling out details like title, author, edition, class, subject, and publisher deters students from listing their unused books.

The Solution: We integrated an AI-powered book detection flow. A user simply uploads or camera-scans a book cover, and our AI extracts:

Title & Author

Class, Subject & Edition

Estimated Condition & Publisher

Developer Takeaway: Reducing user friction through computer vision / AI extraction boosts user engagement and catalog expansion drastically.

🔄 2. Circular Economy Mechanics (Buy, Sell, Donate, Swap)
Educational resource distribution shouldn't just be about commercial selling. Shiori supports multiple transaction types to maximize resource reuse:

Smart Marketplace: Categorized by CBSE, ICSE, Competitive Exams, and School/College books.

Hyper Local Matching: Sorting listings by approximate distance so students can swap or claim free books within their local community.

Trust & Safety: Direct communication channels connecting verified book owners seamlessly.

🌱 3. Impact Tracking & Sustainability
Giving every book a second life doesn't just save money it reduces paper waste and carbon footprint. Shiori includes community impact tracking to quantify how many trees and litres of water students save by reusing textbooks.

💡 Developer Tip for Young Creators
When building projects, focus on solving real community problems. Technology is at its best when it creates a circular ecosystem turning one student's completed journey into another student's learning opportunity!

What do you think about using AI computer vision to automate marketplace listings? I'd love to hear your thoughts and suggestions in the comments below! 🚀

Hi! I’m Aprajita Singh, a passionate student developer building AI-driven solutions for real-world impact. I love creating tools around AI, personal safety, and sustainable technology.

Let’s connect on GitHub /Linkedin!
GitHub : https://github.com/singhaprajita183-maker
Linkedin : https://www.linkedin.com/in/aprajita-singh-b20bb7391/

JSON-LD Recipes: BlogPosting, FAQPage, and SoftwareApplication Without a Plugin

Thu, 29 Oct 2026 12:54:51 +0000

Two weeks ago I wrote the overview: a static indie site needs three machine-readable files — sitemap, schema, and llms.txt. That post told you what each one is for. This one is the part I left out on purpose: the actual code. I run NitroIDE, a browser IDE on a static host with no server, no build step, and no plugin system. There is no SEO plugin to install, so every block of structured data on the site is a <script type="application/ld+json"> block I wrote by hand. Three recipes cover almost everything an indie site needs. Copy them, change the values, validate before shipping — and, crucially, keep them honest, because schema that describes content the page does not show is a mismatch waiting to be flagged.

Recipe 1: SoftwareApplication — the product page. This one lives on the homepage and answers a single question: what is this thing? For NitroIDE it names the product, its category, that it runs in a web browser, that it is free, and the features a human would actually recognise from the page. Rules: operatingSystem for a web tool is "Web Browser"; every item in featureList must be a feature the homepage actually shows; one block, one product. The mistake that voids this recipe is version drift — NitroIDE's real block carries a softwareVersion field, and it changes in the same commit as the version it describes.

Recipe 2: BlogPosting — every article. Every blog article on NitroIDE carries a compact BlogPosting block in its <head>: headline, description, author, publisher, the page URL, and two dates. mainEntityOfPage is the canonical URL of the article itself. dateModified is the field that makes updates visible: when I correct or extend an article, dateModified moves and datePublished does not. The mistake that voids this recipe is copy-paste without editing — check that mainEntityOfPage equals the URL of the page you are looking at.

Recipe 3: FAQPage — only where the page really answers questions. NitroIDE articles end with a real FAQ section, and the schema mirrors it exactly — same questions, same answers, in the same words. No marketing, no link, no call to action in an accepted answer. The mistake that voids this recipe is the mirror breaking: the visible FAQ and its JSON-LD block change in the same edit, every time, no exceptions.

How to validate without a plugin: (1) Paste the page URL into a structured-data testing tool and confirm all three types parse. (2) Read the parsed output against the visible page, field by field. (3) After any edit to a page, re-check that page's blocks. JSON-LD is just JSON inside a script tag, so it breaks exactly like JSON breaks — a trailing comma, an unescaped quote, a smart quote. If the testing tool reports nothing at all, check the JSON first.

The whole recipe card: SoftwareApplication on the product page (update the version in the same commit as the release); BlogPosting on every article (never clone a block without editing it); FAQPage only where the page visibly answers questions (change the schema in the same edit as the FAQ itself); validate every page with a structured-data test before shipping, and re-check after edits. None of this needs a plugin, a build step, or a server.

I build NitroIDE — a browser-based IDE where your code never leaves your machine: https://nitroide.com?utm_source=coderlegion&utm_medium=article&utm_campaign=daily-2026-10-29

Stop Syncing State With useEffect: 4 Bugs That Disappear When You Delete the Effect

Thu, 29 Oct 2026 10:55:28 +0000

Here is a pattern I see in almost every React codebase I read:

const [fullName, setFullName] = useState('');

useEffect(() => {
  setFullName(firstName + ' ' + lastName);
}, [firstName, lastName]);

It works. It also renders twice every time a name changes, shows a stale value for one frame, and is a bug waiting to happen when someone adds a third dependency and forgets to list it.

The fix is to delete the effect. Here are four cases where that is the right move.

Why These Effects Cause Bugs

An effect runs after React has painted the screen. So any state you set inside it means:

React renders with the old value and paints it.
The effect runs and calls setState.
React renders again with the new value.

The user can see step 1. That is the flicker. And every effect you add is another place where the dependency list can silently drift out of date.

Case 1: Derived Values

If you can calculate something from props or state you already have, do not store it:

// Before
const [fullName, setFullName] = useState('');
useEffect(() => {
  setFullName(firstName + ' ' + lastName);
}, [firstName, lastName]);

// After
const fullName = firstName + ' ' + lastName;

No state, no effect, no extra render, and it can never be out of sync, because it is recalculated every time.

The same goes for filtering and sorting:

// Before: two sources of truth
const [visible, setVisible] = useState(items);
useEffect(() => {
  setVisible(items.filter((i) => i.active));
}, [items]);

// After
const visible = items.filter((i) => i.active);

If the calculation is genuinely expensive, wrap it in useMemo. Measure first. For a few hundred items, plain code is fine.

Case 2: Resetting State When a Prop Changes

This is the one people struggle with most:

function Profile({ userId }: { userId: string }) {
  const [comment, setComment] = useState('');

  useEffect(() => {
    setComment(''); // reset when the user changes
  }, [userId]);

  return <textarea value={comment} onChange={(e) => setComment(e.target.value)} />;
}

When userId changes, the old comment shows for one frame, then clears. If you have several pieces of state, you need one reset line for each, and you will forget one.

The fix is the key prop:

function ProfilePage({ userId }: { userId: string }) {
  return <Profile key={userId} userId={userId} />;
}

function Profile({ userId }: { userId: string }) {
  const [comment, setComment] = useState('');
  return <textarea value={comment} onChange={(e) => setComment(e.target.value)} />;
}

When the key changes, React treats it as a different component: it throws away the old one, including all its state, and mounts a fresh one. Every piece of state resets, with no effect and no flicker. Remember this one, because it solves a whole category of "why is the old data still there" bugs.

Case 3: Logic That Belongs in an Event Handler

const [submitted, setSubmitted] = useState(false);

useEffect(() => {
  if (submitted) {
    sendOrder(cart);
    setSubmitted(false);
  }
}, [submitted, cart]);

return <button onClick={() => setSubmitted(true)}>Buy</button>;

This uses an effect as a delayed event handler. It is hard to follow, and it can fire again if cart changes while submitted is still true.

Put the logic where the event happens:

function handleBuy() {
  sendOrder(cart);
}

return <button onClick={handleBuy}>Buy</button>;

The rule of thumb: if something happens because the user did something, it belongs in an event handler. If it happens because the component appeared on screen, it can be an effect.

Case 4: Notifying a Parent

useEffect(() => {
  onChange(value);
}, [value, onChange]);

This calls the parent after the render, so the parent and child briefly disagree, and it can trigger extra renders in both. Call the parent in the same handler that changes the value:

function handleChange(next: string) {
  setValue(next);
  onChange(next);
}

Both updates are batched into one render.

So When Is an Effect Right?

Effects are for synchronizing with something outside React:

Subscribing to a browser event, a WebSocket or a timer
Starting and cleaning up a third-party widget
Sending an analytics event because a page was shown
Fetching data on mount (with a cleanup, so a slow response cannot overwrite a newer one)

That last point deserves care, because an effect that fetches can show old results if responses arrive out of order. I wrote about that race condition in a separate article about search inputs. If your library offers one, a data-fetching library or a framework's server data loading removes the need for the effect altogether.

Quick Checklist Before You Write an Effect

Question	If yes
Can I calculate it from existing props or state?	Calculate it during render
Am I resetting state when a prop changes?	Use `key`
Does it happen because the user did something?	Put it in the event handler
Am I telling the parent something changed?	Call the parent in the handler
Am I connecting to something outside React?	An effect is right

The Rule

An effect that only calls setState based on other state or props is almost always a bug waiting to happen. Compute it during render, reset with key, and handle events in handlers.

Quick audit: search your project for useEffect and read the body of each one. Count how many do nothing but set state. Each one is a candidate for deletion, and the component usually gets shorter and faster when you remove it.

If you build with Next.js and React and want a clean starting point, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

What is the strangest useEffect you have ever found in a codebase? Share it in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Mastering the Native Drag and Drop API in React

Thu, 29 Oct 2026 10:24:46 +0000

What is the Drag and Drop API?

The Drag and Drop API is a built-in browser capability that allows web applications to make elements on a webpage interactive through dragging and dropping. Instead of forcing users to click buttons or select items from drop-down menus, this browser feature enables users to click on an item, hold down the mouse button or touchscreen, move the item across the screen, and release it over a designated area. The browser automatically tracks the movement coordinates, mouse state, and transfer data throughout the entire process.

At its core, this API exposes a set of event listeners—hooks provided by the browser to run code when specific interactions happen—that fire as an item is picked up, dragged over drop targets, and finally released.

A Real-Life Analogy: The Corkboard and Sticky Notes

Imagine you have a physical corkboard on your office wall divided into three columns: "To Do," "In Progress," and "Done." Each task is written on a physical sticky note.

When you decide to start working on a task, you place your finger on a sticky note in the "To Do" column, lift it off the board, hover it across the room over to the "In Progress" column, and press it onto the corkboard. During this entire movement, you are carrying both the physical note and the context of what task is written on it. The board itself does not need to send a letter to an assistant asking to move the note; your hands handle the position, while the board simply provides the surface to receive it.

This is precisely how the Drag and Drop API works on a screen. The draggable element acts as the sticky note, the data payload attached to the drag event acts as the text on the note, and the drop target acts as the receiving column on the corkboard.

Why It Matters in Tech Today

In modern web engineering, user experience (UX) directly impacts engagement and product adoption. Complex interfaces like Kanban boards (such as Trello or Jira), file management dashboards (like Google Drive), and custom page builders (like Wix or Squarespace) rely heavily on drag-and-drop interactions to make software feel natural and tactile.

Engineers use the native Drag and Drop API to create fluid interfaces without dragging down performance. Without this browser-native API, software developers would have to write complex, prone-to-bugs math scripts that manually track mouse pixel coordinates on every screen frame. Utilizing the browser's built-in events prevents memory leaks, reduces CPU usage, and saves hundreds of hours of manual positioning logic.

Furthermore, when building file uploading components, this API allows users to drag files straight from their computer's desktop into a browser window, bridging the gap between desktop operating systems and web applications.

Building a Drag and Drop Task List in React

Below is a simple React component that uses the browser's native Drag and Drop API to move tasks between two lists.

import React, { useState } from 'react';

export default function TaskBoard() {
  const [tasks, setTasks] = useState([
    { id: '1', title: 'Design Database Schema', status: 'todo' },
    { id: '2', title: 'Build Express Route', status: 'todo' },
  ]);

  // Triggered when the user starts dragging an item
  const handleDragStart = (event, id) => {
    event.dataTransfer.setData('text/plain', id);
  };

  // Necessary to allow dropping into a container
  const handleDragOver = (event) => {
    event.preventDefault();
  };

  // Triggered when the item is dropped
  const handleDrop = (event, targetStatus) => {
    event.preventDefault();
    const taskId = event.dataTransfer.getData('text/plain');
    
    setTasks((prevTasks) =>
      prevTasks.map((task) =>
        task.id === taskId ? { ...task, status: targetStatus } : task
      )
    );
  };

  return (
    <div style={{ display: 'flex', gap: '20px', padding: '20px' }}>
      {['todo', 'done'].map((status) => (
        <div
          key={status}
          onDragOver={handleDragOver}
          onDrop={(e) => handleDrop(e, status)}
          style={{
            width: '200px',
            minHeight: '200px',
            border: '2px dashed #ccc',
            padding: '10px',
          }}
        >
          <h3>{status.toUpperCase()}</h3>
          {tasks
            .filter((task) => task.status === status)
            .map((task) => (
              <div
                key={task.id}
                draggable
                onDragStart={(e) => handleDragStart(e, task.id)}
                style={{
                  padding: '10px',
                  marginBottom: '8px',
                  backgroundColor: '#4A90E2',
                  color: '#fff',
                  cursor: 'grab',
                }}
              >
                {task.title}
              </div>
            ))}
        </div>
      ))}
    </div>
  );
}

Key Takeaway

The Drag and Drop API transforms rigid web interactions into intuitive, tactile experiences by letting the browser perform the heavy lifting of mouse tracking and state transfers. Mastering this native web feature enables engineers to craft modern, highly interactive web applications with minimal overhead and zero external dependencies.

Enjoyed this breakdown? Support my open-source work on Buy Me a Coffee or explore react-hook-lab!

Originally published on my blog. You can read the alternative breakdown here.

Use Native structuredClone() Instead of JSON.parse(JSON.stringify())

Thu, 29 Oct 2026 06:57:00 +0000

Deep cloning objects in JS used to require third-party libraries like Lodash or hacky JSON serialization that dropped Date objects, Map, Set, and RegExp.

JavaScript
const original = {
user: "Joseph",
joined: new Date(),
roles: new Set(["admin", "designer"]),
};

// Loses Date instances and sets
const badClone = JSON.parse(JSON.stringify(original));

// Native browser & Node.js deep clone (zero dependencies)
const cleanClone = structuredClone(original);

Why it changes your career: Replacing heavy third-party utility libraries with native browser APIs shrinks your bundle size and eliminates unnecessary dependency risks.

Build an AI Ops Dashboard with FSCSS modules (ai-ui, st-core, circle-progress, overlapui)

Wed, 28 Oct 2026 15:40:56 +0000

A step by step tutorial for building a responsive AI dashboard with compiled FSCSS, pure CSS charts, progress rings, stacked avatars, and plain JavaScript. No framework, no build tool beyond the FSCSS CLI.

If you have ever built an AI product UI, you know the pattern. A sidebar, a chat column, a metrics panel, a streaming caret, some usage cards. It is a lot of CSS before you write a single line of product logic.

In this tutorial we build an AI Ops Console using four FSCSS modules, compile everything to one plain CSS file, and wire it up with a small vanilla JavaScript layer. No frameworks. No runtime preprocessor in the browser.

CodePen preview

What we are building

An AI Ops Console with a desktop layout (sidebar, chat, metrics panel) and a mobile layout (hamburger sidebar drawer, bottom sheet metrics panel at 960px and below).

Surface	Module
App shell, sidebar, messages, prompt, stream caret, thinking dots, usage cards, workflow nodes, tool chips, citations	ai-ui.fscss
Token burn area and line chart (clip-path, no SVG or canvas)	st-core@v2
GPU, Queue and Quota rings	circle-progress
Team avatar stack	overlapui
Mock agent replies, live chart nudges, mobile drawers	dashboard.js

The project is split into four files:

ai-dashboard/
├── dashboard.html      # markup only
├── dashboard.fscss     # all FSCSS + layout
├── dashboard.css       # compiled output (generated)
└── dashboard.js        # chat, drawers, chart updates

You compile once and ship plain CSS.

Prerequisites

Node.js 18 or newer (for the FSCSS CLI)
A modern browser
Optional: VS Code with the FSCSS Support extension

Install the compiler globally:

npm install -g fscss@1.2.6

You need FSCSS 1.2.6 or newer. ai-ui requires it, and st-core needs 1.2.3 or newer.

1. Project setup

mkdir ai-dashboard && cd ai-dashboard
touch dashboard.html dashboard.fscss dashboard.js

dashboard.css will be generated by the CLI in step 3.

2. dashboard.fscss: the styles source

This file imports the four modules, calls their helpers against your own class names, defines the chart series, and holds all layout and responsive rules.

/* dashboard.fscss
   AI Ops Dashboard: FSCSS source
   Compile:  fscss dashboard.fscss dashboard.css
*/

/* Modules (registry names; CLI + runtime resolve these) */
@import((*) from ai-ui)
@import((*) from st-core@v2)
@import((*) from circle-progress)
@import((*) from overlapui)

/* Theme + design tokens */
@ai-compose-dashboard()   /* ai-ui tokens + dashboard theme */
@st-root()                /* st-core chart tokens */
@progress-root()          /* circle-progress tokens */
@ou-root()                /* overlapui tokens */

/* ai-ui structure helpers */
@ai-shell(.ai-shell)
@ai-sidebar(.ai-sidebar)
@ai-main(.ai-main)
@ai-messages(.ai-messages)
@ai-message(.ai-message)
@ai-message-user(.ai-message-user)
@ai-message-assistant(.ai-message-assistant)
@ai-bubble(.ai-bubble)
@ai-avatar(.ai-avatar)
@ai-prompt(.ai-prompt)
@ai-prompt-box(.ai-prompt-box)
@ai-prompt-send(.ai-prompt-send)
@ai-stream(.ai-stream)
@ai-thinking(.ai-thinking)
@ai-usage(.ai-usage)
@ai-stat(.ai-stat)
@ai-workflow(.ai-workflow)
@ai-node(.ai-node)
@ai-edge(.ai-edge)
@ai-tools(.ai-tools)
@ai-tool-chip(.ai-tool-chip)
@ai-card(.ai-card)
@ai-divider(.ai-divider)
@ai-citations(.ai-citations)
@ai-citation(.ai-citation)

/* st-core linear chart */
@arr tokenSeries[32, 48, 55, 42, 68, 75, 61, 88, 72, 91, 84, 96]

@st-chart-fill(.chart-fill, tokenSeries)
@st-chart-line(.chart-line, tokenSeries)

.token-chart {
  @st-chart-points(tokenSeries)
  position: relative;
  height: 160px;
  width: 100%;
  background: var(--st-surface, #161422);
  border-radius: 12px;
  overflow: hidden;
}

/* circle-progress */
@circle-progress(.cp)
.cp-72 { @progress-range(72) }
.cp-48 { @progress-range(48) }
.cp-91 { @progress-range(91) }

.cp {
  --progress-size: 110px;
  --progress-stroke: 10px;
  --progress-color-bg: transparent;
  --progress-color-track: rgba(255, 255, 255, 0.08);
  --progress-color-arc: var(--ai-accent, #e879f9);
  --progress-color-glow: color-mix(in srgb, var(--ai-accent, #e879f9) 40%, transparent);
  --progress-color-value: var(--ai-text, #f5f3ff);
  --progress-color-label: var(--ai-text-muted, #a78bfa);
  font-size: 0.95rem;
  font-weight: 600;
}

/* overlapui avatars */
@avatar-overlap(.team-faces)
.team-faces {
  --ou-avatar-size: 36px;
  --ou-overlap: -12px;
  margin-block: 8px;
}

/* Base layout */
* { box-sizing: border-box; margin: 0; padding: 0; }

html, body {
  height: 100%;
  font-family: var(--ai-font, system-ui, -apple-system, sans-serif);
  background: var(--ai-bg, #0c0a12);
  color: var(--ai-text, #f5f3ff);
  -webkit-text-size-adjust: 100%;
}

.ai-shell {
  min-height: 100vh;
  min-height: 100dvh;
  height: 100vh;
  height: 100dvh;
  display: grid;
  grid-template-columns: var(--ai-sidebar-w, 240px) 1fr;
}

.ai-sidebar {
  display: flex;
  flex-direction: column;
  gap: 16px;
  padding: 20px 16px;
  overflow-y: auto;
  border-right: 1px solid var(--ai-border, rgba(255, 255, 255, 0.08));
  background: var(--ai-bg, #0c0a12);
  z-index: 40;
}

.brand {
  display: flex;
  align-items: center;
  gap: 10px;
  font-weight: 700;
  font-size: 1.05rem;
  letter-spacing: -0.02em;
}
.brand-mark {
  width: 28px;
  height: 28px;
  border-radius: 8px;
  background: linear-gradient(135deg, var(--ai-accent, #e879f9), #818cf8);
  display: grid;
  place-items: center;
  font-size: 0.75rem;
  font-weight: 800;
  color: #0c0a12;
  flex-shrink: 0;
}

.nav {
  display: flex;
  flex-direction: column;
  gap: 4px;
}
.nav a {
  display: flex;
  align-items: center;
  gap: 10px;
  padding: 8px 12px;
  border-radius: 8px;
  color: var(--ai-text-muted, #a78bfa);
  text-decoration: none;
  font-size: 0.875rem;
  transition: background 0.15s, color 0.15s;
}
.nav a:hover,
.nav a.active {
  background: color-mix(in srgb, var(--ai-accent, #e879f9) 12%, transparent);
  color: var(--ai-text, #f5f3ff);
}

.side-section {
  display: flex;
  flex-direction: column;
  gap: 8px;
}
.side-section h3 {
  font-size: 0.7rem;
  text-transform: uppercase;
  letter-spacing: 0.06em;
  color: var(--ai-text-muted, #a78bfa);
  font-weight: 600;
}

.cp-row {
  display: flex;
  justify-content: space-between;
  gap: 8px;
  flex-wrap: wrap;
}
.cp-item {
  display: flex;
  flex-direction: column;
  align-items: center;
  gap: 4px;
  font-size: 0.7rem;
  color: var(--ai-text-muted, #a78bfa);
}

.ai-main {
  display: flex;
  flex-direction: column;
  min-height: 0;
  min-width: 0;
  overflow: hidden;
}

.topbar {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 12px 16px;
  border-bottom: 1px solid var(--ai-border, rgba(255, 255, 255, 0.08));
  gap: 10px;
  flex-wrap: wrap;
  flex-shrink: 0;
}
.topbar h1 {
  font-size: 1rem;
  font-weight: 600;
}
.topbar-actions {
  display: flex;
  gap: 8px;
  align-items: center;
  flex-wrap: wrap;
}
.chip {
  font-size: 0.75rem;
  padding: 4px 10px;
  border-radius: 999px;
  background: color-mix(in srgb, var(--ai-accent, #e879f9) 15%, transparent);
  color: var(--ai-accent, #e879f9);
  border: 1px solid color-mix(in srgb, var(--ai-accent, #e879f9) 30%, transparent);
  white-space: nowrap;
}

.workspace {
  flex: 1;
  display: grid;
  grid-template-columns: 1fr minmax(260px, 320px);
  min-height: 0;
  overflow: hidden;
}

.chat-col {
  display: flex;
  flex-direction: column;
  min-height: 0;
  min-width: 0;
  border-right: 1px solid var(--ai-border, rgba(255, 255, 255, 0.06));
}

.ai-messages {
  flex: 1;
  overflow-y: auto;
  padding: 16px;
  display: flex;
  flex-direction: column;
  gap: 14px;
  -webkit-overflow-scrolling: touch;
}

.ai-prompt {
  padding: 12px 16px calc(16px + env(safe-area-inset-bottom, 0px));
  border-top: 1px solid var(--ai-border, rgba(255, 255, 255, 0.06));
  flex-shrink: 0;
}

.right-panel {
  display: flex;
  flex-direction: column;
  gap: 16px;
  padding: 16px;
  overflow-y: auto;
  background: color-mix(in srgb, var(--ai-surface, #12101a) 80%, transparent);
  -webkit-overflow-scrolling: touch;
}

.panel-card {
  background: var(--ai-card, #1a1625);
  border: 1px solid var(--ai-border, rgba(255, 255, 255, 0.08));
  border-radius: 12px;
  padding: 14px;
}
.panel-card h3 {
  font-size: 0.8rem;
  font-weight: 600;
  margin-bottom: 10px;
  color: var(--ai-text-muted, #a78bfa);
}

.ai-workflow {
  display: flex;
  align-items: center;
  gap: 6px;
  flex-wrap: wrap;
  font-size: 0.75rem;
}
.ai-node {
  padding: 6px 10px;
  border-radius: 6px;
  background: var(--ai-surface, #161422);
  border: 1px solid var(--ai-border, rgba(255, 255, 255, 0.1));
}
.ai-node.is-active {
  border-color: var(--ai-accent, #e879f9);
  color: var(--ai-accent, #e879f9);
  box-shadow: 0 0 0 1px color-mix(in srgb, var(--ai-accent, #e879f9) 40%, transparent);
}
.ai-edge {
  width: 16px;
  height: 2px;
  background: var(--ai-border, rgba(255, 255, 255, 0.2));
}

.ai-usage {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 10px;
}
.ai-stat {
  background: var(--ai-surface, #161422);
  border-radius: 10px;
  padding: 10px 12px;
}
.ai-stat-label {
  display: block;
  font-size: 0.65rem;
  text-transform: uppercase;
  letter-spacing: 0.04em;
  color: var(--ai-text-muted, #a78bfa);
  margin-bottom: 4px;
}
.ai-stat-value {
  font-size: 1.15rem;
  font-weight: 700;
  letter-spacing: -0.02em;
}
.ai-stat-delta {
  font-size: 0.7rem;
  margin-left: 6px;
}
.ai-stat-delta.up { color: #4fffb0; }
.ai-stat-delta.down { color: #ff5e7d; }

.ai-tools {
  display: flex;
  flex-wrap: wrap;
  gap: 6px;
}
.ai-tool-chip {
  font-size: 0.7rem;
  padding: 4px 8px;
  border-radius: 6px;
  background: var(--ai-surface, #161422);
  border: 1px solid var(--ai-border, rgba(255, 255, 255, 0.1));
}
.ai-tool-chip.is-done { border-color: #4fffb0; color: #4fffb0; }
.ai-tool-chip.is-running { border-color: var(--ai-accent, #e879f9); color: var(--ai-accent, #e879f9); }

.muted {
  color: var(--ai-text-muted, #a78bfa);
  font-size: 0.8rem;
}

/* Mobile controls (hidden on desktop) */
.menu-btn,
.panel-btn,
.sidebar-backdrop {
  display: none;
}

/* TABLET <= 960px */
@media (max-width: 960px) {
  .ai-shell {
    grid-template-columns: 1fr;
  }

  .ai-sidebar {
    position: fixed;
    inset: 0 auto 0 0;
    width: min(280px, 86vw);
    transform: translateX(-105%);
    transition: transform 0.25s ease;
    box-shadow: none;
    border-right: 1px solid var(--ai-border, rgba(255, 255, 255, 0.08));
  }
  body.sidebar-open .ai-sidebar {
    transform: translateX(0);
    box-shadow: 8px 0 32px rgba(0, 0, 0, 0.45);
  }

  .sidebar-backdrop {
    display: block;
    position: fixed;
    inset: 0;
    background: rgba(0, 0, 0, 0.5);
    z-index: 35;
    opacity: 0;
    pointer-events: none;
    transition: opacity 0.25s ease;
  }
  body.sidebar-open .sidebar-backdrop {
    opacity: 1;
    pointer-events: auto;
  }

  .menu-btn,
  .panel-btn {
    display: inline-flex;
    align-items: center;
    justify-content: center;
    width: 36px;
    height: 36px;
    border-radius: 8px;
    border: 1px solid var(--ai-border, rgba(255, 255, 255, 0.12));
    background: var(--ai-surface, #161422);
    color: var(--ai-text, #f5f3ff);
    cursor: pointer;
    font-size: 1.1rem;
    flex-shrink: 0;
    line-height: 1;
  }

  .topbar {
    padding: 10px 12px;
    gap: 8px;
  }
  .topbar h1 {
    font-size: 0.95rem;
    flex: 1;
    min-width: 0;
    overflow: hidden;
    text-overflow: ellipsis;
    white-space: nowrap;
  }
  .topbar-actions { gap: 6px; }
  .chip {
    font-size: 0.7rem;
    padding: 3px 8px;
  }
  #model-chip { display: none; }

  .workspace {
    grid-template-columns: 1fr;
    grid-template-rows: 1fr;
    position: relative;
  }
  .chat-col {
    border-right: none;
    min-height: 0;
  }

  .right-panel {
    position: fixed;
    inset: auto 0 0 0;
    max-height: min(72vh, 560px);
    border-radius: 16px 16px 0 0;
    border-top: 1px solid var(--ai-border, rgba(255, 255, 255, 0.1));
    transform: translateY(110%);
    transition: transform 0.28s ease;
    z-index: 30;
    box-shadow: 0 -8px 32px rgba(0, 0, 0, 0.4);
    padding-bottom: calc(16px + env(safe-area-inset-bottom, 0px));
  }
  body.panel-open .right-panel {
    transform: translateY(0);
  }
  .right-panel::before {
    content: "";
    display: block;
    width: 36px;
    height: 4px;
    border-radius: 999px;
    background: rgba(255, 255, 255, 0.2);
    margin: 0 auto 10px;
  }

  .token-chart { height: 140px; }
  .cp {
    --progress-size: 88px;
    --progress-stroke: 8px;
    font-size: 0.85rem;
  }
}

/* PHONE <= 600px */
@media (max-width: 600px) {
  .ai-messages {
    padding: 12px;
    gap: 12px;
  }
  .ai-prompt {
    padding: 10px 12px calc(12px + env(safe-area-inset-bottom, 0px));
  }
  .ai-usage {
    grid-template-columns: 1fr 1fr;
    gap: 8px;
  }
  .ai-stat { padding: 8px 10px; }
  .ai-stat-value { font-size: 1rem; }

  .cp-row {
    justify-content: center;
    gap: 12px;
  }
  .cp {
    --progress-size: 76px;
    --progress-stroke: 7px;
    font-size: 0.8rem;
  }

  .panel-card { padding: 12px; }
  .ai-workflow { gap: 4px; }
  .ai-node {
    padding: 5px 8px;
    font-size: 0.7rem;
  }
  .ai-edge { width: 10px; }

  .team-faces {
    --ou-avatar-size: 32px;
    --ou-overlap: -10px;
  }
  .ai-bubble { font-size: 0.9rem; }
}

/* VERY NARROW <= 380px */
@media (max-width: 380px) {
  .ai-usage { grid-template-columns: 1fr; }
  .chip#btn-refresh {
    padding: 3px 6px;
    font-size: 0.65rem;
  }
}

Why this structure works

Import only registers @define helpers. Nothing paints until you call them.
Compose and root helpers write design tokens on :root (or a scope).
Selector-parameterized helpers such as @ai-shell(.ai-shell) and @st-chart-fill(.chart-fill, tokenSeries) attach rules to your own class names.
Plain CSS after that is normal layout, overrides and media queries.

Can also use remote URLs:

@import((*) from "https://cdn.jsdelivr.net/gh/fscss-ttr/ai-ui.fscss@main/ai-ui.fscss")
@import((*) from "https://cdn.jsdelivr.net/gh/fscss-ttr/st-core.fscss@main/st-core%40v2.fscss")
@import((*) from "https://cdn.jsdelivr.net/gh/fscss-ttr/FSCSS@main/xf/styles/circle-progress.fscss")
@import((*) from "https://cdn.jsdelivr.net/gh/fscss-ttr/FSCSS@main/xf/styles/overlapui.fscss")

3. Compile FSCSS to CSS

# one-shot
fscss dashboard.fscss dashboard.css

# watch (recompile on save), if your fscss build supports it
# fscss dashboard.fscss dashboard.css --watch

The compiler:

Expands every @import, @define and @arr into standard CSS
Emits custom properties (--st-p1 to --st-p12, --ai-*, --progress-* and so on)
Emits clip-path: polygon(...) for the chart fill and line
Leaves your media queries and plain CSS intact

Ship only dashboard.css to production. No runtime.min.js is needed on this path.

4. dashboard.html: the markup

Link the compiled stylesheet. There is no FSCSS runtime script.

See complete tutorial here: https://dev.to/fscss/build-an-ai-ops-dashboard-with-fscss-ai-ui-st-core-circle-progress-overlapui-59m5

Demystifying the Facade Pattern in Node.js: Clean APIs Made Simple

Wed, 28 Oct 2026 10:10:50 +0000

What Is the Facade Pattern?

The facade pattern is a structural software design pattern that provides an uncomplicated, unified interface in front of a complex collection of classes, libraries, or APIs. Instead of forcing your application code to interact with dozens of intricate internal functions, the facade exposes a single, high-level method that coordinates the messy work behind the scenes. In short, it gives a sprawling, complicated subsystem a clean and welcoming front door.

The Real-World Analogy: The Home Theater Remote

Imagine you want to watch a movie on a high-end home entertainment setup. To make that happen naturally, you need to execute half a dozen distinct tasks:

Turn on the television.
Set the video input to HDMI 2.
Turn on the surround sound receiver.
Adjust the audio amplifier to optical audio.
Dim the smart living room lights.
Power on the media streaming console.

You could juggle four different remote controls and flip wall switches yourself, learning the exact quirks of each manufacturer. Alternatively, you could pick up a modern universal remote and press a single button: Watch Movie.

That universal remote is a facade. It does not replace the television, receiver, or lights; they still exist with all their specialized knobs and settings. Instead, the remote hides the tedious orchestration behind one single, convenient touchpoint.

Why It Matters in Daily Engineering

In everyday software development, projects tend to grow through accretion. A feature starts out simple, but soon requires five external dependencies: an authentication provider, a payment gateway, a cloud storage bucket, an email delivery service, and an internal logging pipeline.

Without a facade, engineers frequently write "glue code" directly inside their HTTP request handlers (controllers). If five different routes need to charge a customer, each route handler winds up importing and configuring the payment library, checking inventory, calculating sales tax, and firing off analytics calls. This creates two immediate crises:

High Coupling: If the payment provider updates its software development kit (SDK) or changes its function signatures, you must find and update twenty different files across your project.
Cognitive Overload: Engineers reviewing or writing features are forced to read through hundreds of lines of low-level plumbing when they only care about whether an order succeeded.

By placing a facade between your core business logic and external subsystems, engineers prevent third-party updates from leaking across the entire codebase. When an underlying vendor changes, you update one facade file, leaving the rest of the application completely untouched.

Practical Implementation in Node.js

Consider an e-commerce checkout flow in an Express and Node.js application. Completing an order touches an inventory service, a payment processor, and a notification service.

Without a facade, your Express route handler would have to instantiate and coordinate every service manually. Here is how you encapsulate that complexity using a Facade:

// Subsystem 1: Inventory Management
class InventoryService {
  checkStock(productId) {
    // Simulate querying database stock levels
    console.log(`Checking stock for item: ${productId}`);
    return true;
  }
  reserve(productId, quantity) {
    console.log(`Reserved ${quantity} unit(s) of ${productId}`);
  }
}

// Subsystem 2: Payment Processing
class PaymentProcessor {
  charge(amount, paymentToken) {
    console.log(`Charging $${amount} using token: ${paymentToken}`);
    return { status: 'success', transactionId: 'txn_987654' };
  }
}

// Subsystem 3: Customer Notifications
class NotificationService {
  sendReceipt(email, transactionId) {
    console.log(`Receipt sent to ${email} for transaction ${transactionId}`);
  }
}

// The Facade: OrderFacade
class OrderFacade {
  constructor() {
    this.inventory = new InventoryService();
    this.payment = new PaymentProcessor();
    this.notifications = new NotificationService();
  }

  processOrder({ productId, quantity, price, paymentToken, customerEmail }) {
    const isAvailable = this.inventory.checkStock(productId);
    if (!isAvailable) {
      throw new Error('Product is out of stock.');
    }

    this.inventory.reserve(productId, quantity);
    const paymentResult = this.payment.charge(price * quantity, paymentToken);
    this.notifications.sendReceipt(customerEmail, paymentResult.transactionId);

    return { success: true, transactionId: paymentResult.transactionId };
  }
}

// Express Route Usage
const express = require('express');
const app = express();
app.use(express.json());

const orderFacade = new OrderFacade();

app.post('/api/checkout', (req, res) => {
  try {
    const orderConfirmation = orderFacade.processOrder(req.body);
    return res.status(200).json(orderConfirmation);
  } catch (error) {
    return res.status(400).json({ error: error.message });
  }
});

The route handler does not know or care how inventory reservation works or what parameters the payment gateway demands. It invokes processOrder() and receives a clear outcome.

Key Takeaway

A facade is not an abstraction that conceals how a system works to make it private; it is an ergonomic shield that keeps your application's day-to-day feature code clean, readable, and insulated from volatile third-party tools.

Enjoyed this breakdown? Support my open-source work on Buy Me a Coffee or explore react-hook-lab!

Originally published on my blog. You can read the alternative breakdown here.

Launching a fancy text converter: 451 styles, and the Unicode edge cases behind them

Tue, 27 Oct 2026 09:22:36 +0000

I'm Shawn Sun, a front-end engineer, and I just put a fancy text converter online. This is a developer community, so here are the parts that were fun to build instead of a feature list.

You type once and get 451 copy-and-paste styles. Tap one to copy it, and the last 8 you copied come back under Recent. No sign-up. None of these are fonts: every style is real Unicode characters, and that caused most of the work below.

1. A style is mostly a lookup table

Bold, italic, script, Fraktur and the rest live in the Mathematical Alphanumeric Symbols block, so most styles are "offset of A, plus the letter's index".

2. The block has holes

Some letters were encoded earlier elsewhere, so their slot is empty. A naive base + index gives you a box, so each style carries a small exceptions table.

3. Accents: decompose first

There is no bold é. I split it with NFD, style the e and keep the accent after it. Whether the accent then sits on top depends on the font.

4. Don't split emoji

Walk a string by code point and 👩💻 falls apart. I cut input into grapheme clusters with Intl.Segmenter and only style plain letters and digits.

5. Long input: preview first, convert on copy

Rendering every style live is fine for a username and slow for a pasted paragraph. Past 200 UTF-16 code units, each card previews only the start, and the full text is converted when you copy.

Honest limits

Conversion runs in your browser. I count anonymous usage events, such as which style was copied, but your text isn't part of them.

I'd like your feedback

Which category is missing, and do the style names make sense? Try your own text on the live site and tell me in the comments.

— Shawn Sun

Building a Booking System with Node.js, Google Calendar, and Google Meet

Tue, 27 Oct 2026 07:58:12 +0000

Introduction

Booking a consultation should be straightforward for the person making the appointment. Behind the scenes, however, an automated booking system has to coordinate several moving parts: collecting customer information, checking availability, scheduling an event, generating a meeting link, saving the booking, and notifying the people involved.

I encountered these challenges while developing the booking system for JOPAD Advisory. I built the system from scratch, using Node.js and Express for the backend, MongoDB for storing bookings, Google Calendar for scheduling, Google Meet for virtual meetings, and Resend for email notifications.

In this article, I'll walk through how I implemented the booking workflow, how the different services work together, and some of the engineering considerations that come with connecting external APIs to a backend application.

1. The Architecture

The backend coordinates the booking process. Each service has a specific responsibility:

Node.js and Express: Handle booking requests and coordinate the workflow.
MongoDB and Mongoose: Store booking details and provide access to existing appointments.
Google Calendar API: Create calendar events for scheduled sessions.
Google Meet: Generate a virtual meeting link through the Calendar event's conference configuration.
Airtable: Receive a secondary record of the booking.
Resend: Power the email notification workflow.

The booking process follows this sequence:

A customer submits a booking request through the website.
The Express endpoint validates the submitted fields.
The backend calculates the appointment's start and end times.
Existing bookings are checked for overlapping time intervals.
Google Calendar creates an event and requests a Google Meet conference.
The booking is saved to MongoDB with its meeting link.
The backend attempts to send a secondary record to Airtable.
Booking notification emails are triggered.

This design brings several services together behind a single booking endpoint, giving the frontend one place to submit the request.

2. Building the Booking Endpoint

I used an Express POST endpoint to receive booking requests. The request contains the appointment time, duration, customer's contact details, session description, and other booking information.

The first step is to reject incomplete requests before performing external API operations.

A simplified version of the validation looks like this:

router.post("/book", async (req, res) => {
  const {
    time,
    duration,
    email,
    firstName,
    lastName,
    description
  } = req.body;

  if (
    !time ||
    !duration ||
    !email ||
    !firstName ||
    !lastName ||
    !description
  ) {
    return res.status(400).json({
      message: "Missing required fields"
    });
  }

  // Continue with availability checks
  // and booking creation.
});

This is a simplified illustration of the validation logic in my implementation, not a complete replacement for the original endpoint.

The actual endpoint validates additional fields, including the selected date, day, time range, phone number, and referral information.

The important principle is to validate the data required by the booking workflow before creating external resources or writing records.

For a production system, request validation should also verify data types, valid email addresses, positive durations, valid dates, and acceptable appointment times. A field being present does not necessarily mean its value is valid.

3. Calculating Appointment Duration

A booking needs both a start time and an end time. The end time determines the appointment's actual interval and makes it possible to detect overlapping bookings.

In my implementation, the backend calculates the end time using the requested start time and duration:

const startTime = new Date(time);
const endTime = new Date(startTime);

endTime.setMinutes(
  endTime.getMinutes() + Number(duration)
);

For example, an appointment starting at 10:00 AM with a duration of 60 minutes should end at 11:00 AM.

Calculating the interval on the backend is important because scheduling decisions should not depend solely on values calculated by the browser.

It is also important to handle time zones consistently. My Google Calendar integration sends ISO-formatted timestamps to the API. A more comprehensive implementation should explicitly define the application's scheduling time zone and validate incoming timestamps to prevent ambiguity around local times and daylight-saving transitions.

4. Preventing Overlapping Bookings

One of the central problems in a booking system is preventing customers from selecting times that have already been reserved.

Two appointments overlap when the first appointment starts before the second one ends and finishes after the second one starts.

The logic can be expressed as:

const overlaps =
  requestedStart < existingEnd &&
  requestedEnd > existingStart;

This condition also allows back-to-back appointments. For example, a booking ending at 11:00 AM does not conflict with another booking beginning at exactly 11:00 AM.

In my implementation, I retrieve existing bookings from MongoDB, calculate each booking's end time from its start time and duration, and check for conflicts:

const existingBookings = await Booking.find();

const conflict = existingBookings.some(booking => {
  const existingStart = new Date(booking.startTime);
  const existingEnd = new Date(existingStart);

  existingEnd.setMinutes(
    existingEnd.getMinutes() +
      Number(booking.duration)
  );

  return (
    startTime < existingEnd &&
    endTime > existingStart
  );
});

if (conflict) {
  return res.status(409).json({
    message: "This time slot has already been booked"
  });
}`

Returning HTTP "409 Conflict" communicates that the request conflicts with an existing booking.

This approach is easy to understand, but it has a scalability limitation: the implementation loads all existing bookings before checking for an overlap. As the collection grows, a database query restricted to potentially overlapping intervals would be more efficient.

There is also an important concurrency consideration. Two requests can check availability at almost the same time, both find the slot free, and both continue. The check alone does not guarantee that simultaneous requests cannot create overlapping bookings.

A stronger production design would use an atomic reservation strategy, such as reserving discrete time slots with a unique database constraint or using another concurrency-control mechanism. That protection needs to be designed around the application's scheduling rules rather than relying only on an initial availability check.

5. Connecting Google Calendar and Google Meet

After the backend confirms that a requested slot does not conflict with an existing booking, it calls a dedicated utility function to create the meeting.

I separated this logic into a Google Calendar utility instead of placing the entire integration directly inside the Express route. This keeps the route focused on the booking workflow and makes the external integration easier to maintain.

Authenticating with Google

The utility initializes an OAuth 2.0 client using environment variables and sets a refresh token:

const { google } = require("googleapis");

const oauth2Client = new google.auth.OAuth2(
  process.env.GOOGLE_CLIENT_ID,
  process.env.GOOGLE_CLIENT_SECRET,
  process.env.GOOGLE_REDIRECT_URI
);

oauth2Client.setCredentials({
  refresh_token: process.env.GOOGLE_REFRESH_TOKEN
});

The example uses the conventional environment-variable spelling for the client secret. In the project, the environment variable is named "GOOGLE_CLIENT_SECRETE", so the deployed configuration must match the actual code unless that naming is corrected.

The refresh token allows the server-side client to obtain access tokens as needed without requiring the user to repeat the authorization flow for every booking.

This requires the initial OAuth authorization to have been completed successfully and the refresh token to remain valid. The Google account must also have the necessary permissions and configuration for creating Calendar events and conference links.

Credentials should be stored securely in environment variables or an appropriate secrets manager, never committed to a public repository.

Creating a Calendar event

The integration uses Google's Calendar API:

const calendar = google.calendar({
  version: "v3",
  auth: oauth2Client
});

The meeting function calculates the event's end time and constructs a Calendar event containing the session title, description, start and end timestamps, and attendee information.

The attendee is represented by the customer's email address:

attendees: [
  {
    email,
    responseStatus: "accepted"
  }
]

The event also includes settings that prevent guests from modifying the event, inviting other guests, or seeing other guests.

These settings are part of the event configuration; they do not replace proper authorization and access control in the booking application itself.

Requesting a Google Meet link

The event configuration includes a conference creation request:

conferenceData: {
  createRequest: {
    requestId: "jopad-" + Date.now(),
    conferenceSolutionKey: {
      type: "hangoutsMeet"
    }
  }
}

The event is then inserted into the primary Google Calendar:

const response = await calendar.events.insert({
  calendarId: "primary",
  resource: event,
  conferenceDataVersion: 1,
  sendUpdates: "all"
});

The "conferenceDataVersion: 1" option tells Google Calendar that conference data should be processed as part of the request. The "sendUpdates: "all"" option requests that Calendar send event updates to the relevant participants.

After the API call succeeds, the implementation extracts the meeting URL from the returned conference data:

const meetLink =
  response.data.conferenceData.entryPoints[0].uri;

return meetLink;

The booking route receives that link and includes it in the booking record.

One important implementation detail is that the code assumes the response contains a conference entry point. A more defensive implementation would verify that the response contains a usable Meet URL before continuing.

Google Calendar conference creation can also involve asynchronous processing. Production code should account for cases where the event exists but the conference details are not yet available, rather than assuming every successful event insertion immediately includes a meeting link.

6. Saving Bookings in MongoDB

Once the meeting link has been returned, the backend creates a Mongoose booking document.

The model stores information such as:

Appointment start time and duration.
Customer name and contact information.
Session description.
Date and time display values.
Referral information.
Google Meet link.
Record creation timestamp.

The central fields include:

const bookingSchema = new mongoose.Schema({
  startTime: {
    type: Date,
    required: true
  },
  duration: String,
  email: String,
  firstName: String,
  lastName: String,
  description: String,
  meetLink: String,
  createdAt: {
    type: Date,
    default: Date.now
  }
});

This is an excerpt of the schema; the complete project model contains additional fields.

After constructing the document, the route saves it:

await newBooking.save();

Saving the booking after generating the meeting link ensures that the returned booking record can contain the link associated with the created event.

However, the order of these operations creates an important failure scenario. If Google Calendar successfully creates the event but MongoDB subsequently fails to save the booking, a calendar event may remain without a corresponding booking record.

This is a common challenge when coordinating operations across independent services. A more resilient design could track workflow states, retry recoverable operations, and provide a reconciliation or cleanup process for partially completed bookings.

7. Adding an Airtable Backup

The system also attempts to send booking information to Airtable after saving the MongoDB document.

The request includes selected booking fields, such as the customer's name, email, phone number, session description, referral details, meeting link, and appointment date.

The operation is wrapped in its own "try...catch" block. If the Airtable request fails, the error is logged, but the main booking workflow can still continue.

This makes Airtable a secondary destination rather than the primary source of truth for the booking.

That distinction matters: the implementation attempts a backup write, but it does not guarantee that the MongoDB and Airtable records are always synchronized. If Airtable is unavailable, the backup attempt fails without automatically retrying it.

A more robust implementation could place failed backup operations into a retry queue or maintain a record of synchronization status.

8. Sending Booking Notifications

After the booking has been saved and the Airtable attempt has completed, the route triggers the email notification utility:

sendBookingEmails({
  email,
  firstName,
  lastName,
  dayString,
  referral,
  dateString,
  number,
  description,
  timeString,
  timeRange,
  meetLink
}).catch(err => {
  console.log("Email failed:", err.message);
});

The email operation is not awaited by the route. This allows the endpoint to return its successful booking response without waiting for the notification workflow to finish.

It also means an email failure does not change the response after the booking has been saved.

There is a trade-off: the current implementation logs email failures but does not automatically retry them or record a delivery status in the booking document. For a production booking service, a persistent background job or message queue would provide a stronger way to retry notifications and monitor delivery outcomes.

The route eventually responds with HTTP "201 Created", along with a success message and the saved booking.

9. Lessons from the Implementation

Building this workflow brought several backend engineering considerations into focus.

Validate before creating external resources. Checking the request and current bookings before calling Google reduces unnecessary API operations.

Separate responsibilities. Keeping the Calendar integration in its own utility makes the Express route easier to understand and maintain.

Handle partial failures. MongoDB, Google Calendar, Airtable, and an email provider are independent services. A successful operation in one does not guarantee success in the others.

Treat concurrency as a separate problem. Checking for overlapping bookings is necessary, but it does not by itself protect against two simultaneous requests reserving the same slot.

Design for observability and recovery. Logging an error helps with debugging, but production systems also benefit from structured logs, retry mechanisms, delivery tracking, and reconciliation workflows.

These considerations extend beyond booking applications. Any backend that coordinates a database with multiple external APIs needs a plan for partial failures and retries.

Conclusion

Building the JOPAD Advisory booking system from scratch gave me practical experience connecting a Node.js backend to Google Calendar, generating Google Meet links, storing bookings in MongoDB, maintaining a secondary Airtable record, and triggering email notifications.

The most important lesson is that integrating APIs is only one part of building a reliable application. The surrounding workflow—validation, conflict detection, persistence, failure handling, and recovery—is just as important.

A booking endpoint can appear simple from the frontend, but it coordinates several systems that can succeed or fail independently. Understanding those interactions is what turns an API integration into a more complete engineering solution.

I'm continuing to explore ways to make these workflows more resilient, especially around concurrent bookings, retries, and recovery from partial failures.

If you're building a booking platform or integrating third-party services into a Node.js application, I'd be interested to hear how you approach these challenges.

Designing browser music controls around the next beat

Tue, 27 Oct 2026 02:36:40 +0000

By Paul Gendek. Originally published on DEV. The original DEV article is labelled “Fully Autonomous”; its AI disclosure is retained below.

When I am playing guitar alone, changing a backing groove usually means moving a hand from the instrument to the laptop. A button can be easy to click and still interrupt the activity it is supposed to support. That problem led me to Mock Band, a browser rhythm section, and to a useful distinction: accepting a command, applying a musical change and making that change understandable to the player are separate jobs.

I supplied the concept, product direction and requirements, tested physical hardware and retained merge approval. AI tools implemented changes and ran automated checks. This article is an AI-drafted adaptation of my original project account and the current case study. The implementation details below describe the system those tools helped implement.

Start with what the player is doing

The initial idea, recorded in a note in September 2023, was to choose drums, bass and guitar accompaniment, repeat a groove and then reshape it through instructions. A player could change key or move to half-time while keeping both hands on the guitar. A footswitch would activate voice listening.

The player remained responsible for the riff and musical direction. The product did not need to listen to the guitar and infer its performance to serve that goal. It needed to accept an intentional change with less interruption.

That distinction reduced the interaction problem to something concrete. How does a person indicate a change? Which parts of that change can happen now? Which should wait for a musical boundary? What should remain usable when voice or a controller is unavailable?

I chose the browser after researching WebMIDI and browser music APIs. Voice recognition, MIDI support and permissions still vary across browser and device combinations. Visible controls and text therefore remain useful ways to operate the band.

Connect input methods to shared musical actions

The interface and application state use React and TypeScript. Text and recognized speech share a command vocabulary. A typed tempo instruction and its recognized spoken equivalent can reach the same musical action without maintaining two separate definitions of what the instruction means.

MIDI controller input has a different shape. A mapped controller action can invoke a scene or transport handler directly. It does not need to become a sentence and pass through a text parser first.

The useful point of convergence is shared application state and provider handlers. Those handlers connect transport, musical changes and scene events to the rest of the system. Sharing that destination gives the input methods a common effect while preserving the differences in how the request arrived.

This matters when extending a product. Adding an input method should not require inventing another version of scene recall or tempo changes. It also should not require squeezing every physical gesture into a text-command metaphor.

Give audio timing its own responsibility

The current audio bridge passes changes to an AudioWorklet. The worklet renders drums, bass and rhythm accompaniment and handles their timing away from interface rendering. Its live schedule can also feed WebMIDI output through the bridge.

MDN's AudioWorklet reference explains the separate Web Audio execution context. That separation helps explain this architecture, but the use of a worklet alone does not establish that a particular application has no timing problems.

The interface has to respond to a request. The audio engine has to decide when an allowed change takes effect. In this system, a playing change can queue for a beat or bar boundary; a stopped change can apply immediately.

Consider a tempo adjustment requested halfway through a bar. The player has made a valid request, but applying it at an arbitrary instant may disrupt the phrase. Queuing it gives the music a meaningful point at which to change. This is a design choice about musical behavior, with implementation consequences for state.

Distinguish selected pending and applied state

A delayed musical change creates more than one truthful description of the current situation.

State	What it means	What the player needs to understand
Selected	The player has requested a new value.	The intended next setting.
Pending	The change is waiting for a musical boundary.	Why the current sound may still reflect the previous value.
Applied	The audio engine has adopted the change.	Which setting is active in the music.

These are design distinctions, not three competing copies of the truth. A selected value can be correct as an intention while the old value remains correct as the applied sound.

For a hypothetical example, imagine changing from one tempo to another during playback with a bar-boundary change pending. If the interface presents the new value as already active, a player may think the engine ignored it. If it hides the request until the boundary, the player may repeat it. The product needs to communicate the relationship between intention and execution.

The lesson extends beyond music. Whenever an operation is accepted now but takes effect later, the interface needs to describe both events honestly. In music, the delay has an audible consequence, so the distinction becomes difficult to ignore.

Let the physical switch correct the requirement

During early development, I tested a purchased Bluetooth footswitch and found that its behavior was a toggle. The interaction had assumed a hold-to-talk gesture.

That was not a problem I could resolve by looking only at a button handler. The intended gesture and the actual device disagreed. I fed the finding back into Cursor and refined the interaction around a tap that starts listening while recognition is awaited. Getting it usable required debugging and repeated manual testing.

Scene recall with the footswitch was a satisfying early result for me. That is a historical acceptance observation, not certification of the current version or every controller.

The important requirement came from trying the hardware in the activity. With both hands on a guitar, a switch has to support a gesture the player can actually perform and recognize. A software abstraction can describe a press cleanly while missing how the physical control behaves.

Keep local scenes and validation understandable

The current product provides ten local scenes, with JSON export and import for backup or moving configurations between browsers. Keeping musical state in the browser avoids an account and cloud setup step. It also makes the storage boundary part of the experience: a scene saved in one browser is not automatically present in another.

Local state should not be confused with offline support for every feature. Browser speech recognition has its own capabilities and dependencies. A local scene system does not make a browser's recognition service work offline.

Validation has similar boundaries. Agents handled automated checks. I supplied manual acceptance testing and merge decisions. Those activities can support different claims, and none should stand in for all the others.

I reported a successful live MIDI output test through an IAC bus into Logic Pro on September 29, 2026. That is useful evidence for that route. It does not establish behavior with every physical receiver or controller. An interface screenshot can establish a visible control or layout, but cannot establish that the music sounds right.

The next useful checks are therefore about the actual interaction: can a player request a change without losing the phrase, understand when it takes effect and recover when an optional input method is unavailable? The current version has not yet been part of my regular practice beyond QA. Those practice questions remain work to do.

Conclusion

Building a browser music tool made the input and timing boundary unusually tangible for me.
Shared handlers let different input methods reach the same musical actions.
The interface needs to distinguish selected, pending and applied state.
A playing change can wait for a beat or bar boundary while the interface acknowledges the request.
Visible controls and text remain useful when an optional input method is unavailable.
The system must accept the player's intention, preserve a musically sensible transition and communicate the difference.
Real hardware then tests whether that intention was represented correctly in the first place.

I built a game that teaches Vim motions: what I got wrong about teaching a modal editor

Mon, 26 Oct 2026 13:26:00 +0000

Most developers I know have the same relationship with Vim: they learned just enough to exit it, and never went further.
I wanted to fix that, so I built Vimrealm: a browser RPG where you type real Vim commands to move a wizard around an isometric island made of text. Letters are stone, digits are crystal, punctuation is sandstone, spaces are grass. Press w and the wizard leaps to the next word. Press dd and a whole row of tiles drops away.
Here's what I learned building it, including the parts I got wrong.

Why vimtutor loses people

vimtutor is good at one thing: showing you that the commands exist. It's weak at three others:

Modes are invisible until they bite you. You press i, forget you're in Insert mode, type dd and get "dd" in your file.
There's no feedback on efficiency. Reaching a word with lllllllll and with w looks identical to the tutorial. Vim's whole point is that these are not the same.
You can use everything from lesson one. Nothing stops you from falling back on the arrow keys, so you do.
A game can fix all three, because a game has rules.
The design

Quests with a par. Every quest has a par keystroke count, taken from a reference solution I wrote. Finish at or under par and you earn three stars. This turns "I got there" into "I got there well", and it's the part that makes people retry levels to find the shorter route. Commands like :hint, :help and :e! cost nothing, so asking for help is never punished.
Spells unlock chapter by chapter. Commands are "spells", and you only have the ones you've learned. Try something you haven't met yet and the game tells you which chapter teaches it. The arrow keys are sealed for good. Chapter 1 is h j k l; chapter 2 adds word motions; later chapters add operators, text objects, the dot command, search and visual mode. The curriculum ends with a boss fight against the Arrow-Key Dragon.
Hints name the command. Every target in a "reach" quest has a hint pointing at the spell to use. Quests come in two kinds: reach (land the cursor on each gem, in order) and edit (make the buffer match a goal text, with mismatched lines glowing red).
Trials after the story. Once the dragon falls, 60 Trials drill known spells with a twist: banned commands, a keystroke limit, a flawless run where one failed spell ends it, or a time limit that starts at your first key.

The technical part: a Vim emulator in plain JS

The game is plain HTML, CSS and JavaScript. No bundler, no framework, no client-side dependencies, and the free chapters even work from file://. The core is an emulator that handles Normal, Insert, Replace, Visual, Visual Line and Command-line modes, with counts, operators plus motions, text objects, registers, undo/redo, dot-repeat and search.
Each keystroke flows through one pipeline:
keydown → normalize key → quest.feed(key) → vim.feed(key) → event
vim.feed returns an event describing what happened (move, edit, mode, undo, yank and so on) and the game reacts: sounds, hero animation, tile changes, win overlay. Keeping the engine and quest rules free of any DOM code was the best decision I made, because the same files run in Node.
Testing it. The emulator has to behave like real Vim, or you teach people the wrong thing. Every behaviour I add gets a test case like this:
```
t(name, lines, keys, expect, start)
```
Keys are written in a small notation (<Esc>, <CR>, <C-r>), so a test reads like something you'd actually type.
A second test suite replays every level's reference solution through the real quest rules and fails if any key is rejected or the quest can't be won. That's also how par stays honest: change a level's buffer and the build tells you the solution no longer works.
Where I stopped. The emulator covers what the course teaches, not all of Vim. There are no macros, marks, named registers, ex ranges or :s, and search matches literal text rather than regex. I drew the line at the point where emulating more would teach less. A beginner doesn't need qa in week one, and every feature I add is one more place for the emulator to disagree with real Vim.
One small deviation I kept deliberately: in Normal mode, Backspace takes back the last pending key. Real Vim does something different there, but for a beginner who typed d by mistake, an undo for the pending key is friendlier than a cursor move.

What I don't know yet

Vimrealm is new and I haven't had real players go through it yet, so I can't tell you which levels are confusing or where people quit. I have guesses: I suspect the jump from reach quests to edit quests in chapter 6 is the steepest point, and that par is either too strict or too forgiving.
That's exactly what I'd like to find out.

Try it

The first five chapters (13 quests, all movement) are free, with no sign-up:
👉 vimrealm.com
The rest (operators, text objects, the dot command, search, visual mode and the dragon) is a one-time $7.99. I'd rather say that up front than hide it.
If you'd rather read than play, I wrote two guides built around worked examples:
Vim text objects
The Vim dot command
I'd love to hear which chapter you got stuck on, and which Vim habit you'd want a game to teach.

The architecture of a website that can't see your files (74 tools, no backend)

Mon, 26 Oct 2026 02:55:10 +0000

Most "free online PDF tool" sites have the same architecture: your file goes up to their server, gets processed, and comes back. The privacy policy says they delete it after an hour. You have to take their word for it.

I learned this as the family's unofficial IT person. Every few weeks, someone sends me an Aadhaar scan or a bank statement and asks me to "make it smaller" or "unlock it". I kept uploading other people's documents to sites I knew nothing about, and at some point that stopped feeling okay.

After my first two posts on Fizzdoc, a close friend asked me some version of "but how do I know it really doesn't upload?" This post is the long answer.

So for Fizzdoc I wanted a site that can't see your file, by design. The browser itself won't let the page send it anywhere.

Fizzdoc now has 74 tools (PDF, Word, Excel, PowerPoint, images, audio), 16 languages and about 1,200 pages, and it has no backend at all. This post is about the design decisions that make that work, and the trade-offs I accepted.

Constraint 1: the page is not allowed to talk to anyone

Every page ships this Content Security Policy (in a <meta> tag, which the browser enforces just like a header):

default-src 'self'; script-src 'self' 'wasm-unsafe-eval'; connect-src 'self'; ...

connect-src 'self' is the important part. fetch, XMLHttpRequest, WebSockets, sendBeacon: the browser blocks all of them unless they go to fizzdoc.com itself, and fizzdoc.com is just static files. So even if one of the many open-source libraries had a bug or a malicious update, it couldn't send a document anywhere.

That one line shaped everything else:

No CDNs. Fonts, WebAssembly engines and AI models are all served from the same origin.
No analytics scripts. Even when Cloudflare injected its own analytics beacon, the CSP blocked it, because a script that isn't from the site can't run. (I switched that beacon off too; traffic numbers come from Cloudflare's server-side stats instead.)
It is testable. The Playwright suite (about 1,250 browser tests) runs real jobs and fails if any request leaves the origin.

Constraint 2: no server, so the build does the work

There is no server to render pages, so a build step renders all of them ahead of time. One TypeScript file lists every tool (name, copy, FAQ, search keywords), and the build turns it into a static HTML page per tool per language: about 1,200 pages, each with its own title, structured data (FAQ, HowTo, breadcrumbs), hreflang links and sitemap entry.

The first load is small because each page only ships what it needs:

On first load	Gzipped
JavaScript	about 19 KB
CSS	about 9 KB

Everything heavy loads only when you use the tool that needs it, through dynamic import().

Each job gets its own throwaway worker

The PDF tools are qpdf compiled to WebAssembly. Every job gets a fresh Web Worker, which is terminated when the job ends. That keeps the page responsive, and the file and any password disappear with the worker.

Other engines follow the same pattern: pdf.js and pdf-lib for rendering and editing, Tesseract (WASM) for OCR, Whisper (through Transformers.js) for speech to text, and BiRefNet on ONNX Runtime Web (WebGPU when available, WASM otherwise) for background removal.

Big models on a host with a 25 MiB file limit

Cloudflare Pages refuses any file over 25 MiB. The background model is about 100 MB and the WebGPU build of ONNX Runtime is 27 MB.

So the build splits them into 20 MiB parts. On first use the worker downloads the parts, joins them, and keeps the result in Cache Storage. After that the tool starts instantly, and it works with the internet off. The build also fails if any output file goes over the limit, after one deploy failed on it.

Offline without breaking updates

A service worker makes every tool work offline after one visit. The rules are deliberately boring:

Pages: network first, cache as a fallback. Online visitors always get the latest page.
Hashed assets (/assets/index-abc123.js): cache first. A hashed file never changes, so the cached copy is always right.
Old files are never deleted. A page cached by an older version still needs its older assets.
Models are excluded. Their tools manage their own caches.

A page that was never opened shows a small "needs the internet once" page in your language instead of the browser's error screen.

Hard parts that come from having no server

Phones run out of memory, silently. The first version of the background remover crashed Chrome on a 6 GB Android phone ("Aw, Snap!" at 5%). A tab gets far less memory than the phone has, and there's no error to catch. Phones now use a 4.6 MB model instead of the 100 MB one.

iPhone canvases have a size limit (about 16.7 million pixels). The Photo Editor tries full size first and falls back to the largest canvas the device allows.

Fonts couldn't be data: URLs. Vite inlines small files as data: URLs, my own CSP refused them, and the CSP-violation test caught it before it shipped.

"Share to WhatsApp" can't make a sticker. A web page can't add stickers to WhatsApp. A shared file arrives as a photo, so the page shows WhatsApp's own "Create sticker" steps instead of a button that lies.

The editor is just pixel maths

The newest tools, the Photo Editor and the Collage Maker, use no image library. Brightness, contrast, saturation and warmth are a short loop over the pixels. Every edit redraws from the original photo, so edits never pile up blur. Doing it in plain code instead of ctx.filter means every browser gives the same result, and unit tests can check it.

What it costs, and what 30 days of traffic look like

Fizzdoc runs on Cloudflare's free plan. Hosting costs me nothing, because every page and every AI model is just a static file. These are Cloudflare's own server-side numbers for the last 30 days (there is no analytics script on the site, so this is all I can see):

Last 30 days
Requests	201k
Visits	41.9k
Page views	62.8k
Data served	10.15 GB
Server errors (5xx)	0%

A few things I didn't expect:

A big share is bots. Search crawlers (Googlebot, Applebot, Petalbot, Semrush) and AI crawlers show up all over the user-agent list. I welcome them in robots.txt, but it means "42k visits" is not 42k people. Treat these as upper bounds.
Most of the bandwidth is AI models, not pages. The pages are tiny; the 10 GB is almost all background-removal and Whisper model files that visitors download once and then keep in their browser cache.

Bots keep looking for a backend that doesn't exist. Hundreds of requests for /.env, /wp-config.php, /api/ and /login. There is nothing to find, since there's no server, database or secrets behind the site.
Visitors come from everywhere. The United States, India, Singapore, South Korea, Australia and Germany lead, and the page is in 16 languages.

Trade-offs I accepted

Your device does the work. A 300-page scan OCRs slower on an old phone than on a server.
Some formats aren't possible yet. PowerPoint to PDF and old .doc/.xls files aren't supported.
One-time downloads. The AI tools download their model once (the page shows the size first).

Try it, break it

Site: https://fizzdoc.com
Code (Apache-2.0): https://github.com/kingrishabdugar/fizzdoc
Check it yourself: open DevTools → Network, run any tool, and watch nothing leave.

If you build something similar, the one decision I'd copy is the CSP. It turns "we don't upload your file" from a promise into a property of the page. And if Fizzdoc saved you an upload, a star on GitHub helps more people find it.

Headless Vue + WordPress Boilerplate v2.0.0

Mon, 26 Oct 2026 01:04:13 +0000

Headless Vue + WordPress Boilerplate v2.0.0

Yes, Version 2.0.0 is here!!!

This boilerplate allows you to use Vue as the front-end for your WordPress theme in a headless architecture. WordPress handles the backend and REST API, while Vue powers the user interface using modern frontend tooling like Vite.

Key Features

Use Vue 3 with Vite for a fast and modern development experience
⚡ Hot Module Replacement inside WordPress: save a .vue file and see it instantly, no rebuild
One-line REST API routes in PHP and one-line calls in Vue (useApi, useWp)
WordPress pages, posts and menus work out of the box with Vue Router
Modular folder structure for components, pages, APIs, and stores
⚙️ Supports Vue Router and Pinia (Vue Store)
Style with Tailwind CSS, standard CSS or your preferred CSS preprocessor

Requirements

WordPress 6.7+ and PHP 8.1+
Node.js 20+
Pretty permalinks (Settings > Permalinks, anything except "Plain")

Folder Structure

themes/
└── vue-boilerplate/
    ├── functions/               # WordPress PHP functions
    │   ├── api.php              # Your REST API routes
    │   ├── api-helpers.php      # vue_theme_api_get(), vue_theme_api_post(), ...
    │   ├── vite.php             # Loads the Vue app (dev server or build)
    │   └── theme-settings.php   # Theme supports and menu locations
    ├── src/                     # Vue application root
    │   ├── api/                 # API client (index.js) and JS modules for API calls
    │   │   └── wp/
    │   ├── assets/              # Static assets like images and SVGs
    │   ├── components/          # Vue components (e.g., layout)
    │   ├── composables/         # useApi and useWp
    │   ├── page/                # Vue page views
    │   ├── router/              # Vue Router setup
    │   ├── stores/              # Pinia stores
    │   │   └── wp/
    │   ├── utils/               # HTML sanitizer and link helpers
    │   ├── App.vue              # Root Vue component
    │   ├── main.js              # Vue app entry point
    │   ├── settings.js          # Values passed from WordPress
    │   └── style.css            # Global styles
    ├── dist/                    # Production build (created by npm run build)
    ├── *.php                    # WordPress theme files (header.php, footer.php, etc.)
    ├── style.css                # Theme metadata
    └── vite.config.js           # Configuration file for Vite, a fast frontend build tool.

Getting Started

Download and put the files inside your themes folder, then activate the theme.
Download Latest Release
Install Dependencies
```
npm install
```
Run the Development Server
```
npm run dev
```
Open your WordPress site URL (e.g. http://mysite.local), not the Vite URL.

While npm run dev is running, WordPress loads the app from the Vite dev server. Vue and CSS changes show up instantly, and PHP changes reload the page. Stop the dev server and WordPress goes back to the production build.

Make sure WordPress is running locally (e.g., with LocalWP or Laragon) and that the theme is activated.

Build for Production

npm run build

This will compile and optimize your Vue app into dist/. Upload the theme with the dist folder, you don't need node_modules or src on the server.

Working with the API

Add a route (PHP)

Add it at the bottom of functions/api.php. Routes live under /wp-json/vue-theme/v1/.

vue_theme_api_get('/books', function () {
    return get_posts(['post_type' => 'book']);
});

// URL parameter
vue_theme_api_get('/books/{id}', function ($request) {
    $book = get_post((int) $request['id']);

    if (!$book) {
        return new WP_Error('not_found', 'Book not found.', ['status' => 404]);
    }

    return $book;
});

// JSON body
vue_theme_api_post('/contact', function ($request) {
    $email = sanitize_email($request['email']);

    return ['sent' => true];
});

// Logged in users only, or users with a capability
vue_theme_api_post('/notes', 'my_callback', ['permission' => true]);
vue_theme_api_delete('/notes/{id}', 'my_callback', ['permission' => 'edit_posts']);

Use it (Vue)

In a component, useApi and useWp are auto-imported and give you reactive state:

<script setup>
const { data: books, loading, error } = useApi('books')

// WordPress core API: posts, pages, categories, media, your custom post types...
const page = ref(1)
const { data: posts, totalPages } = useWp('posts', () => ({ per_page: 6, page: page.value }))
</script>

<template>
    <p v-if="loading">Loading...</p>
    <p v-else-if="error">{{ error }}</p>
    <ul v-else>
        <li v-for="book in books" :key="book.ID">{{ book.post_title }}</li>
    </ul>
</template>

Anywhere else (stores, event handlers), use the clients:

import { api, wp } from '@/api' // or a relative path like '../api'

const books = await api.get('books')
const result = await api.post('contact', { email, message })
const posts = await wp.get('posts', { per_page: 5, search: 'vue' })
const { data, total, totalPages } = await wp.paginate('posts', { page: 2 })

Failed requests throw an ApiError with message, status and code. The nonce for logged in users is sent automatically.

Routing

Add your own routes in src/router/index.js.
Any other URL is looked up in WordPress: src/page/Content.vue shows the page or post with that slug, or a "Page not found" message.
Menus assigned to Primary Menu and Footer Menu (Appearance > Menus) are rendered by Header.vue and Footer.vue.

Integration Tips

Site title, logo and menus are available without a request: useSiteStore()
Pass your own PHP data to Vue with the vue_theme_app_config filter, then read it from window.wpVueTheme
Always use sanitizeHtml() from src/utils/html.js before rendering WordPress content with v-html
Import images from src/assets so they get the right URL after the build
Set show_in_rest to true on your custom post types to load them with useWp('your-post-type')

❓ Troubleshooting

"The Vue app is not built yet": run npm install and npm run build, or start npm run dev.
Changes don't show up: check that npm run dev is still running and that you opened the WordPress URL.
Port 5173 is already in use: create .env.local with VITE_DEV_PORT=5174.
*Local domain is not localhost, `.local, .loc or .test**: add VITE_WP_ORIGIN=http://your-domain` to .env.local.
WordPress runs in Docker: PHP can't see the dev server on your machine, so add add_filter('vue_theme_check_dev_server', '__return_false'); to functions.php while developing.
Vue routes return a server 404: enable pretty permalinks in Settings > Permalinks.

⬆️ Upgrading from 1.x

See CHANGELOG.md for the breaking changes.

Github Repo

See Headless Vue + WordPress Boilerplate v2.0.0

License

See MIT License

Prepared by: Christopher Robin Chase

Fine in Chrome, broken in Preview: two PDFKit gotchas for anyone who writes PDFs

Mon, 26 Oct 2026 00:16:01 +0000

This article was originally published on Hashnode: Fine in Chrome, broken in Preview. It is republished here with light edits.

Disclosure: we make LensUp's PDF editor, the browser tool where we ran into both bugs, so we have a direct connection to the product mentioned here. This write-up was drafted and edited with AI assistance; the bugs, test results and reproduction scripts come from our own testing, and the scripts are public so you can check every claim yourself.

We build a PDF editor that runs in the browser. It opens a PDF, lets you add text, a signature or a highlight, fill in form fields, and writes the result back as an incremental update. We checked every save with three renderers: pdf.js (Firefox and many web viewers), pdfium (Chrome) and poppler (most Linux tools). All three were happy.

Then we rendered the same files with Apple's PDFKit, the engine behind Preview on the Mac, the Files app on iOS and PDFs in Safari. It showed two problems none of the others did: a translucent highlighter that turned into an opaque bar or a sentence that vanished, and form answers printed twice on top of each other.

Neither problem shows up if you only test on Linux or in Chrome. Here are both, with small scripts that reproduce them on any Mac in a few seconds: github.com/ppop123/pdfkit-pitfalls.

Gotcha 1: an incremental update must use the same cross-reference form as the file it updates

Some background

An incremental update appends to a PDF instead of rewriting it. The new and changed objects go at the end, followed by a new cross-reference section that points back to the previous one. That's how signed PDFs stay signed, and it's why saving an edit doesn't mean rewriting the whole file: only the edit is written.

The cross-reference section comes in two forms. The classic one is an xref table followed by a trailer. PDF 1.5 added cross-reference streams (/Type /XRef), which usually come with object streams (/Type /ObjStm): many small non-stream objects compressed together into one stream.

We opened files for incremental update with pdf-lib (the @cantoo/pdf-lib fork, which supports incremental updates) and saved with the defaults, which turn object streams on. So whatever the original file used, our update ended in an XRef stream, with our new dictionaries packed into an object stream.

What PDFKit does with that

Take a one-page PDF that ends in a classic xref table and append a highlighter stroke: a yellow rectangle drawn through an ExtGState with 60% opacity and the Multiply blend mode. Written as a table-based update, it renders the same everywhere. Written as an XRef stream with the ExtGState inside an object stream, poppler still draws it correctly, but PDFKit shows an opaque yellow bar where the sentence was.

Render it with CG_PDF_VERBOSE=1 set, and CoreGraphics says why:

encountered unexpected object type: 7.
missing or invalid object number.
missing or invalid cross-reference stream.

It gives up on the update's XRef stream. Objects the update wrote out on their own are still found: the rectangle itself is drawn. Objects inside the update's object stream are not, and the ExtGState is one of them. Without it the rectangle is painted fully opaque, on top of the text.

The reverse breaks too. Over an original that ends in an XRef stream, an update written with a classic table gets:

failed to find start of cross-reference section.
font `Helvetica-7098480789' not found in document.

This time it's the original's object stream that gets lost, and the font was in it. The highlight is there; the sentence is gone.

Original's last section	Update written as	PDFKit
`xref` table	`xref` table	fine
`xref` table	XRef stream with object streams	loses the objects in the update's object stream
XRef stream	`xref` table	loses the objects in the original's object streams
XRef stream	XRef stream	fine

In our editor's checks, pdf.js, pdfium and poppler accepted all four combinations. That's exactly why a Linux-only test suite never caught it.

The fix

Look at where the original's last startxref points. If it lands on the keyword xref, the last section is a table; otherwise it's a stream. Then write the update in the same form:

// The form of the original's last cross-reference section: 'table' or 'stream'.
function xrefForm(bytes) {
  const tail = new TextDecoder('latin1').decode(bytes.subarray(Math.max(0, bytes.length - 2048)));
  const found = [...tail.matchAll(/startxref\s+(\d+)/g)];
  const offset = found.length ? Number(found[found.length - 1][1]) : NaN;
  if (!(offset >= 0 && offset < bytes.length)) return 'table';
  let i = offset;
  while (i < bytes.length && /\s/.test(String.fromCharCode(bytes[i]))) i += 1;
  return new TextDecoder('latin1').decode(bytes.subarray(i, i + 4)) === 'xref' ? 'table' : 'stream';
}

const doc = await PDFDocument.load(bytes, { forIncrementalUpdate: true });
// … edit …
const saved = await doc.save({ useObjectStreams: xrefForm(bytes) === 'stream' });

Hybrid-reference files, whose trailer is a table that also points to an XRef stream, end in a table, so they count as 'table' here.

Gotcha 2: PDFKit draws filled text fields itself

What PDFKit does

A form field's look is supposed to come from its appearance stream (/AP): a small content stream in which the writer draws the value. For a text field that has a value, PDFKit does something else. It draws the value (/V) itself with CoreText, in the font named by the field's default appearance string (/DA), and it drops the text-showing operators (BT … Tj … ET) from the appearance stream. Everything else in the appearance stream it still paints, such as paths and Form XObjects.

You can see the first half even with pdf-lib's own appearance. In the first row below, poppler draws pdf-lib's auto-sized Helvetica, while PDFKit ignores it and draws its own rendering of the value at a different size.

Why that bit us

Our text engine shapes text itself (joining Persian and Arabic, ordering mixed-direction text, falling back between fonts) and draws the result as glyph outlines, so every reader shows exactly the same glyphs. In a field's appearance, those outlines are paths. PDFKit painted the paths and then drew /V again with CoreText on top: two copies of every answer, as in the second row. On a real IRS W-9 the two copies didn't even line up, because PDFKit left-aligned its copy while our appearance was right-aligned.

None of these stopped the second drawing: making the field read-only, setting /NeedAppearances to false, removing the /Tx BMC … EMC marked content, or changing the font or color in /DA.

The fix

Write the value as text after all, just not in a real font: use a Type 3 font whose glyph procedures are the same outlines. PDFKit drops text-showing operators, Type 3 included, and draws the value once in its own rendering. pdf.js, pdfium and poppler draw the Type 3 glyphs, which are our outlines. That's the third row.

The trade-off is that in Preview you get PDFKit's rendering of the value (its font from /DA, its alignment), not yours. For us that was acceptable, since CoreText shapes Persian correctly.

Two related notes:

Dropdowns and list boxes are different. PDFKit doesn't redraw them, so for choice fields we kept the outlines.
Acrobat had its own problem with outlines. Acrobat Reader drew our outline appearances in some forms but left the box blank in others (fields created by pdf-lib, with a /MK background color). It drew the Type 3 version in both.

Bonus gotcha from Acrobat: Reader extensions (`/UR3`)

Many official forms, the W-9 among them, carry usage rights (/Perms /UR3, "Reader extensions"): a signature over the file as issued. Change the file and Acrobat Reader opens it with:

This document enabled extended features in Adobe Acrobat Reader. The document has been changed since it was created and use of extended features is no longer available.

Every save changes the file, so on save we now remove /UR3 and the older /UR from /Perms (and /Perms itself if nothing else is left). A certification signature (/DocMDP) stays. iText does the same thing with removeUsageRights. To be clear about what we've checked: we saw the warning in Acrobat Reader, and we haven't re-tested the fixed files there yet.

How to test with PDFKit without clicking through Preview

PDFKit is scriptable from Swift in about twenty lines: open the file with PDFDocument, draw page 1 into a bitmap with PDFPage.draw(with:to:) (form widgets included), and write a PNG. Run it with CG_PDF_VERBOSE=1 and CoreGraphics prints what it didn't like. The repo's render-pdfkit.swift does exactly that. qlmanage -t, the Quick Look thumbnailer, goes through PDFKit too.

If you compare against pdfium from Python: pypdfium2 doesn't draw form fields unless you call pdf.init_forms() first. Without it, every field looks empty, which is easy to mistake for a bug in your writer.

Takeaways

Three renderers agreeing on a file doesn't mean the viewer on every Mac and iPhone will. If your PDFs reach Apple devices, render them with PDFKit, in CI on a macOS runner or at least by hand.
In an incremental update, match the cross-reference form of the file you're updating.
For a filled text field, PDFKit draws the value itself. Avoid drawing the value into the appearance as paths; text in a Type 3 font works everywhere we tested.

The reproductions, in Node and Swift, are MIT-licensed: github.com/ppop123/pdfkit-pitfalls.

About the author: the team behind this post builds LensUp Scanner, a free set of browser tools for scanning documents and working with PDFs. If you have seen other PDFKit quirks, the pdfkit-pitfalls repo is open to issues and pull requests.

devtemDesign: one config object paints a whole landing page

Sun, 25 Oct 2026 10:50:19 +0000

A zero-dependency page engine in plain HTML, CSS and JS. 7 templates, live theming, pricing, FAQ, stats and a mobile drawer from a single config. Full reference included

Every landing page I built started the same way: nav, hero, feature cards, pricing, FAQ, footer, then a day of making it responsive. So I wrote an engine that does that part for me.

devtemDesign takes one config object and renders the whole page. No framework, no build step, no dependencies. Two tags and one function call.

This post is both an introduction and a reference for v0.1.0.

Try it in 30 seconds

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/devtemdesign@0.1.0/style.min.css">
<script src="https://cdn.jsdelivr.net/npm/devtemdesign@0.1.0/script.min.js"></script>

<div id="app-root"></div>
<script>
  devtemDesign("app-root", {
    template: "cyber",
    logoName: "MYAPP",
    heroTitleLine1: "Declarative UI,",
    heroTitleLine2: "Zero-Config Motion",
    heroSubtitle: "One config object. Complete animated landing.",
    primaryBtnText: "Get started",
    primaryBtnHref: "/docs"
  });
</script>

That gives you a sticky glass navbar, an animated hero, ambient background orbs, reveal-on-scroll, a mobile drawer and a footer. Every section except the hero is optional, and a section only renders when its config key is present.

If you want to skip the code entirely, the builder generates a config from a description and lets you edit it live.

What's in 0.1.0

7 templates: figsh, cyber, aurora, monochrome, sunset, ocean, and paper (light).
Live theming: switch at runtime, add a built-in theme button, or override any design token.
New sections: stats with count-up numbers, FAQ accordion, closing CTA, and pricing with a Monthly/Yearly toggle.
Interactions: scroll progress bar, active nav link, card spotlight, seamless brand marquee, back-to-top button.
A real lifecycle: devtemDesign() returns { setTemplate, destroy }.
Accessibility: skip link, focus rings, aria-expanded on the menu, native <details> for FAQ, full prefers-reduced-motion support.

A fuller example

const page = devtemDesign("app-root", {
  template: "ocean",
  themeSwitcher: true,
  logoName: "ORBIT",
  navLinks: [
    { label: "Features", href: "#features" },
    { label: "Pricing", href: "#pricing" },
    { label: "FAQ", href: "#faq" }
  ],
  ctaText: "Start free",
  ctaHref: "#pricing",

  heroBadge: "New: team workspaces",
  heroTitleLine1: "Ship analytics,",
  heroTitleLine2: "not dashboards",
  heroSubtitle: "Turn raw events into answers your whole team can read.",
  primaryBtnText: "Start free",
  primaryBtnHref: "#pricing",

  stats: [
    { value: "12k+", label: "Teams" },
    { value: "99.9%", label: "Uptime" }
  ],

  features: [
    { title: "Live metrics", desc: "Streams update in under a second.", icon: "⚡" },
    { title: "Shared boards", desc: "One link for the whole team.", icon: "📊" }
  ],

  yearlyBadge: "Save 20%",
  pricing: [
    { tier: "Starter", amount: "$0", features: ["3 boards"], cta: "Start free", href: "#" },
    { tier: "Team", amount: "$19", period: "/mo",
      yearly: { amount: "$182", period: "/yr" },
      featured: true, badge: "Most popular",
      features: ["Unlimited boards", "Priority support"], cta: "Go Team", href: "#" }
  ],

  faq: [{ q: "Is there a free plan?", a: "Yes. Starter is free forever." }],
  cta: { title: "See your data differently", text: "Create account", href: "#" },
  footer: { tagline: "Built with devtemDesign.", copy: "© 2026 Orbit" }
});

You can see this running, with a template picker and a mobile preview, on the examples page.

Templates

Template	Vibe	Accents
`figsh`	Futuristic glass	Cyan, purple, pink
`cyber`	Neon cyberpunk	Cyan, magenta, red
`aurora`	Organic nature	Emerald, violet, blue
`monochrome`	Minimal grayscale	White, silver
`sunset`	Warm dusk	Orange, rose, gold
`ocean`	Cool depth	Sky, teal, indigo
`paper`	Light mode	Indigo, pink, cyan

Every color in the stylesheet comes from a token, which is why the light template works without a separate stylesheet.

Runtime control

const page = devtemDesign("app-root", config);

page.setTemplate("sunset");   // switch theme, no re-render
page.destroy();               // remove listeners, observers and markup

devtemDesign.version;         // "0.1.0"
devtemDesign.templates;       // ["figsh", "cyber", "aurora", ...]

Calling devtemDesign() again on the same container destroys the previous instance first, so there are no leaked listeners.

Theme tokens

Override any token with the theme option:

theme: { accent: "#ff4d6d", accent2: "#ffb703", "bg-deep": "#0b0710" }

Token	Purpose
`--accent`, `--accent2`, `--accent3`	Brand colors and gradients
`--text`, `--muted`	Primary and secondary text
`--bg-deep`	Page background, and text on filled buttons
`--glass-bg`, `--glass-border`, `--glass-blur`	Card surfaces
`--surface`, `--line`	Subtle fills and dividers
`--orb`	Ambient orb opacity

Config reference

All text fields accept HTML, so icons and inline markup work. Only pass content you trust.

Option	Type	Default	Description
`template`	string	`"figsh"`	One of the 7 templates
`theme`	object	`{}`	Token overrides
`themeSwitcher`	boolean or string[]	`false`	Navbar theme button. An array limits the cycle. Choice is saved in `localStorage`
`cursor`	boolean	`true`	Custom cursor on or off
`logo`, `logoName`, `logoHref`	string	fscss logo, `"CORE"`, `"/"`	Brand image, name and link
`navLinks`	(string or `{ label, href }`)[]	Features, How it works, Pricing	Navbar and drawer links
`ctaText`, `ctaHref`	string	`"Get started"`, `"#"`	Navbar button

Hero

Option	Description
`heroBadge`	Pill above the title
`heroTitleLine1`, `heroTitleLine2`	H1 lines. The second has an animated gradient
`heroSubtitle`	Paragraph under the H1
`primaryBtnText`, `primaryBtnHref`	Main button
`secondaryBtnText`, `secondaryBtnHref`	Ghost button, rendered only when text is set
`brands`, `brandsSubtitle`	Hero chips and a seamless marquee that pauses on hover

Sections

Section	Keys	Anchor
Stats	`stats: [{ value, label }]`	`#stats`
Features	`featuresLabel`, `featuresTitle`, `featuresSub`, `features: [{ title, desc, icon }]`	`#features`
Steps	`stepsLabel`, `stepsTitle`, `stepsSub`, `steps: [{ title, desc }]`	`#how`
Panels	`panelsLabel`, `panelsTitle`, `panelsSub`, `panels: [{ tag, title, desc }]`	none
Pricing	`pricingLabel`, `pricingTitle`, `pricingSub`, `yearlyBadge`, `pricing: [...]`	`#pricing`
FAQ	`faqLabel`, `faqTitle`, `faqSub`, `faq: [{ q, a }]`	`#faq`
CTA	`cta: { title, sub, text, href }`	none

Stat values keep their prefix, suffix, commas and decimals, so "$1,200", "99.9%" and "12k+" all count up correctly.

A pricing plan looks like this. A Monthly/Yearly toggle appears automatically when any plan has yearly:

{
  tier: "Pro", amount: "$12", period: "/mo", desc: "For product landings.",
  features: ["Everything in Free", "Priority support"],
  cta: "Go Pro", href: "/signup",
  featured: true, badge: "Most popular",
  yearly: { amount: "$115", period: "/yr" }
}

footer: {
  tagline: "Declarative UI engine for the modern web.",
  copy: "© 2026 devtem-dev",
  columns: [{ heading: "Product", links: [{ label: "Docs", href: "/docs" }] }],
  social:  [{ icon: "fab fa-github", href: "https://github.com/devtem-dev", label: "GitHub" }],
  legal:   [{ label: "Privacy", href: "/privacy" }]
}

The full schema, with types and defaults, lives at design.devtem.org/api.

Upgrading from 0.0.2

Three option names changed to match what the code actually reads:

0.0.2 docs	Use now
`heroTag`	`heroBadge`
`featuresSectionLabel`	`featuresLabel`
`featuresSectionTitle`	`featuresTitle`

Good to know

Font Awesome is optional. It is only needed for icon fields and footer social icons. The hamburger, checkmarks and accordions are pure CSS.
Theming uses color-mix(), so you need Chrome 111+, Safari 16.2+ or Firefox 113+. Older browsers still render the page but lose some tinted surfaces.
Rendering replaces the container's contents. Give the engine its own wrapper element.

"'use client' Doesn't Turn Your Whole App Into a Client Component (The Children Trick Nobody Explain

Sat, 24 Oct 2026 11:28:48 +0000

You need a theme provider, so you create a file, add 'use client' at the top, and wrap your app in it.

Then a nagging thought arrives: "I just wrapped my entire layout in a client component. Did I turn the whole app into client-side React?"

Most developers either panic and avoid providers, or give up and put 'use client' at the top of every file "just to be safe". Both are the wrong response, and the actual rule is simpler than you expect.

The Setup

// components/ThemeProvider.tsx
'use client';

import { createContext, useState } from 'react';

export const ThemeContext = createContext('light');

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme] = useState('light');
  return <ThemeContext value={theme}>{children}</ThemeContext>;
}

// app/layout.tsx  (a Server Component)
import { ThemeProvider } from '@/components/ThemeProvider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

ThemeProvider is a Client Component. It wraps every page. So are all the pages client components now?

No.

What 'use client' Actually Does

'use client' marks a boundary. It says: "this file, and everything this file imports, is part of the JavaScript sent to the browser."

The key word is imports. The boundary follows the import graph, not the position in the rendered tree.

In the layout above, children is not imported by ThemeProvider. It is passed in as a prop by the layout, which is a Server Component. The server renders the page first, and hands the finished result to the client component as a slot to fill.

So your pages stay Server Components. They can still fetch data on the server, use secrets, and ship no JavaScript for their static parts.

The Mistake That Does Change Things

Now look at this version:

// components/ThemeProvider.tsx
'use client';

import { Dashboard } from './Dashboard'; // imported, not passed in

export function ThemeProvider() {
  // ...
  return <Dashboard />;
}

Here the client file imports Dashboard, so Dashboard joins the client bundle, along with everything it imports. If it was a Server Component that queried your database, it is no longer one. It will either break the build or quietly ship heavy code to every visitor.

The difference between the two examples is a single word: import versus prop.

The Pattern: Pass Server Components Through as Children

Any time a client component needs to wrap server content, use a slot:

// components/Modal.tsx
'use client';

import { useState } from 'react';

export function Modal({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button onClick={() => setOpen(true)}>Show stats</button>
      {open && <div role="dialog">{children}</div>}
    </>
  );
}

// app/page.tsx  (Server Component)
import { Modal } from '@/components/Modal';
import { Stats } from '@/components/Stats'; // reads the database

export default function Page() {
  return (
    <Modal>
      <Stats />
    </Modal>
  );
}

Stats runs on the server, even though it is rendered inside a client component's JSX. The button and the toggle are interactive in the browser. The data never leaves the server except as finished markup.

This works for any prop that holds JSX, not only children. A sidebar prop or a header prop behaves the same way.

Rule of Thumb: Push the Boundary Down

Put 'use client' on the smallest piece that needs interactivity, not on the page:

// Bad: the whole page becomes client code
'use client';
export default function ProductPage() { /* ...200 lines... */ }

// Better: only the button is client code
export default function ProductPage() {
  return (
    <main>
      <ProductDetails />   {/* server */}
      <AddToCartButton />  {/* 'use client' lives here */}
    </main>
  );
}

A page that is mostly text and images, with one button, should send JavaScript for the button, not for the page. Less JavaScript sent means a faster load, which is what I walk through in this plain-language guide to Core Web Vitals.

Two Things That Still Bite

1. Props crossing the boundary must be serializable. Data goes from server to client as text, so you can pass strings, numbers, plain objects, arrays and dates. You cannot pass a regular function. (Server Actions are the exception, because they are designed to cross.)

// Error: functions cannot be passed to Client Components
<ClientButton onClick={() => console.log('hi')} />

Define the handler inside the client component instead.

2. A server-only module can leak into the client by import. If a client file imports a helper that touches your database or secrets, the build either fails or bundles code you never meant to ship. The server-only package turns that into a loud build error:

// lib/db.ts
import 'server-only';

Import this file from a client component and the build fails, instead of shipping the connection code.

The Rule

'use client' marks an import boundary, not a rendering zone. Whatever a client file imports goes to the browser. Whatever you pass to it as props or children can stay on the server. Keep the directive on small interactive leaves, and use the children slot for everything else.

Quick audit: search your project for 'use client' and look at each file. If it is a page or a layout, ask whether it really needs state or browser APIs. If it is a wrapper, check that it receives its content as children and does not import it.

If you want a Next.js starting point built around the App Router, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Where in your project is 'use client' doing more than it needs to? Drop it in the comments, and tell me if the children trick surprised you.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

I Built Avi.js — A Lightweight TypeScript Framework Inspired by NestJS

Thu, 22 Oct 2026 14:41:50 +0000

I Built Avi.js — A Lightweight TypeScript Framework Inspired by NestJS

I've been working on an open-source project called Avi.js, and I recently released v0.1.2! 🚀

Avi.js — Structure without the overhead.

It's a lightweight, TypeScript-first backend framework for Node.js, inspired by the structured development experience of NestJS.

The idea started with a question:

Can we build a structured TypeScript backend framework with modules, controllers, and dependency injection—without requiring reflect-metadata?

That's what I've been exploring with Avi.js.

What I've built so far

Before getting into the latest update, here's a look at what Avi.js currently supports.

1. Modules, controllers, and dependency injection

Avi.js supports a modular architecture with explicit dependency declarations rather than relying on runtime reflection.

It includes singleton, transient, and request-scoped providers, along with startup checks for missing dependencies and circular references.

The goal is to keep dependencies visible in code while providing a familiar way to organize backend applications.

2. Two API styles, one engine

Avi.js supports two ways of defining controllers:

Decorator-based API: Class-based controllers and modules using standard TC39 decorators.
Explicit API: Plain TypeScript objects and functions without decorators.

Both approaches use the same router, dependency injection container, and request pipeline.

This gives developers the flexibility to choose the style that fits their project.

3. Dependency injection without `reflect-metadata`

Instead of inferring constructor dependencies through emitted runtime metadata, Avi.js uses explicit declarations such as static inject.

For example:

@Controller('/users')
class UsersController {
  static inject = [UsersService] as const;

  constructor(private readonly users: UsersService) {}
}

This approach doesn't require reflect-metadata, emitDecoratorMetadata, or legacy experimental decorators.

It's a design choice focused on making dependency wiring explicit and understandable.

4. Native Node.js HTTP

Avi.js runs on Node.js's native node:http module without requiring Express or Fastify underneath.

It supports:

HTTP routing and route parameters
Middleware and guards
Request and response hooks
JSON, text, and streaming responses
Graceful shutdown

5. Validation, security, and developer tooling

Avi.js also includes several features for building and maintaining backend applications:

Schema validation using Standard Schema-compatible libraries
CORS and security headers
OpenAPI 3.1 document generation
Testing utilities with provider overrides
CLI scaffolding and code generation
Startup checks for dependency and route configuration errors

These features are already available in the current early-development releases.

What's new in v0.1.2?

One feature I'm particularly excited about is resource generation.

You can now generate an entire CRUD resource using one command:

npx avi g resource posts

For a modular project, the CLI generates:

src/
└── modules/
    └── posts/
        ├── posts.module.ts
        ├── posts.controller.ts
        └── posts.service.ts

The CLI also registers the resource in your application automatically.

The generated resource includes working GET, POST, PATCH, and DELETE routes backed by an in-memory store, which you can later replace with your own database integration.

For minimal projects, Avi.js generates services and routes without requiring modules.

The goal is to reduce repetitive setup while keeping the generated code understandable and editable.

Getting started

You can try Avi.js with Node.js 22.12 or newer.

Create a new project:

npm create avi@latest my-api
cd my-api
npm install
npm run dev

Avi.js currently provides two official project templates:

Modular (default): A feature-first structure with modules, controllers, and services.
Minimal: A smaller, functional structure using explicit routes and services.

Both templates run on the same framework engine, so you can start small and introduce more structure as your application grows.

You can also install the core package directly into an existing project:

npm install @avijs/core

Avi.js is still in pre-alpha development (0.x), and its APIs may change before 1.0.

I'm not trying to claim it's faster or better than established frameworks. It's an experiment in building a structured backend framework with explicit dependencies and fewer runtime abstractions.

I'm sharing it because I'd love to get feedback from developers who enjoy working with Node.js and TypeScript.

If you're curious, feel free to try it, open an issue, or contribute.

Official website: https://chrischase011.github.io/avi-js/

GitHub: https://github.com/chrischase011/avi-js

Latest release: https://github.com/chrischase011/avi-js/releases/tag/v0.1.2

Thanks for checking it out! 🚀

#typescript #nodejs #opensource #webdev

How to Fix Metro Bundler Stuck or Not Starting Errors in React Native

Thu, 22 Oct 2026 12:02:08 +0000

If you've worked with React Native for a while, you've probably run into a problem where Metro refuses to start, gets stuck while bundling, or leaves your app waiting for JavaScript that never arrives.

Sometimes the terminal shows an error immediately. Other times, Metro appears to start normally, but the app stays on a loading screen or fails to connect to the development server.

The frustrating part is that these symptoms can have completely different causes. A port conflict, stale cache, broken dependency installation, invalid configuration, or network issue can all look like a Metro problem.

Here's how to narrow it down and fix the actual cause instead of repeatedly restarting your project and hoping something changes.

1. Identify What Metro Is Actually Doing

Before changing anything, identify which of these situations matches your problem.

Metro won't start: The development server exits with an error, refuses to launch, or reports that a port is already in use.
Metro starts but gets stuck bundling: The terminal shows that bundling has started, but it never finishes.
The app cannot connect to Metro: The server appears to be running, but the application displays a loading screen or a connection error.
Metro starts, but the app crashes: Bundling may be successful, but a JavaScript exception or native configuration problem prevents the app from running.

These are different failure points. Clearing the cache might help with a stale bundle, but it won't fix a port occupied by another process or an invalid native configuration.

Start with the simplest checks and move toward more disruptive fixes only when necessary.

2. Stop Metro and Start It Again

First, stop any Metro server running in the terminal by pressing Ctrl + C.

Then start it using the command appropriate for your project.

If you're using Expo

From your project directory, run:

npx expo start

To clear Expo's Metro cache at the same time, use:

npx expo start --clear

If you're using React Native CLI

Start Metro from your project's root directory:

npx react-native start

If you suspect stale cached files, use:

npx react-native start --reset-cache

Important: You don't need to clear the cache every time Metro fails. Start with the normal command. Use the cache-reset option when the symptoms suggest stale or inconsistent cached data, or when a normal restart doesn't help.

If Metro exits immediately, read the terminal output before trying another command. The first meaningful error is often more useful than the final stack trace.

3. Check Whether Port 8081 Is Already in Use

Metro normally uses port 8081. If another process is listening on that port, Metro may fail to start or ask you to use a different one.

The terminal might show a message similar to:

Error: listen EADDRINUSE: address already in use :::8081

This means another process is already using the requested address and port.

On Windows

Open Command Prompt and run:

netstat -ano | findstr :8081

Look for a line containing LISTENING. The last column contains the process ID (PID).

You can identify the process with:

tasklist /FI "PID eq 12345"

Replace 12345 with the actual PID.

If you've confirmed that the process is an old Metro server you no longer need, you can stop it:

taskkill /PID 12345 /F

On macOS or Linux

Run:

lsof -i :8081

Inspect the process listed for port 8081. If it's an old Metro process that you no longer need, stop that specific process:

kill <PID>

Replace <PID> with the actual process ID.

Don't terminate a process simply because it's using the port. Confirm what it is first, especially if other development tools are running.

Once the port is available, start Metro again.

4. Clear Metro's Cache When Bundling Gets Stuck

Metro transforms your JavaScript files and their dependencies into a bundle the application can execute. Cached transformation results help make subsequent builds faster, but stale or inconsistent cached data can sometimes cause confusing behavior.

Typical symptoms include:

Bundling worked before, but now fails after code or dependency changes.
The app appears to use an older version of your JavaScript.
Metro repeatedly fails while transforming files without an obvious dependency error.
A normal restart doesn't resolve the problem.

Try the appropriate cache-reset command from Step 2.

After the cache is cleared, let Metro rebuild the bundle. The first build can take longer because the cached transformation results need to be regenerated.

If the same error returns, don't keep clearing the cache. Look at the specific file, dependency, or configuration mentioned in the terminal output. A repeatable error usually means there's something more specific to fix.

5. Check Your Dependencies Before Reinstalling Everything

Metro depends on the packages and configuration in your React Native project. If a package installation was interrupted, dependencies were changed, or incompatible versions were introduced, Metro may fail while loading its configuration or resolving modules.

Start by checking the actual error.

For example, these messages point toward different problems:

Cannot find module ...

Unable to resolve module ...

Cannot find module 'metro-config'

A missing module doesn't automatically mean the entire dependency installation is broken. It might be an incorrect import path, a package that was never installed, or a version mismatch.

Check the following:

Did the problem start immediately after installing, removing, or updating a package?
Does the error identify a particular module or package?
Does your project use the package versions expected by its React Native or Expo version?
Did you accidentally run the installation command from the wrong directory?

If the project uses npm and has a valid, committed package-lock.json, a clean installation may be appropriate:

npm ci

This reinstalls dependencies according to the lockfile and removes the existing node_modules directory as part of the process.

For a Yarn project, use the installation command appropriate for its Yarn version and existing lockfile. Don't switch package managers or delete your lockfile just to see whether Metro starts.

Avoid deleting node_modules, lockfiles, and caches all at once as your first response. Doing so can introduce new version differences and make it harder to identify what originally caused the failure.

6. Check Metro and Expo Configuration

If Metro reports an error while loading its configuration, clearing the cache or reinstalling dependencies might not help.

Look for changes to files such as:

metro.config.js
babel.config.js
package.json
Expo app configuration, such as app.json or app.config.js

Pay particular attention to recent changes involving custom Metro configuration, Babel plugins, aliases, monorepo settings, or package versions.

For example, if Metro fails while loading metro.config.js, inspect the configuration and the package named in the error. A missing import or incompatible configuration dependency can prevent the server from starting at all.

If the problem appeared after a configuration change, compare that change with the last working version. Reverting one recent change is often more informative than rebuilding the entire environment.

For Expo projects, also make sure you're following the configuration requirements for your installed Expo SDK rather than copying a Metro configuration from an unrelated project or older tutorial.

7. If Metro Runs but the App Cannot Connect

A running Metro server doesn't guarantee that your app can reach it.

This distinction matters because repeatedly resetting Metro's cache won't fix a connection problem.

Check the development-server URL

When Metro starts, inspect the URL or connection information it prints in the terminal.

If you're using a physical device, make sure the device and computer can communicate over the selected network. VPNs, firewalls, guest Wi-Fi networks, and network isolation can interfere with local development connections.

If you're using Expo

Expo supports different connection methods depending on your environment and configuration. If the normal connection method doesn't work, try the tunnel option:

npx expo start --tunnel

A tunnel can help when the device cannot reach your computer directly over the local network, although it may be slower and depends on the tunnel service being available.

If you're using an Android emulator

Check that the emulator is running and that the development server is reachable. For a React Native CLI workflow using the standard Android emulator setup, you can forward port 8081 with:

adb reverse tcp:8081 tcp:8081

This is useful when the emulator needs a route to Metro through Android Debug Bridge. It isn't a universal fix for every device or connection setup.

If the app can connect but crashes after loading the bundle, move on to the JavaScript or native error shown by the app. At that point, Metro itself might be working correctly.

8. Don't Confuse a JavaScript Error With a Metro Startup Failure

Sometimes developers blame Metro because the application stops working immediately after a successful bundle.

But these messages describe different problems:

Metro startup error: The development server cannot initialize.
Module resolution error: Metro cannot find or resolve a requested module.
JavaScript runtime exception: The bundle loads, but the application encounters an error while executing code.
Native build error: The Android or iOS application fails during native compilation or configuration.

For example, if Metro reports that it cannot resolve a module imported by App.tsx, investigate the import path, filename, package installation, and any configured aliases.

If the Android build fails before the application starts, inspect the native build output instead of treating every failure as a Metro cache problem.

Finding the correct failure point saves time because each category requires a different solution.

9. When None of These Fixes Works

If Metro still refuses to start, collect the evidence before making more changes.

A useful troubleshooting report should include:

The exact command used to start Metro.
The full terminal error, especially the first meaningful error before the stack trace.
Your operating system.
Whether the project uses Expo or React Native CLI.
The relevant React Native and Expo versions.
Any recent dependency or configuration changes.
Whether Metro fails to start, gets stuck bundling, or starts while the app cannot connect.

Remove access tokens, passwords, private URLs, and other sensitive information before sharing logs publicly.

If the output contains several errors, don't assume the final message is the root cause. A failure to load one configuration dependency can trigger multiple follow-up errors.

This is also where a diagnostic tool can help. If you've already tried the obvious fixes and the logs are difficult to interpret, you can paste the relevant error and technical context into FixMyError. It can help analyze the failure, identify likely causes, and suggest targeted next steps instead of making you cycle through unrelated fixes.

Final Thoughts

When Metro Bundler gets stuck or refuses to start, the best approach is to identify where the failure occurs before changing your project.

Start with a normal restart, check port 8081, clear the cache when appropriate, and inspect dependency or configuration errors when they appear. If Metro is running but the app cannot connect, troubleshoot the connection rather than repeatedly resetting the bundler.

The goal isn't to run every possible fix. It's to find the specific reason your development environment stopped working and make the smallest change that resolves it.

Your Next.js Dates Are Wrong for Half Your Users (and the Hydration Warning Is Only the Start)

Wed, 21 Oct 2026 11:48:27 +0000

You format a date in a component. It looks right on your laptop. Then a user in another country opens the page and either sees a console full of hydration errors, or worse, sees nothing wrong at all and reads the wrong time.

I live in a timezone that is five hours away from where most servers run, so this one finds me every time.

The Code That Looks Fine

// components/OrderDate.tsx
export function OrderDate({ date }: { date: string }) {
  return <p>Ordered on {new Date(date).toLocaleString()}</p>;
}

No hooks, no browser APIs, nothing that looks risky. It even works in next dev, because on your machine the server and the browser are the same computer.

Why It Breaks

In Next.js, this component runs twice: once on the server to produce the HTML, and again in the browser to hydrate it. toLocaleString() with no arguments uses the timezone and language of whatever machine runs it.

The server is often in UTC, with a default locale such as en-US.
Your user's browser might be in Karachi, with en-GB.

Server HTML:   Ordered on 10/20/2026, 10:15:00 AM
Browser render: Ordered on 20/10/2026, 15:15:00

React compares the two, finds that they differ, and logs a hydration error. In development, you see it. In production, React quietly tries to recover by re-rendering on the client, which costs time and can cause a visible flash.

Why It Is Hard to Catch

It never fails where you test. Same machine, same timezone, same locale: the two outputs are identical.
Many users never see an error. The page just shows one format for a split second and then another.
It often hides inside other pieces of data. Date.now(), Math.random(), new Date().getFullYear() and anything that reads window or localStorage can all produce a different value on the server and in the browser.

The Fix That Is Tempting, and Wrong

You will find this advice everywhere:

<p suppressHydrationWarning>
  Ordered on {new Date(date).toLocaleString()}
</p>

It does silence the warning. But per React's documentation, it only suppresses the warning on that one element and does not patch up mismatched text. The user can end up looking at the server's version of the time, which is in the wrong timezone.

You did not fix the bug, you removed the alarm for it.

Fix 1: Make the Output the Same on Both Sides

Pass an explicit locale and timezone, so the server and the browser calculate the same string:

export function OrderDate({ date }: { date: string }) {
  const text = new Date(date).toLocaleString('en-US', {
    timeZone: 'UTC',
    dateStyle: 'medium',
    timeStyle: 'short',
  });

  return <time dateTime={date}>{text} UTC</time>;
}

This is deterministic, so there is nothing to mismatch. It is the right choice for logs, admin tables and anything where showing UTC is acceptable. Label it as UTC so nobody reads it as local time.

Fix 2: Show the Local Time After the Page Loads

If users should see their own timezone, only compute it in the browser:

'use client';

import { useEffect, useState } from 'react';

export function LocalDate({ date }: { date: string }) {
  const [local, setLocal] = useState<string | null>(null);

  useEffect(() => {
    setLocal(
      new Date(date).toLocaleString(undefined, {
        dateStyle: 'medium',
        timeStyle: 'short',
      })
    );
  }, [date]);

  return (
    <time dateTime={date}>
      {local ?? new Date(date).toISOString().slice(0, 10)}
    </time>
  );
}

The first render, on the server and in the browser, shows a stable fallback (the ISO date). Right after hydration, useEffect runs only in the browser and swaps in the local time. Nothing mismatches, and the user ends up with the right value.

The cost is a brief change from the fallback to the local string. Keep the fallback short so the layout does not jump.

Fix 3: Store and Send Dates as ISO Strings

Whichever display option you pick, pass dates around as ISO strings (2026-10-20T10:15:00.000Z) and format them only at the edge, in one place. An ISO string is plain text, so it means the same thing on the server, in the browser and in your database.

Which One When

Situation	Fix
Admin tables, logs, reports	Fixed locale and `timeZone: 'UTC'`
Customer-facing times (orders, bookings, messages)	Format in the browser after mount
A date that never changes (blog post date)	Fixed locale and timezone, since the author's date is what matters

The Rule

Any value that depends on where the code runs, such as timezone, locale, the current time or a random number, will differ between the server and the browser. Either make it identical on both sides, or compute it only in the browser after hydration. Do not suppress the warning and hope.

Quick audit: search your project for toLocaleString(, toLocaleDateString(, Date.now() and Math.random() inside components that render on the server. Each one is either deterministic on purpose, or a mismatch that has not met a user in another timezone yet.

Hydration mistakes also slow pages down, because React has to redo work in the browser. I explain what that does to real-world speed scores in this plain-language guide to Core Web Vitals, and I keep every date in my Next.js templates formatted through one small helper so the server and the browser always agree.

Get the templates: https://pixelanas.gumroad.com

Which timezone bug has bitten you hardest? Drop it in the comments, especially if it only showed up in production.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

I built a blog engine with no build step — one JSON file, a noscript list, and a gated RSS feed

Wed, 21 Oct 2026 09:34:26 +0000

I run NitroIDE, a free browser IDE where your code never leaves the tab — no signup, no cloud backend, no waiting for a container to boot. Last week I rebuilt its blog engine, and the whole thing runs on one JSON file.

No static site generator. No build step. blog-data.json holds every post, and a small vanilla script renders the list, the article pages, and the search index. If JavaScript is off, readers still get a full noscript list of every article. The RSS feed is gated so it only serves valid items — one bad entity used to break the whole feed, and that taught me to validate before shipping.

Why this matters: most blog setups I tried wanted a framework, a pipeline, or a CMS. For a small indie site, that is overhead I do not need. One JSON file, one script, and the blog is fast, private, and mine.

The part I am proudest of: the site works fully offline once loaded, and the blog is no exception. Try NitroIDE free at https://nitroide.com/?utm_source=coderlegion&utm_medium=article&utm_campaign=daily-2026-10-21 — no account, just code.

How to Scrape Threads with Node.js: Profiles, Posts, Replies, and an Engagement Tracker (2026)

Wed, 21 Oct 2026 09:05:56 +0000

Threads is an awkward target. The web app is a React client from Meta, most of the interesting data loads through internal GraphQL calls, and a logged-out visitor sees only a slice of what a logged-in one does. Still, a lot of public data ships inside the first HTML response, and for a modest job like "track likes and replies on one account's recent posts" that slice is enough.

This tutorial builds a small threads scraper in Node.js 18+ with nothing but native fetch. It reads a public profile, pulls its recent posts with like, reply, repost, and quote counts, and appends a timestamped snapshot to a JSON Lines file every time it runs. At the end there's a short report script that shows which posts gained the most engagement between runs.

I'll also be upfront about where this breaks, because on Threads it breaks often.

What a logged-out visitor can reach

Short version, as of writing:

Profile pages (https://www.threads.com/@handle): name, bio, follower count, verification, and the first batch of recent posts.
Single post pages (https://www.threads.com/@handle/post/<code>): the post itself and usually a first batch of replies.
Search, feeds, follower lists, "load more": these either show a login prompt or depend on GraphQL calls that need session tokens. Treat them as off-limits for a no-login scraper.

Threads moved its main domain from threads.net to threads.com in 2025. Old threads.net links redirect, so let fetch follow redirects and normalize URLs to threads.com in your own storage so the same post doesn't get two keys.

Where the data actually lives

If you open the page source of a profile, you won't find the posts as readable HTML. What you will find are many <script type="application/json"> tags, several marked with a data-sjs attribute. These are server-side preloaded data for Meta's Relay client, and some of them contain the same post objects the app renders: code, taken_at, like_count, caption.text, and a text_post_app_info object with direct_reply_count, repost_count, and quote_count.

The structure is deeply nested and changes without notice, so don't hard-code a path like result.data.mediaData.edges[0].... A sturdier approach is to parse every JSON script and walk the whole tree looking for anything that looks like a post. That costs a few milliseconds and survives most reshuffles.

Setup

mkdir threads-scraper && cd threads-scraper
npm init -y
npm pkg set type=module

No dependencies. Node 18 or newer gives you global fetch, and everything else comes from the standard library.

Step 1: Fetch a page politely

// fetchPage.js
const UA =
  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 " +
  "(KHTML, like Gecko) Chrome/129.0 Safari/537.36";

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

export async function fetchPage(url, { retries = 3 } = {}) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    const res = await fetch(url, {
      headers: {
        "user-agent": UA,
        "accept": "text/html,application/xhtml+xml",
        "accept-language": "en-US,en;q=0.9",
      },
      redirect: "follow",
    });

    if (res.ok) {
      const html = await res.text();
      // A login redirect sometimes comes back as 200 with a tiny shell page.
      if (res.url.includes("/login") || html.length < 20_000) {
        throw new Error(`Looks like a login wall for ${url} (final URL ${res.url})`);
      }
      return html;
    }

    if (res.status === 429 || res.status >= 500) {
      const wait = 2 ** attempt * 5_000 + Math.random() * 2_000;
      console.warn(`HTTP ${res.status} on ${url}, retrying in ${Math.round(wait / 1000)}s`);
      await sleep(wait);
      continue;
    }
    throw new Error(`HTTP ${res.status} for ${url}`);
  }
  throw new Error(`Gave up on ${url} after ${retries + 1} attempts`);
}

The 20,000-character threshold is a heuristic, not a documented rule. A real profile page is far larger than that, while the shell you get when Meta wants you to sign in is much smaller. Tune it if you see false positives.

Step 2: Pull the embedded JSON out of the HTML

// extract.js
const SCRIPT_RE = /<script type="application\/json"[^>]*>([\s\S]*?)<\/script>/g;

export function jsonBlobs(html) {
  const blobs = [];
  for (const m of html.matchAll(SCRIPT_RE)) {
    try {
      blobs.push(JSON.parse(m[1]));
    } catch {
      // Some blobs are not valid standalone JSON; skip them.
    }
  }
  return blobs;
}

// Walk any JSON tree and collect objects that look like Threads posts.
export function findPosts(root) {
  const found = new Map();
  const stack = [root];
  while (stack.length) {
    const node = stack.pop();
    if (!node || typeof node !== "object") continue;

    if (
      typeof node.code === "string" &&
      typeof node.taken_at === "number" &&
      "like_count" in node &&
      node.user?.username
    ) {
      found.set(node.code, node);
    }
    for (const v of Array.isArray(node) ? node : Object.values(node)) {
      if (v && typeof v === "object") stack.push(v);
    }
  }
  return [...found.values()];
}

// Same idea for the profile header.
export function findProfile(root, handle) {
  const stack = [root];
  while (stack.length) {
    const node = stack.pop();
    if (!node || typeof node !== "object") continue;
    if (node.username === handle && "follower_count" in node) return node;
    for (const v of Array.isArray(node) ? node : Object.values(node)) {
      if (v && typeof v === "object") stack.push(v);
    }
  }
  return null;
}

The Map keyed by code matters: the same post often appears in more than one blob, and you don't want to count it twice. Using an explicit stack instead of recursion avoids blowing the call stack on Meta's very deep payloads.

Step 3: Normalize a post

Raw post objects carry dozens of fields you don't need. Flatten them into something you'd actually store:

// normalize.js
export function normalizePost(p) {
  const info = p.text_post_app_info ?? {};
  return {
    code: p.code,
    url: `https://www.threads.com/@${p.user.username}/post/${p.code}`,
    author: p.user.username,
    postedAt: new Date(p.taken_at * 1000).toISOString(),
    text: p.caption?.text ?? "",
    likes: p.like_count ?? null,
    replies: info.direct_reply_count ?? null,
    reposts: info.repost_count ?? null,
    quotes: info.quote_count ?? null,
    isReply: Boolean(info.is_reply),
  };
}

Two caveats. First, authors can hide like counts, so like_count may be missing or zero even on a popular post; store null rather than guessing. Second, the profile page mixes in the author's own continuation posts (a multi-part thread shows up as a post plus replies to itself). isReply lets you filter those out if you only want top-level posts.

Step 4: The threads scraper core (a profile)

// profile.js
import { fetchPage } from "./fetchPage.js";
import { jsonBlobs, findPosts, findProfile } from "./extract.js";
import { normalizePost } from "./normalize.js";

export async function scrapeProfile(handle) {
  handle = handle.replace(/^@/, "");
  const html = await fetchPage(`https://www.threads.com/@${handle}`);
  const blobs = jsonBlobs(html);

  let profile = null;
  const posts = new Map();
  for (const blob of blobs) {
    profile ??= findProfile(blob, handle);
    for (const p of findPosts(blob)) {
      if (p.user.username === handle) posts.set(p.code, normalizePost(p));
    }
  }

  return {
    handle,
    followers: profile?.follower_count ?? null,
    verified: profile?.is_verified ?? null,
    bio: profile?.biography ?? null,
    posts: [...posts.values()].sort((a, b) => b.postedAt.localeCompare(a.postedAt)),
  };
}

if (import.meta.url === `file://${process.argv[1]}`) {
  const data = await scrapeProfile(process.argv[2] ?? "zuck");
  console.log(data.followers, data.posts.length);
  console.table(data.posts.slice(0, 5).map(({ code, likes, replies, reposts }) => ({ code, likes, replies, reposts })));
}

Run it with node profile.js someuser. Expect a first page of posts, roughly what you'd see before scrolling. If you get zero posts but a valid profile, Meta has probably changed where the posts are preloaded, or this request was served a stripped page. Save the HTML to disk and search it for a post code you know exists; that tells you quickly which case you're in.

Step 5: Replies on a single post

The post permalink page works the same way. The main post plus the first batch of replies are usually in the preloaded JSON:

// post.js
import { fetchPage } from "./fetchPage.js";
import { jsonBlobs, findPosts } from "./extract.js";
import { normalizePost } from "./normalize.js";

export async function scrapePost(url) {
  const clean = url.replace("threads.net", "threads.com").split(/[?#]/)[0];
  const code = clean.match(/\/post\/([^/]+)/)?.[1];
  if (!code) throw new Error(`Not a Threads post URL: ${url}`);

  const all = new Map();
  for (const blob of jsonBlobs(await fetchPage(clean))) {
    for (const p of findPosts(blob)) all.set(p.code, normalizePost(p));
  }
  const post = all.get(code) ?? null;
  all.delete(code);
  return { post, replies: [...all.values()] };
}

"Replies" here means everything else on the page that looks like a post. On some pages that includes the parent post (if you opened a reply) or related posts. If you need strict parent/child relationships, inspect the surrounding thread_items structure in the blob rather than relying on the flat list.

Why not just call the GraphQL API?

You'll see older tutorials that POST to https://www.threads.com/api/graphql with a doc_id and an lsd token copied from the page. It can work for a while, but plan for three problems:

doc_id churn. Each query is identified by a numeric document ID that changes when Meta ships a new client build. Hard-coded IDs go stale, sometimes within weeks.
Token coupling. The lsd token and related headers are tied to the page you loaded. You end up scraping the HTML anyway just to call GraphQL.
Pagination is where login walls live. "Load more posts" and deep reply threads are exactly the calls that tend to need a session. Using a logged-in account for scraping risks that account, and it's clearly against Meta's terms.

For a no-login threads scraper, the embedded JSON is the more stable source, even though you only get the first page.

Rate limits, IP blocks, and legal notes

Meta doesn't publish limits for the public web pages. From what people commonly report, a residential IP fetching a few pages a minute is fine, while datacenter IPs get challenged or redirected to login much sooner. I'd stick to these rules:

One request every few seconds, with random jitter, and back off on 429.
Cache HTML during development so you're not hitting Threads every time you tweak a parser.
Watch for soft blocks. A 200 with a login shell is the usual symptom, not a clean 403.

On the legal side: Meta's terms prohibit automated collection without permission, and courts in different countries have treated public-data scraping differently. Only collect public data, don't collect more personal data than your use case needs, respect GDPR if you store data about EU users, and talk to a lawyer before building anything commercial. This post is a tutorial, not legal advice.

The official Threads API

Meta has an official Threads API (graph.threads.net). It's the right tool when you're working with your own account: publishing, reading your posts and their insights, managing replies. Meta has since added keyword search and some public profile lookups, but they require app review, specific permissions, and an access token tied to a Threads user, and they come with their own rate limits. Check the current docs before relying on them, because the scope has been changing.

What it won't give you is an easy "give me any public account's posts" call with no app review. That gap is why people write scrapers in the first place.

Project: a Threads engagement tracker

Now the practical bit. This script snapshots a few accounts and appends one line per post per run to snapshots.jsonl. JSON Lines keeps it dependency-free; swap in SQLite (better-sqlite3, or node:sqlite on recent Node versions) when the file gets large.

// track.js
import { appendFile } from "node:fs/promises";
import { scrapeProfile } from "./profile.js";

const HANDLES = process.argv.slice(2);
if (!HANDLES.length) {
  console.error("usage: node track.js handle1 handle2 ...");
  process.exit(1);
}
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

const runAt = new Date().toISOString();
for (const handle of HANDLES) {
  try {
    const { followers, posts } = await scrapeProfile(handle);
    const lines = posts
      .filter((p) => !p.isReply)
      .map((p) => JSON.stringify({ runAt, handle, followers, ...p }));
    if (lines.length) await appendFile("snapshots.jsonl", lines.join("\n") + "\n");
    console.log(`${handle}: ${lines.length} posts, ${followers ?? "?"} followers`);
  } catch (err) {
    console.error(`${handle}: ${err.message}`);
  }
  await sleep(4_000 + Math.random() * 3_000);
}

Schedule it with cron every few hours:

0 */4 * * * cd /path/to/threads-scraper && /usr/bin/node track.js handle1 handle2 >> track.log 2>&1

And a report that compares each post's first and latest snapshot:

// report.js
import { readFile } from "node:fs/promises";

const rows = (await readFile("snapshots.jsonl", "utf8"))
  .split("\n")
  .filter(Boolean)
  .map((l) => JSON.parse(l));

const byPost = new Map();
for (const r of rows) {
  const s = byPost.get(r.code) ?? { first: r, last: r };
  if (r.runAt < s.first.runAt) s.first = r;
  if (r.runAt > s.last.runAt) s.last = r;
  byPost.set(r.code, s);
}

const delta = (a, b) => (a == null || b == null ? null : b - a);
const report = [...byPost.values()]
  .map(({ first, last }) => ({
    post: last.url,
    snapshots: `${first.runAt.slice(0, 16)} -> ${last.runAt.slice(0, 16)}`,
    likes: last.likes,
    likeGain: delta(first.likes, last.likes),
    replyGain: delta(first.replies, last.replies),
    repostGain: delta(first.reposts, last.reposts),
  }))
  .sort((a, b) => (b.likeGain ?? -1) - (a.likeGain ?? -1));

console.table(report.slice(0, 15));

One thing to keep in mind when reading this report: because you only see the first page of posts, older posts drop out of the snapshots once newer ones push them off. A post that stops appearing hasn't stopped growing; you just can't see it anymore. If you need to keep following specific posts, feed their URLs through scrapePost() on each run instead.

The managed alternative

If maintaining the parser becomes a chore, or you need more than the first page from datacenter IPs, ScrapeAtlas* has Threads endpoints that return the same post objects (like_count, taken_at, text_post_app_info.direct_reply_count, and so on). Authentication is an x-api-key header:

const atlas = (path, params) =>
  fetch(`https://api.scrapeatlas.com/v1/threads/${path}?${new URLSearchParams(params)}`, {
    headers: { "x-api-key": process.env.SCRAPEATLAS_API_KEY },
  }).then((r) => r.json());

const profile = await atlas("profile", { handle: "zuck" });
console.log(profile.username, profile.follower_count, profile.is_verified);

const feed = await atlas("user/posts", { handle: "zuck", since: "2026-10-01" });
console.log(feed.posts.map((p) => [p.url, p.like_count, p.text_post_app_info.direct_reply_count]));
console.log(feed.coverage); // e.g. { complete: false, warnings: ["posts_first_page_only"], ... }

const thread = await atlas("post", { url: "https://www.threads.com/@zuck/post/<code>" });
console.log(thread.post.like_count, thread.comments.length);

To be clear about the limits: user/posts is also first page only, which the response tells you in coverage.warnings, so the tracker's blind spot is the same. post takes include_comments=false if you only want the post, and every endpoint accepts trim=true for a compact projection. There are also user/replies, post/comments, search (keyword search with recent, start_date, and end_date), search/users, and search/tags. Search is the part you can't do logged-out on your own.

Wrapping up

Read the preloaded JSON, not the DOM. Walk every application/json script and match on post shape, not a fixed path.
Dedupe by code and normalize threads.net to threads.com.
Expect the first page only without logging in, and design your tracker around that.
Skip GraphQL doc_id calls unless you're ready to re-capture them every time Meta ships a new build.
Go slow and cache, and treat a small 200 response as a block.
For your own account, use the official Threads API.

If the extractor stops finding posts for you, leave a comment with what the page source looks like now and I'll update the post.

*I build it.

Stop Battling JavaScript Date Bugs: A Complete Guide to the Temporal API

Wed, 21 Oct 2026 08:53:20 +0000

Stop Battling JavaScript Date Bugs: A Complete Guide to the Temporal API

The Temporal API is a modern, built-in JavaScript solution designed to overhaul and replace the legacy Date object. It introduces a comprehensive suite of distinct, immutable objects for managing dates, times, durations, and time zones with exact precision. By cleanly separating wall-clock times from global timestamps, Temporal eliminates decades of common date-handling pitfalls in web applications.

The Analogy: Mechanical Wall Clocks vs. Modern Atomic Smartwatches

To understand why we need the Temporal API, picture a traditional mechanical wall clock hanging in a busy train station. If you manually turn the clock's minute hand forward to adjust for a delay, the internal gears might accidentally shift the hour hand, slip off track, or completely lose alignment with the sun outside. Worse yet, if two people try to adjust the clock at the same time, the clock's physical state gets corrupted.

This is how JavaScript's legacy Date object operates: it is mutable (meaning its value can be modified after creation) and constantly tries to guess your local time zone behind the scenes.

The Temporal API, on the other hand, acts like a synchronized atomic smartwatch network. When you want to see what time it will be in three hours, the smartwatch does not alter your current time display. Instead, it generates a brand-new, unchangeable reading specifically for that future moment. It keeps local time, calendar dates, and exact global timestamps in separate, dedicated digital registers, ensuring that adjusting one setting never corrupts another.

Why It Matters in Daily Web Development

Every day, software engineers write code that schedules notifications, processes monthly recurring subscriptions, or logs critical system events. Using traditional JavaScript Date handling, these operations frequently trigger subtle, costly bugs in production systems:

Accidental Mutations: Passing a standard date object into a utility function might accidentally alter the original date variable elsewhere in your codebase.
Time Zone Confusions: A traditional date object automatically converts timestamps based on the local machine's system settings. This causes a server running in UTC (Coordinated Universal Time, the primary time standard by which the world regulates clocks) to interpret a user's midnight entry as 4:00 PM the previous day.
Daylight Saving Time (DST) Distortions: Calculating 24 hours from a given moment during a DST transition can result in events firing an hour early or late.

The Temporal API solves these daily problems by enforcing immutability and introducing specific types like Temporal.PlainDate (for calendar dates without times) and Temporal.ZonedDateTime (for exact moments anchored to a specific geographic region).

Code Example: Node.js Date Calculations

Below is a comparison showing how legacy Node.js date handling leads to unwanted side effects compared to the clean, safe approach provided by the Temporal API.

// Legacy JavaScript Date Approach (Prone to bugs)
const eventDate = new Date('2025-05-01T10:00:00Z');

// We want to calculate a follow-up date 7 days later
const followUpDate = eventDate;
followUpDate.setDate(eventDate.getDate() + 7);

// BUG: Mutating followUpDate unexpectedly altered eventDate too!
console.log(eventDate.toISOString()); // Output: 2025-05-08T10:00:00.000Z


// Modern Temporal API Approach (Safe and Predictable)
// Note: Temporal is available in modern JS runtimes or via the @js-temporal/polyfill package
const { Temporal } = require('@js-temporal/polyfill');

// Create an exact zonal date-time for an event in Tokyo
const originalEvent = Temporal.ZonedDateTime.from({
  timeZone: 'Asia/Tokyo',
  year: 2025,
  month: 5,
  day: 1,
  hour: 10,
  minute: 0
});

// Add 7 days cleanly without modifying the original object
const reminderEvent = originalEvent.add({ days: 7 });

// The original object remains entirely untouched
console.log(originalEvent.toString()); // 2025-05-01T10:00:00+09:00[Asia/Tokyo]
console.log(reminderEvent.toString());  // 2025-05-08T10:00:00+09:00[Asia/Tokyo]

Key Takeaway

Transitioning to the Temporal API shifts date manipulation from a fragile, error-prone chore into a robust, type-safe development experience. By cleanly isolating distinct concepts like calendar dates, wall-clock times, and regional time zones into immutable objects, Temporal guarantees that your application processes time consistently across every server and browser on the planet.

Enjoyed this breakdown? Support my open-source work on Buy Me a Coffee or explore react-hook-lab!

Originally published on my blog. You can read the alternative breakdown here.

Mastering the Critical Path in Performance Budgets for Faster React Apps

Tue, 20 Oct 2026 09:05:05 +0000

What is the Critical Path in Performance Budgets?

A performance budget is a set of strict limits agreed upon by a web development team to cap resource sizes, file counts, or loading speeds. The critical path—often called the Critical Rendering Path—is the exact sequence of assets and browser processing steps required to render the initial visible portion of a webpage. Combining these two concepts means setting explicit size and time limits specifically for the code and assets that block the initial page display.

The Airport Fast Track Analogy

Imagine walking through an airport terminal to board a flight. To get through the boarding gate, you only need two essential items in your hand: your passport and your boarding pass. These two items represent your critical path.

If you try to haul three oversized suitcases, two heavy coats, and a duty-free shopping bag through the gate check all at once, you will slow down the entire line. A critical path performance budget is like an airport rule stating that passengers can only hold their passport and ticket while stepping up to the gate. Everything else—your checked luggage and heavy items—must be handled separately so you can pass through instantly.

Why it Matters in Daily Software Engineering

In modern web development, teams often bundle massive amounts of JavaScript and CSS together. When a user opens an application, the browser must download, parse, and execute all of this code before showing a single pixel of the user interface.

If software engineers do not restrict what travels down the critical path, the browser gets clogged with non-essential files—such as analytics scripts, chat widgets, or secondary modal dialogues. By defining a strict performance budget for the critical path, engineers guarantee that the essential visual structure loads within milliseconds, keeping users engaged and preventing high bounce rates on mobile networks.

Practical Code Example: React Code Splitting

To keep our critical path budget light, we should dynamically import non-essential React components so they do not block the main render. Here is how you can defer non-critical widgets using React.lazy and Suspense in a React application:

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

// Critical component: Loaded immediately for the initial render
import Header from './Header';
import MainContent from './MainContent';

// Non-critical component: Loaded on-demand outside the critical path
const HeavyAnalyticsDashboard = lazy(() => import('./HeavyAnalyticsDashboard'));

function App() {
  return (
    <div className="app-container">
      {/* Essential components render without delay */}
      <Header />
      <MainContent />

      {/* Non-critical component is deferred with a lightweight fallback */}
      <Suspense fallback={<div>Loading analytics...</div>}>
        <HeavyAnalyticsDashboard />
      </Suspense>
    </div>
  );
}

export default App;

By splitting the bundle, HeavyAnalyticsDashboard is pulled out of the critical rendering budget, ensuring the Header and MainContent display almost instantaneously.

Key Takeaway

Managing your critical path within a performance budget is not about stripping away feature-rich functionality; it is about controlling when those features are delivered. By keeping your initial rendering pipeline lean and pushing non-essential scripts into secondary loading phases, you preserve ultra-fast initial page loads without sacrificing modern application capabilities.

Enjoyed this breakdown? Support my open-source work on Buy Me a Coffee or explore react-hook-lab!

Originally published on my blog. You can read the alternative breakdown here.

AION 2 Pets

Tue, 20 Oct 2026 04:54:15 +0000

I maintain AION 2 Pets, a small independent web companion for players who want to plan pet collection without connecting a game account. It combines 206 pet records with recorded locations for 157 pets across three regional maps. The useful distinction is between finding a recorded location, budgeting upgrade resources and keeping a collection record. Map markers do not establish drop rates or farming time.

The checklist uses manual browser-local state and supports JSON backup and validated merge import. That keeps the interaction simple, while making the limits visible: clearing site storage or switching devices requires a backup rather than an assumption of cloud synchronization. Pet soul requirements, collection EXP and analysis costs are shown separately.

The project uses JavaScript and a static site deployment on Cloudflare Workers. Source notes and coverage limits are included, and the site does not automate gameplay or read a player account. This is an independent fan tool, not an NCSOFT product.

Explore the pet atlas and planning tools.

Your TypeScript Is Lying to You, and These 5 Places Hide Real Bugs

Mon, 19 Oct 2026 12:30:35 +0000

TypeScript's most dangerous keyword is two letters long.

as does not convert anything. It does not check anything. It tells the compiler "trust me", and the compiler does. If you are wrong, the error moves from your editor to your users.

Here are five places I keep finding it in real codebases, each one compiling cleanly and each one a crash waiting for the right input.

1. Casting an API Response

const res = await fetch('/api/users/1');
const user = (await res.json()) as User;

console.log(user.profile.avatarUrl);

res.json() returns Promise<any>. Casting any to User is the compiler equivalent of a handshake agreement. If the backend renames a field, makes profile optional, or returns an error object with a 200 status, this line still compiles and the crash happens three functions later with a message that has nothing to do with the cause.

What to write instead: validate the data at the boundary.

import { z } from 'zod';

const UserSchema = z.object({
  id: z.string(),
  email: z.string().email(),
  profile: z.object({ avatarUrl: z.string().url().nullable() }),
});

type User = z.infer<typeof UserSchema>;

const user = UserSchema.parse(await res.json());

Now the type is derived from a check that actually ran. If the shape is wrong, you get a clear error at the exact line where bad data entered your app.

2. The Non-Null Assertion on Environment Variables

const client = new MongoClient(process.env.DATABASE_URL!);

process.env.X is typed string | undefined, which is honest. The ! deletes the undefined from the type and nothing else. When the variable is missing in a new environment, you get a confusing failure from deep inside a library instead of "DATABASE_URL is missing".

function requireEnv(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing environment variable: ${name}`);
  return value;
}

const client = new MongoClient(requireEnv('DATABASE_URL'));

The app now fails at startup, with the variable name in the message. That is the cheapest place to find out.

3. The Non-Null Assertion on `find()`

const user = users.find((u) => u.id === id)!;
sendEmail(user.email);

find returns undefined when nothing matches, and "nothing matches" is exactly the case your tests forgot. The ! makes the compiler stop warning you about the one scenario worth warning about.

const user = users.find((u) => u.id === id);
if (!user) throw new Error(`User ${id} not found`);

sendEmail(user.email);

After the check, TypeScript narrows user to a real object on its own. No assertion required.

4. Casting Object.keys

type Settings = { theme: string; lang: string };

function logSettings(s: Settings) {
  (Object.keys(s) as (keyof Settings)[]).forEach((k) => {
    console.log(s[k].toUpperCase());
  });
}

const fromApi = { theme: 'dark', lang: 'en', retries: 3 };
logSettings(fromApi);

This compiles. TypeScript types are structural, so an object with extra properties is still a valid Settings when it arrives through a variable. Object.keys returns plain string[] for exactly this reason, and the cast to keyof Settings overrides that protection. At runtime retries is a number, and toUpperCase is not a function.

const SETTING_KEYS = ['theme', 'lang'] as const;

function logSettings(s: Settings) {
  SETTING_KEYS.forEach((k) => console.log(s[k].toUpperCase()));
}

Iterate over a list of keys you control, not over whatever the object happens to contain.

5. Casting the Caught Error

try {
  await saveProfile(data);
} catch (e) {
  toast((e as Error).message);
}

In JavaScript you can throw anything: a string, a number, undefined, a plain object. Libraries do it. With strict on, TypeScript types e as unknown to keep you honest, and as Error is the line that undoes it. If something throws a string, .message is undefined and your toast says "undefined".

catch (e) {
  const message = e instanceof Error ? e.message : 'Something went wrong';
  toast(message);
}

A Bonus Lie That Lives in Your Config

const items: Item[] = [];
const first = items[0];
first.name; // typed as Item, crashes at runtime

Array index access is typed as Item, not Item | undefined, because the compiler cannot know the length. One line in tsconfig.json fixes it:

{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true
  }
}

This flag is not part of strict, so most projects never turn it on. It adds a few extra checks, and every one of them is a real case where the array could have been empty.

The Rule

A cast is a promise you make to the compiler that it cannot verify. Data from outside your program needs a runtime check, not a type assertion.

An easy audit: search your project for as and for !. and !;. For each hit, ask what happens when the assumption is false. Casts on your own literals are usually fine. Casts on network responses, environment variables, search results and caught errors are where the bugs live.

I keep these checks in the shared lib/ folder of the TypeScript-first templates on pixelanas.com, so a missing environment variable or a changed API shape fails loudly on the first request instead of silently in production.

Get the templates: https://pixelanas.gumroad.com

How many as casts does your project have, and how many of them are on data you do not control? Drop your count in the comments.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

I built a background remover that never sees your photo (and it does GIFs and videos too)!

Sun, 18 Oct 2026 14:58:30 +0000

When you’re the only engineer in the family, you automatically become the unpaid IT department, video producer, and resident graphic designer, because to relatives, "computers" is just one big subject (and that includes everything to do with mobile phones too... somehow!). So whenever someone needed a transparent PNG or a quick cutout, it fell on me, and I’d get stuck in the same annoying loop. I'd hunt down a "free" background remover (whatever showed up first on Google), upload the photo, wait, and then get held hostage by a "Buy Credits" button. My only options were settling for a blurry, postage-stamp-sized preview, or making a whole new account if I was desperate enough for the high-res version. Worse, somewhere in that mess, a family photo would get shipped off to a sketchy server I know nothing about.

For a product shot, that's annoying. For a passport photo, a signature, or a client's photo, it's a bit more than annoying.

So I added a background remover to Fizzdoc, my open-source toolkit where every tool runs inside the browser tab. It now does:

Photos: Remove Background, saved at the photo's own resolution as PNG, JPG or WebP.
Animated GIFs: Remove GIF Background, every frame, same timing, same loop.
Videos: Remove Video Background, every frame, with the sound kept.
WhatsApp stickers: WhatsApp Sticker Maker, a 512 × 512 WebP with a white outline, kept under 100 KB, with words in fun fonts and emoji you drag into place.

You can keep the background clear, or put white, any colour, a blur or another photo behind. It's free, there's no sign-up, no watermark, and no limit on how many photos you do. The size limit comes from your device's memory, not from me.

And the photo never leaves your device. Not "we delete it after an hour". It just never goes anywhere.

Below is how it works, and what broke along the way.

The rule: nothing gets uploaded, and you can check

Fizzdoc is a static site on Cloudflare Pages. There's no backend, so there's nothing that could receive a file. The page also ships a Content Security Policy with connect-src 'self', which means the browser itself blocks the page from talking to any other website.

That rule shaped everything below. No CDN for the model, no hosted inference API, no "just this one request". Open DevTools, go to the Network tab, remove the background, and you'll see the model files coming from fizzdoc.com and nothing going out.

Picking a model

I wanted three things:

Good edges on hair and fur, because that's where background removers usually show their seams.
Small enough to download once into a browser.
A licence that lets anyone use the result, including for work.

I went with BiRefNet (MIT licence), the lite variant, using the 512 × 512 ONNX export by studioludens. I store its big weight tensors as 16-bit floats and cast them back to 32-bit when the model loads, which halves the download to about 100 MB without changing the maths it runs.

For phones there's a second model, U²-Net small (Apache-2.0), just 4.6 MB. I learned this one the hard way: someone sent me a screenshot of an early version on a 6 GB Android phone, where Chrome killed the tab at 5% ("Aw, Snap!"). A browser tab on a phone gets far less memory than the phone has, and when it runs out there's no error to catch, the tab just dies. So now phones always use the small model, and the page says so ("for the cleanest edges on hair and fur, use a laptop"). If the big model ever crashes a tab on a laptop too, the page remembers it for 30 days and uses the small one there.

And for laptops with a graphics chip there's the opposite: a Sharper edges (hair, fur) button. It reruns the photo through a 1024 × 1024 export of the same BiRefNet-lite model (onnx-community, MIT). It's a one-time 135 MB download and needs WebGPU, so it's never offered on phones. If the device can't manage it, you keep the result you already had.

Running it: WebGPU when it can, CPU when it can't

The model runs with ONNX Runtime Web inside a Web Worker, so the page never freezes.

If the device has a graphics chip with WebGPU, the model runs there. This is the fast path.
If WebGPU isn't there (or the driver says no), the same model runs on the CPU through WebAssembly.
If that fails too, usually because the device ran out of memory, the small U²-Net model takes over.

So the chain is GPU, then the same model on CPU, then the small model. Nobody gets an error just because their laptop is old.

Two fun problems with "self-host everything"

Cloudflare Pages has a 25 MiB limit per file. The model is about 100 MB and ONNX Runtime's WebGPU build is a 27 MB .wasm. So both live on the server as 20 MiB parts: the models are split by a small script when I add them, and the runtime is split at build time. The worker downloads the parts, joins them, and keeps the result in the browser's Cache Storage, so the next time it starts straight from there, even with the internet off. The build also fails if any file it writes goes over 25 MiB, after one deploy failed on it.

A runtime that exists in pieces. ONNX Runtime normally fetches its .wasm as one file. Mine exists just as parts on the server, so the worker joins them from Cache Storage and hands the bytes to the runtime directly with ort.env.wasm.wasmBinary. It needs no extra hosting and no change to the security policy.

The part I'm proudest of: full resolution from a 512 px model

The model looks at your photo squeezed to 512 × 512 and returns a soft mask. If you stretch that mask back over a 4000 × 3000 photo, the edges look like they were cut with a butter knife.

So the mask goes through two classic image-processing filters, both plain arithmetic on typed arrays in the worker:

Fast guided filter (He and Sun, 2015). It uses the photo itself as a guide to snap the blurry mask onto the real edges, so hair follows the actual strands. The fit is computed on a smaller copy (up to 1280 px) and then applied to every pixel of the full photo in one pass.
Blur-fusion foreground estimation (Forte, 2021). Edge pixels are a mix of your subject and the old background. Put a cut-out on a new colour without fixing that, and you get a faint halo of the old background. This step estimates the subject's true colour at the edges, so the new background looks like it was always there.

By default the result is saved at your photo's own size: your own pixels, with a cleaner mask.

When the AI gets it almost right

It's an AI model, so a busy background or a subject that blends into it can confuse it. For photos there's a small set of touch-ups:

Erase / Restore brush, with Undo, Redo and Zoom for careful work on a phone.
Tap to remove and Tap to keep: one tap picks the whole connected area of a similar colour and removes it, or brings it back.
Shadow and a white Outline, if you want the cut-out to stand out.
Crop: the whole photo, fit to the subject, or a square around the subject for online shop listings.
Hold to see the original, to compare before and after.

GIFs: every frame, same rhythm

Animated GIFs are sneaky. Many frames aren't full pictures, just small patches drawn over the previous frame, with rules ("disposal methods") about what to clear afterwards.

gifuct-js (MIT) decodes the frames, and Fizzdoc composes each one into a full picture the way a browser would show it.
Each frame goes through the same model (in a faster mode, since there can be dozens).
gifenc (MIT) writes the new GIF, keeping every frame's delay and the loop.

One catch: a GIF pixel is either fully see-through or fully solid. So on a clear background the edges are a little sharper than in a PNG. Pick a colour or a photo behind and the soft edges are back.

Videos: every frame, sound kept

For video, Mediabunny (MPL-2.0) reads the file and the browser's own WebCodecs encoder writes the new one. Every frame goes through the model and gets its new background, and the soundtrack is carried over.

The output is MP4 (H.264) if the browser can handle it; otherwise, it's WebM (VP9). Before you start, the page shows a preview frame and an estimate of how long the whole clip will take on that device.

What does "no background" mean for a video? Truly see-through video would need the encoder library to start helper workers from blob: URLs, which my page's security policy blocks, and most players can't show it anyway. So "None" gives you a green screen, which any video editor removes in one click. I chose to keep the policy strict rather than loosen it for one feature.

Stickers: words, emoji, and the last step in WhatsApp

The WhatsApp Sticker Maker starts from the same cut-out. It squares it to 512 × 512, adds a white outline, and keeps the WebP under 100 KB by lowering the quality step by step until it fits.

On top of that, you can add words in five styles (Funny, Cute, Cozy, BIG, and Serious) and emojis. Each one is a layer you drag, pinch, resize and rotate, on a phone or with a mouse. The fonts are self-hosted like everything else: Bangers, Kalam, Teko and Inter, with Baloo 2 covering Hindi letters. Emoji are drawn with your device's own emoji font.

One fun bug on the way: Vite inlines small files as data: URLs, and a few of the font files were small enough. My own CSP (default-src 'self') refused them, and the end-to-end test that fails on any CSP violation caught it before it shipped. Fonts are now always separate files.

One limit, though. A web page can't add a sticker to WhatsApp, and a sticker shared from the browser arrives as a normal photo. So instead of a "Share to WhatsApp" button that doesn't do what it says, the page shows WhatsApp's own steps: save the sticker, then in any chat tap Stickers › Create and pick it. On iPhone there's a "Save to Photos" button, because downloads go to Files and WhatsApp picks stickers from Photos.

What it's like on low-end phones

I care about this a lot because many people open Fizzdoc on Android phones.

Phones always get the small model, so it works rather than crashes. Edges are a bit softer than on a laptop, which is a trade I'll take every time.
The worker keeps the page responsive while it thinks.
The model downloads once (the page shows the progress in MB). After that it starts right away, and it keeps working with Wi-Fi and mobile data off, which is also the easiest way to check that nothing is uploaded.
Videos give you a time estimate first: short clips are fine, long ones are a laptop job.

Things it doesn't do (yet)

Truly transparent video (see above, green screen instead).
Many photos in one go: the background remover takes one photo at a time.
Several photos in one sticker. That's next.

Credits

None of this would exist without these people and projects. Thank you:

Project	What it does in Fizzdoc	Licence
BiRefNet by Peng Zheng and co-authors	The background model	MIT
birefnet-lite-512 by studioludens	The 512 px ONNX export	MIT
BiRefNet_lite-ONNX by onnx-community	The 1024 px export for Sharper edges	MIT
U²-Net by Xuebin Qin and co-authors	The small model for phones	Apache-2.0
ONNX Runtime Web by Microsoft	Runs the models on WebGPU or WebAssembly	MIT
gifuct-js by Matt Way	Reads animated GIFs	MIT
gifenc by Matt DesLauriers	Writes animated GIFs	MIT
Mediabunny by Vanilagy	Reads and writes videos	MPL-2.0
Kaiming He and Jian Sun	The (fast) guided filter	Paper
Marco Forte	Blur-fusion foreground estimation	Paper

The full licence texts are in Fizzdoc's third-party licences.

Try it, break it, tell me

Photo: https://fizzdoc.com/remove-background/
GIF: https://fizzdoc.com/remove-gif-background/
Video: https://fizzdoc.com/remove-video-background/
WhatsApp sticker: https://fizzdoc.com/whatsapp-sticker-maker/
Code (Apache-2.0): https://github.com/kingrishabdugar/fizzdoc

It's part of a bigger toolkit of 68 free tools (PDF, Word, Excel, PowerPoint, images and audio), all running in your browser, in 16 languages. If something looks off on your device, there's a "Report it" link on every tool. And if you like it, a star on GitHub genuinely makes my day.

Lossless vs Lossy Compression: The Core Difference Explained

Sun, 18 Oct 2026 11:31:34 +0000

The Essence of Compression: Expressing the Same Information with Less Data

Before diving into the distinction between lossless and lossy compression, we need to understand what compression actually does.

At its core, compression is about expressing the same information with less data. Any piece of data—whether text, images, audio, or video—contains "redundancy." Redundancy refers to parts that can be removed without losing the meaning of the information. A compression algorithm's job is to identify and eliminate this redundancy.

Consider a simple example. The character string AAAAABBBCC occupies 10 bytes. But we can represent the same information more compactly by recording "each character and how many times it repeats consecutively," yielding 5A3B2C—only 6 bytes. The data size drops by 40%, yet the meaning is identical. This is the most primitive form of compression, known as Run-Length Encoding (RLE).

From an information theory perspective, Claude Shannon introduced the concept of "information entropy": the minimum average encoding length of a data stream is bounded by its entropy. No lossless algorithm can break this theoretical limit. This means that re-compressing already-compressed data yields almost no benefit—the redundancy has already been stripped away.

Understanding this essence reveals two fundamentally different technical paths: lossless compression strives for perfect fidelity, while lossy compression deliberately discards details that the human eye or ear cannot easily perceive, trading them for a much higher compression ratio.

Lossless Compression: Restoring Every Bit

The core promise of lossless compression is that the decompressed data is byte-for-byte identical to the original—not a single bit may differ. These algorithms eliminate only "statistical redundancy" and "structural redundancy," never touching the semantic content of the information.

DEFLATE: The Most Widely Used Lossless Algorithm

DEFLATE is the algorithm underlying ZIP, gzip, zlib, and many other tools. It elegantly combines two classic techniques:

LZ77: Uses a sliding window to search for repeated substrings in already-processed data, replacing them with "distance + length" pointers. For example, the word "compression" appearing repeatedly in a text file can be replaced with a back-reference to its first occurrence.
Huffman coding: Applies variable-length encoding to the symbol stream produced by LZ77. Frequently occurring symbols get short codes; rare symbols get long codes. This pushes the encoding closer to the entropy limit.

DEFLATE's strengths are its simplicity, speed, and universal compatibility—nearly every programming language's standard library includes an implementation.

LZMA: Higher Ratios Through Context Modeling

LZMA (Lempel-Ziv-Markov chain Algorithm) builds on LZ77 with a much larger sliding window (up to several GB), a more refined probability model, and range coding. Compared to DEFLATE, LZMA typically achieves higher compression ratios, at the cost of slower compression speed and greater memory usage. The 7z format is based on LZMA.

The key improvement in LZMA is that it does not rely on a static probability table. Instead, it dynamically predicts the probability of the next symbol based on context. This "context modeling" brings the encoding much closer to the theoretical entropy limit.

PNG Filtering: Preprocessing for Image Data

PNG is a lossless image format, but it does not apply DEFLATE directly to raw pixel values. Before compression, PNG applies a "filter" to each row of pixels to make the data more amenable to DEFLATE.

A common filter stores the difference between each pixel and its neighbor to the left, above, or upper-left. Since natural images have locally similar pixels, these differences tend to cluster around zero. This transformed data has higher redundancy, allowing DEFLATE to compress it far more effectively.

This also explains why ZIP cannot effectively compress JPEG images: JPEG is already highly compressed through DCT and entropy coding, leaving almost no statistical redundancy for DEFLATE to exploit. Running ZIP on a JPEG typically adds a few bytes of header overhead with no size reduction.

Lossy Compression: Trading Below the Perception Threshold

The central idea of lossy compression is that human perception has limits. If the discarded details fall below the perceptual threshold, the visual or auditory difference is negligible—but the data reduction can be enormous.

DCT: The Mathematical Foundation of JPEG

The Discrete Cosine Transform (DCT) is the heart of JPEG image compression. Its role is to convert an image from the "spatial domain" to the "frequency domain."

In the spatial domain, an image is represented by pixel brightness values. In the frequency domain, the image is decomposed into a sum of cosine wave components at different frequencies: low-frequency components represent large smooth areas, while high-frequency components represent edges and fine detail.

The DCT itself is reversible and loses no information. The actual "loss" happens in the next step—quantization.

Quantization: The Source of Loss

Quantization maps high-precision DCT coefficients to a limited set of discrete values. In practice, each coefficient is divided by a value from a quantization table and then rounded to an integer. Because the human eye is less sensitive to high-frequency detail, the quantization table applies larger divisors to high-frequency coefficients, causing many of them to become zero.

This step causes irreversible information loss—once a coefficient is rounded to zero, it cannot be recovered. But it also creates massive compression opportunity: long runs of zeros can be encoded very efficiently with run-length encoding.

Designing the quantization table is an art: larger divisors yield higher compression but more visible quality loss. This is exactly what the JPEG quality parameter (e.g., quality=80) controls—it scales the quantization table up or down.

Inter-Frame Prediction: The Key to Video Compression

Video compression goes a step beyond still images. Consecutive frames in a video often change very little (for example, a static background with a moving person), so there is no need to store every frame in full.

Inter-frame prediction uses "motion estimation" to find the displacement between the current frame and a reference frame, storing only "motion vectors" and "residuals." This elimination of temporal redundancy allows video compression ratios to reach hundreds or even thousands to one—far beyond what single-frame image compression can achieve.

Lossless vs Lossy: Comparison Diagram

The flowchart below illustrates the core branches and typical applications of the two compression families:

DCT Principle Diagram

The diagram below simplifies how DCT transforms an 8x8 pixel block from the spatial domain to the frequency domain, then preserves low frequencies while discarding high frequencies through quantization:

Code Examples

Lossless Compression with zlib

import zlib

# Original text data with heavy repetition
original = b"compression compression compression " * 50

# Compress
compressed = zlib.compress(original, level=9)
print(f"Original size: {len(original)} bytes")
print(f"Compressed size: {len(compressed)} bytes")
print(f"Ratio: {len(original) / len(compressed):.2f}x")

# Decompress and verify the data is identical
decompressed = zlib.decompress(compressed)
assert decompressed == original, "Data mismatch!"
print("Verification passed: decompressed data is identical to original")

Running this code, you will typically see a compression ratio above 10x, and the decompressed data is byte-for-byte identical to the original. This is what "lossless" means.

Lossy Compression with PIL

from PIL import Image
import io

# Create a test image rich in high-frequency detail
img = Image.new("RGB", (512, 512))
pixels = img.load()
for x in range(512):
    for y in range(512):
        # Generate a pattern with high-frequency detail
        pixels[x, y] = ((x * 7) % 256, (y * 5) % 256, ((x + y) * 3) % 256)

# Save as lossless PNG
img.save("test_lossless.png")
png_size = len(open("test_lossless.png", "rb").read())
print(f"PNG (lossless) size: {png_size} bytes")

# Save as lossy JPEG with quality 20 to amplify the effect
buffer = io.BytesIO()
img.save(buffer, format="JPEG", quality=20)
jpeg_size = buffer.tell()
print(f"JPEG (lossy) size: {jpeg_size} bytes")
print(f"Ratio: {png_size / jpeg_size:.2f}x")

# Reload the JPEG and compare pixel differences
buffer.seek(0)
img_jpeg = Image.open(buffer)
diff_count = sum(
    1 for x in range(512) for y in range(512)
    if img.getpixel((x, y)) != img_jpeg.getpixel((x, y))
)
print(f"Pixels that changed: {diff_count} / {512 * 512}")
print("Conclusion: JPEG compression alters pixel values irreversibly")

This code demonstrates the hallmark of lossy compression: a smaller file, but with pixel values changed irreversibly.

Comparison Table

Dimension	Lossless Compression	Lossy Compression
Core Principle	Eliminates statistical & structural redundancy	Discards info below perception threshold
Fidelity	100% reversible, identical after decompression	Irreversible, unrecoverable loss
Typical Algorithms	DEFLATE, LZMA, Brotli, Zstandard	DCT+quantization, wavelet, MDCT
Key Techniques	LZ77, Huffman coding, range coding	Transform coding, quantization, prediction
Typical Applications	ZIP, GZIP, 7Z, PNG, FLAC	JPEG, WebP, H.264, MP3, AAC
Best Suited For	Text, source code, archives, medical imaging	Photos, video, music, streaming
Typical Ratio	Usually 2x to 5x	Usually 10x to 100x or higher
Not Suitable For	Already-compressed data (e.g., JPEG files)	Data requiring exact reproduction (e.g., legal text)

FAQ

Q1: Why can't ZIP compress a JPEG image?

By the time a JPEG is created, it has already gone through DCT, quantization, and entropy coding. The statistical redundancy in the data has been almost entirely eliminated. DEFLATE cannot find exploitable repetition patterns, so running ZIP on a JPEG not only fails to reduce the size but may actually add a few bytes of header overhead.

Q2: Is PNG always larger than JPEG for the same image?

Not necessarily. For images with large areas of solid color or a limited palette (such as logos, icons, or screenshots), PNG's filter-plus-DEFLATE combination is often smaller than JPEG and preserves perfect quality. But for color-rich natural photographs, JPEG's DCT-plus-quantization typically achieves compression ratios above 10x, making it far smaller than PNG.

Q3: Can you repeatedly compress the same file with a lossless algorithm?

No. Each pass of lossless compression pushes the data closer to its entropy limit. After the first pass, redundancy is largely gone, and a second pass has almost nothing left to exploit—it may even grow slightly due to added metadata. This is why "compressing an already-compressed file" is futile.

Summary

Lossless and lossy compression are not opposing camps but optimal choices made for different information characteristics:

Lossless compression serves data where "not a single bit can be wrong"—text, code, archives. It uses techniques like LZ77 and Huffman coding to eliminate statistical redundancy while guaranteeing perfect reconstruction.
Lossy compression serves details "the eye and ear cannot perceive"—photos, video, music. It uses DCT, quantization, and inter-frame prediction to make trade-offs below the perception threshold, exchanging controlled information loss for order-of-magnitude improvements in compression ratio.

Understanding the fundamental difference between these two paths is the cornerstone of mastering all compression technology. In subsequent articles, we will dive into the specific algorithm implementations along each path, understanding the elegance of compression line by line.

Build a Search Box That Won’t Show Stale Results

Sun, 18 Oct 2026 10:08:35 +0000

A search box can display the wrong answer even when every request succeeds.

Imagine someone types cat, pauses long enough to trigger a request, then adds an s. The request for cats finishes first. A moment later, the older cat request finishes and replaces the results. The input says one thing; the page answers something else.

A reliable implementation needs a clear rule: only work associated with the latest input may change the search UI. That rule must cover results, errors, and loading indicators.

Here, “stale” means belonging to an older input. Data freshness inside your backend or cache is a separate concern.

A. Give each mechanism one job

Three pieces work together:

Debouncing delays starting a request while the user keeps typing.
Cancellation stops an obsolete fetch when possible.
A version guard decides whether completed work still owns the UI.

Debouncing alone leaves previously started requests running. Cancellation helps with those requests, but a version guard makes the UI rule explicit, including for future asynchronous work that does not support cancellation.

The subtle detail is when to advance the version: immediately when input changes. If you wait until the next request starts, an old response can still render during the debounce interval.

B. Start with a small page and an explicit response shape

<label for="query">Search articles</label>
<input id="query" type="search" autocomplete="off">
<p id="status" role="status">Type to search.</p>
<ul id="results" aria-busy="false"></ul>
<script src="search.js" defer></script>

The example expects a same-origin endpoint, /api/search?q=..., that returns JSON like this:

{"items": [{"title": "Understanding browser requests"}]}

That endpoint is an application dependency; the browser code does not implement it. An empty search response should be {"items": []}. This example treats a missing or malformed body as an error.

C. Invalidate first, then schedule

Put this first part in search.js:

const input = document.querySelector("#query");
const status = document.querySelector("#status");
const results = document.querySelector("#results");

let version = 0;
let timer;
let activeController;

function scheduleSearch() {
  const mine = ++version;
  clearTimeout(timer);
  activeController?.abort();
  activeController = undefined;

  const query = input.value.trim();
  results.replaceChildren();
  results.setAttribute("aria-busy", "false");

  if (!query) {
    status.textContent = "Type to search.";
    return;
  }

  status.textContent = "Waiting for you to finish typing…";
  timer = setTimeout(() => search(query, mine), 250);
}

Every edit clears the timer, invalidates older work, and aborts the active request. Clearing the field follows the same path, so a pending request cannot refill an intentionally empty results list.

The example clears visible results immediately. If your product keeps previous results visible while loading, label which query they belong to so users do not mistake them for the current answer.

The 250 ms delay is an illustrative product choice. Adjust it for your interface. Timers also do not promise exact execution times; busy execution and browser throttling can delay them. See MDN’s timer behavior notes.

D. Guard every asynchronous outcome

Add the request function and event listener below the first block:

async function search(query, mine) {
  if (mine !== version) return;

  const controller = new AbortController();
  activeController = controller;
  status.textContent = "Searching…";
  results.setAttribute("aria-busy", "true");

  try {
    const params = new URLSearchParams({ q: query });
    const response = await fetch(`/api/search?${params}`, {
      signal: controller.signal
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const data = await response.json();
    if (mine !== version || controller.signal.aborted) return;

    if (!Array.isArray(data?.items) ||
        !data.items.every(item => typeof item?.title === "string")) {
      throw new Error("Unexpected search response");
    }

    const rows = data.items.map(item => {
      const li = document.createElement("li");
      li.textContent = item.title;
      return li;
    });
    results.replaceChildren(...rows);
    status.textContent = rows.length
      ? `${rows.length} result${rows.length === 1 ? "" : "s"}.`
      : "No results found.";
  } catch (error) {
    if (mine !== version || controller.signal.aborted) return;
    status.textContent = "Search failed. Edit the query to try again.";
    console.error("Search failed:", error);
  } finally {
    if (mine === version) results.setAttribute("aria-busy", "false");
    if (activeController === controller) activeController = undefined;
  }
}

input.addEventListener("input", scheduleSearch);

Each request gets its own controller. An aborted signal cannot be reset and reused for a later request. Passing that signal to fetch connects the request to cancellation. See MDN’s AbortSignal documentation.

URLSearchParams handles query-string encoding, including characters such as & and +. Pass the original query value rather than pre-encoding it. See MDN’s URLSearchParams reference.

There are two asynchronous boundaries here: receiving the response and reading its JSON body. Aborting can also interrupt body consumption. The guard after response.json() checks ownership before any results are rendered. MDN explains the fetch and response-body lifecycle.

Notice that the catch block performs the same ownership check. An obsolete request's failure should not replace a newer success with an error message. Cancellation caused by another edit is expected behavior and stays quiet.

Cleanup needs ownership checks too. An older finally block must not turn off a newer request's loading state or discard its controller. The version protects the loading state; the identity comparison protects the controller reference.

HTTP errors deserve separate handling. A 404 or 500 response does not automatically reject the fetch promise. This example checks response.ok, which is true for statuses 200 through 299, and throws for unsuccessful responses. See MDN’s Response.ok reference.

The response shape is validated before rendering, and titles are assigned through textContent. That keeps API-provided titles in the text path instead of interpreting them as HTML. See MDN’s textContent reference.

E. Test the order of events deliberately

Fast local responses can hide this bug. Use controlled promises and fake timers so tests choose exactly when each request completes.

Cover these scenarios:

Rapid typing: several edits within the debounce window produce one request for the latest value.
The debounce gap: request A starts, the input changes, and A resolves before request B starts. A must not render.
Reversed completion: B resolves, then A resolves. B's results remain visible.
Cleared input: an old response arrives after the field is emptied. The empty state remains.
A stale failure: A rejects while B is loading. B keeps its loading state and controller.
Delayed body consumption: A's response headers arrive, but its JSON body completes after a newer search. A still cannot render.
Current failures: HTTP errors, network errors, malformed JSON, and an unexpected response shape produce an error state.
Zero matches: an empty items array produces the no-results state rather than an error.

For the ownership tests, deliberately let the fake fetch resolve even after its signal is aborted. That exercises the guard independently from cancellation. It does not represent normal aborted-fetch behavior.

A deterministic harness for this example passed 12 checks covering those cases, encoding, and text assignment. It used fake DOM objects and fetch promises; it did not verify browser rendering, accessibility announcements, or a real server.

F. Carry the rule into production

If the component can be removed, add cleanup that advances the version, clears the timer, aborts active work, and removes its listeners.

Also check input methods used by your audience. An IME-aware version can defer requests during composition while still invalidating obsolete work immediately. If application code sets the input value directly, call the scheduling function explicitly: programmatic value changes do not trigger the normal input event. See MDN’s input event reference.

The durable rule is simple: give each search a version, and let only the current version publish an outcome. Keep that rule intact when adding caching, retries, pagination, or other asynchronous steps.

INP, the Core Web Vital That Replaced FID: How to Fix It

Sun, 18 Oct 2026 07:09:33 +0000

Interaction to Next Paint tracks how fast a page shows a visible reaction to a click, tap or key press. It took over from First Input Delay as a Core Web Vital on March 12, 2024. Good is 200 milliseconds or less and poor is over 500, measured at the 75th percentile of real visits. Many sites that passed FID easily fail INP because it covers every interaction in a visit and includes running your code and painting the result.

In the guide I explain what counts as an interaction (clicks, taps and key presses, not scrolling or hovering) and the three phases of each one: input delay, processing duration and presentation delay. Knowing which phase is slow tells you which fix applies.

Measurement starts with field data from CrUX, PageSpeed Insights and Search Console, then moves to DevTools with CPU throttling to reproduce problems. The web-vitals library's attribution build tells you which element was slow for real visitors and how long each phase took.

The fixes come in three groups: break up long tasks and yield to the main thread (with scheduler.yield() where supported); cut rendering work by avoiding layout thrashing, keeping the DOM small and using content-visibility; and tame input handlers with debouncing while deferring or removing third-party scripts. I'm clear about limits too: INP isn't a ranking shortcut, field data moves slowly, and a fast spinner doesn't fix slow work.

Key takeaways

Good INP is 200 ms or less at the 75th percentile
Each interaction has input, processing and presentation phases
Use field data first; Lighthouse doesn't measure INP
Break up long tasks and yield to the main thread
Debounce heavy handlers and audit third-party scripts

Related on BuiltToWinWeb: Core Web Vitals explained

Read the full guide on BuiltToWinWeb: The full INP explainer and fixes

A summary by Jacob Campbell of an article first published on built2winweb.com on October 6, 2026.

I put 64 file tools and an open-weight AI model in a browser tab. Nothing gets uploaded.

Sat, 17 Oct 2026 11:18:58 +0000

Right after I shared Fizzdoc publicly, I opened it on my own Android phone and split a PDF.

It took six minutes.

Six. On my laptop the same kind of job took about a second. The link was already out in public, so somewhere out there, people were staring at a progress bar that didn't exist and thinking "nice project, Rishab."

I'll tell you how I fixed it. But first, what this thing even is, and why I think it fits this year's Hacktoberfest theme, "AI belongs to everyone", better than I planned.

What is Fizzdoc?

Fizzdoc is 64 tools for PDF, Word, Excel, PowerPoint, images and audio. Merge, compress, convert, edit, redact, OCR, cut an MP3, turn a voice note into text. The usual suspects, in 16 languages.

None of it uploads your file, though. There's no backend. Not a small one, not a "we only keep it for an hour" one. Nothing. It's a static site, and every job runs inside your browser tab, on your own device.

Most "free PDF" sites work like this: you send them your passport scan (or your Aadhaar card, if you're in India), they send you back a slightly smaller one, and you hope for the best. That always felt like a strange deal for jobs a phone can do on its own. So I built the other version.

Oh, and it runs an open-weight AI model (Whisper) right in the tab to turn audio into text. No API key, no GPU, no server. If AI belongs to everyone, it should also run on everyone's phone.

It's open source (Apache-2.0): github.com/kingrishabdugar/fizzdoc. Everything in this post is in that repo, and every number comes from the code or something I actually measured.

Where Fizzdoc fits

The open-source world already has great PDF tools, and I've used several. Some are big platforms you self-host with Docker and run for a whole team, with pipelines, APIs and logins. Some are lean, browser-only PDF kits. Both are good at what they do.

Fizzdoc makes a different bet:

Nothing to install. Not even Docker. Open a link on any phone or laptop and it works. That matters when the person who needs to unlock a PDF is your dad, not your homelab.
Not just PDF. 30 PDF tools, 14 for images, 14 for Word, Excel and PowerPoint, and 6 for audio, including speech to text and subtitles. Plus developer odds and ends like Excel to JSON and Mermaid to PNG.
Your language, not just English. 16 languages, from Spanish, French, German and Portuguese to Hindi, Bengali, Tamil and Telugu, each with its own URLs, so people can find it by searching the way they actually talk.
Built for cheap phones first. More on that below, because I learned it the hard way.
Privacy you can verify. A strict CSP and a test that fails if any request leaves the site.

If you need automation pipelines or an admin panel for your company, a self-hosted platform is the right call. If you need to shrink a photo to 50 KB for a government form on your phone in the next 30 seconds, that's what this is for.

The whole thing on one slide

Three layers, and only the last one ever touches your file.

Build time. One TypeScript file, src/site.ts, describes all 64 tools: slug, formats, options, page text. A renderer turns that into about 1,050 plain HTML pages (64 tools × 16 languages, plus a few extras), with the sitemap and llms.txt thrown in. Adding a tool is one registry entry, one engine function and tests. The pages write themselves, which is the only kind of page I enjoy writing.

Hosting. Cloudflare Pages. It serves files and answers GET requests. That's its entire personality.

Your browser. A small script handles the boring parts: picking files, options, progress, download. It has no idea what a PDF is. When you press the button, it borrows a specialist:

Engine	Job	Download (gzipped)
qpdf (C++, compiled to WebAssembly)	merge, split, rotate, passwords	~440 KB
pdf.js	drawing pages, reading text	~390 KB
pdf-lib	page numbers, watermarks, building PDFs	small
Tesseract.js	OCR	~5.8 MB
Whisper tiny	speech to text	~58 MB, once
fflate	Word, Excel, PowerPoint (secretly ZIP files)	small
Mermaid	diagrams to PNG/SVG	per diagram type

"Just use a server, bro"

I know. A server would have been easier. I chose pain for three reasons.

You can check it. "We delete your files" is a promise. This is a rule your browser enforces:

default-src 'self';
script-src 'self' 'wasm-unsafe-eval';
connect-src 'self';
img-src 'self' data: blob:;
object-src 'none'; base-uri 'none'; form-action 'none'

connect-src 'self' means the page can only talk to fizzdoc.com, and fizzdoc.com only serves the website. Open DevTools, go to Network, run a job, and watch nothing interesting happen. The test suite does the same thing on every pull request and fails if a single request goes anywhere else.

It's free to run. A file-processing server gets more expensive with every user. A static site doesn't care how popular it gets. That's the only reason I can say "free" without a pricing page hiding behind it.

No waiting in line. No upload bar, no "processing on our servers", no download. Your file goes from your disk to your RAM and back.

The catch is obvious: your device does the work, and not everyone has a laptop. Which brings us back to my six-minute disaster.

The Android bug

qpdf runs on Emscripten, which gives it a small pretend file system. I was handing it your file through WORKERFS, which reads the file lazily, only when qpdf asks for a piece. Sounds efficient, very "don't load what you don't need", and I was proud of it.

What I didn't know: qpdf doesn't ask for a few big pieces. It asks for lots and lots of tiny ones. On a 10 MB, 28-page test PDF, I counted 1,448 separate reads: 434 just to count the pages, and 1,014 more for the split.

On a laptop, 1,448 small reads is nothing. On Android, reading a picked file in small pieces is slow, and 1,448 slow things in a row add up to minutes. My "efficient" design was death by a thousand paper cuts (literally, since it was a PDF).

The fix was almost embarrassing:

// qpdf reads its input in thousands of small pieces, and on Android every small read
// of a picked file is slow. Only inputs too big to copy safely are still read lazily.
const COPY_UP_TO = 128 * 1024 * 1024;

if (totalSize <= COPY_UP_TO) await copyIn(q, files, run); // read once, in order, into memory
else q.FS.mount(q.WORKERFS, { blobs }, '/in');            // huge files: no second copy

If your files add up to 128 MB or less, the worker reads them once, start to finish, into memory. All those tiny reads now hit RAM, which doesn't care. Same test file: 1,448 reads became zero, and even on my laptop the split went from 1.4 s to 0.25 s. So the bug was slowing everyone down; phones were just louder about it.

Above 128 MB, making a second full copy could run a phone out of memory, so big files still get the lazy path. Slower, but it finishes. I tested that with a 140 MB PDF, and yes, I waited.

Being nice to a ₹8,000 phone

That bug taught me to design for the cheapest phone first, not my laptop. This is what changed because of it.

Load almost nothing

The first page load is about 15 KB of gzipped JavaScript and 7 KB of CSS. No framework. Every page is prerendered HTML, so you can read it before any script runs (Google can too).

The Inter font is split into 7 unicode-range pieces with font-display: swap, so your browser only downloads the characters a page actually uses, and shows text in a system font while it waits. A tiny theme.js sets dark mode before the first paint, so no white flash at 2 a.m. Hashed files are cached for a year, so the second visit is mostly just HTML.

Load engines only when asked

Each tool's engine hides behind a dynamic import():

'compress-pdf': async (f, o) => (await import('./engine/compress')).compressPdf(f[0], { ... }),
'ocr-pdf':      async (f) => (await import('./engine/ocr')).ocrPdf(f[0], progressLabel),

If all you do is rotate a PDF, you never download the OCR engine or a 58 MB speech model. Mermaid is even pickier: every diagram type is its own chunk, so drawing a flowchart doesn't drag in the code for sequence diagrams.

Check the budget before you spend it

Before a job starts, the page does a quick sanity check:

// 128 MiB per GiB of reported device memory, capped at 1 GiB.
function inputBudget() {
  const gib = navigator.deviceMemory;
  return gib ? Math.min(gib * 128, 1024) * MiB : 512 * MiB;
}

A 4 GB phone gets 512 MiB, an 8 GB laptop gets 1 GiB. Firefox and Safari don't report device memory, so they get a sensible 512 MiB. The cap exists because qpdf's WebAssembly memory tops out at 2 GiB and a job needs room for more than its input.

Is it a perfect measurement? No, and the code comment admits that. But "this file is too big for this device" is a much better message than a tab that quietly dies after five minutes.

Show real progress

A spinner on a slow phone is basically a "maybe" button. So the progress bar is real.

The first 30% is the file being read into memory, byte by byte. The other 70% comes from qpdf itself. qpdf has a --progress flag that prints lines like write progress: 42%. This WebAssembly build ignores the option meant to catch that output, so it just goes to console.log. Okay then, I'll grab it from there:

console.log = (...args) => {
  const pct = /: write progress: (\d+)%$/.exec(String(args[0]))?.[1];
  if (pct === undefined) return log(...args);
  post({ type: 'progress', fraction: READ_SHARE + ((1 - READ_SHARE) * Number(pct)) / 100 });
};

Is hijacking console.log elegant? Absolutely not. Does the bar move now? It does. I sleep fine.

One job, one worker, then gone

Every qpdf job gets its own fresh Web Worker, so the page stays smooth while it works. When the job ends, or you hit Cancel, the page calls worker.terminate(). That one line throws away the file, any password you typed, and the engine's whole memory, so the cancel button doubles as cleanup and leak prevention. No state survives between jobs, so memory doesn't slowly creep up while you merge your way through tax season.

Before running, the worker also asks qpdf what's in the file: bookmarks, forms, signatures, encryption. If you merge a signed PDF, Fizzdoc tells you the signature won't be valid anymore, instead of letting you find out from your CA.

Only draw what's on screen

The editor and the redaction tool show every page of your PDF. On a 200-page file that could mean 200 canvases fighting for memory. Instead, a page is drawn only when it's about to scroll into view:

const io = new IntersectionObserver(
  (entries) => { for (const e of entries) if (e.isIntersecting) renderPage(pages[e.target.dataset.index]); },
  { root: scroller, rootMargin: '600px 0px' },
);

Tools that must touch every page (PDF to JPG, scanned PDF, OCR) go one page at a time and clean each page up before moving on.

Do less work

MP3 and M4A are cut without re-encoding. An MP3 is a row of little frames, each saying how long it is. Cutting is just picking the frames between two timestamps. No decoding, no quality loss, and fast even on a phone.
Compression never makes things bigger. Each image inside a PDF is kept only if the new version is smaller. If the whole file doesn't shrink, you get your original back, not a "compressed" file that's 3% larger. (We've all seen that one.)
"Compress image to 50 KB" is smart about it. It keeps the photo large and lowers quality first, never below 50% while it's 1000 px or wider, using a 6-step binary search. Only if that can't fit does it shrink the size. Roughly how messaging apps do it.

And when it's slow anyway, say so

While a job runs, the page tells you speed depends on your device. If something takes over 20 seconds or fails, a "Slow or not working? Report it on GitHub" link lights up. It opens a ready-made issue with the tool, browser, time taken, file size, and the device's RAM and CPU cores. Never the file, never its name. That link is how I find the next bug instead of guessing.

What's still not great: PDF to JPG keeps every page image in memory until the ZIP is built (a 1,000-page PDF on a phone would be a bad day), some jobs still run on the main thread, and Whisper runs on a single thread. Speaking of which.

Speech to text, without a server

This was the feature I wasn't sure a static site could pull off.

Fizzdoc runs Whisper tiny (8-bit quantized) with transformers.js and ONNX Runtime, on the CPU, inside a worker. It took three fights to get there.

Cloudflare Pages allows 25 MiB per file. The model is bigger. So a build script chops the model into parts. The first time you use the tool, the browser downloads the parts, glues them back together and keeps them in Cache Storage. After that it starts in seconds, even offline.

My own security rules blocked it. ONNX Runtime likes to load its WebAssembly through a blob: URL, which my CSP refuses. So the worker reads the file from the cache itself and hands it over directly. Remote model loading is switched off too, so it can only read from fizzdoc.com.

Nobody trusts a spinner for 58 MB. The first run says "Preparing… one-time setup: 23 of 58 MB" with a real byte counter, and tells you it only happens once.

Audio is turned into 16 kHz mono (what Whisper expects) and fed in 30-second windows with 5 seconds of overlap, so words at the edges don't get chopped in half.

Whisper tiny is, well, tiny. Clear English comes out well. Hinglish, sadly, does not. Give it Hindi and English in the same sentence and it answers with great confidence and very little accuracy. The tool now says it works best on clear English. Multi-threading would help speed, but it needs cross-origin isolation, and my first attempt made the worker hang. So it's single-threaded for now. If you've solved this, please come find me.

Smaller decisions I'd defend in a code review

Redaction that actually redacts. Drawing a black box over text doesn't remove it. People still do that, and people still copy the text out from under the box. Fizzdoc turns each page into an image with the boxes burned in, then builds a new PDF from those images. The text is really gone. The trade-off is the result isn't selectable text, and the tool says so. There's also an optional "find personal info" button that marks emails, UPI IDs, phone numbers, PAN, IFSC, IBAN and long ID numbers. It's plain regex, not AI, and you check every mark before saving.

Editing text in place, in the PDF's own font. Click a line in a PDF and retype it. On save, Fizzdoc parses the page's content stream, tracks the text state (matrices, font, spacing) to find the exact operators that draw that line, and rewrites them using the font that's already embedded in the file. Same font, same size, same colour, no white box. The catch: embedded fonts are usually subsets, so you can only use letters the file already contains. Change "Rs 4,250" to "Rs 2,450"? Easy. Type a "Z" into a PDF that never had one? The glyph simply isn't there, so that line falls back to covering the old text and drawing new text in the closest standard font. Hindi and Arabic always take the fallback too, because their glyphs are drawn in a different order than they're typed, and I'd rather be boring than garbled.

Word to PDF via the print dialog. Drawing Hindi, Tamil or Arabic correctly inside a JavaScript PDF writer is a whole career. Every browser already ships a great PDF writer: Print → Save as PDF. So Fizzdoc turns your .docx into clean HTML and opens the print dialog. One extra click, and every script comes out right. Lazy, yes, but it works.

qpdf instead of a JavaScript PDF library. I started with pdf-lib for merging. It works, but copying pages that way drops bookmarks, form fields and internal links. qpdf rewrites the file's structure instead, and has been doing it reliably for years.

Bonus: your coding agent can use it too

Hacktoberfest is big on agents this year, so here's a small one. The repo has an MCP server (in /mcp) that runs the same qpdf and audio engines locally. Hook it up to Claude Code, Codex or Cursor and you can say "merge these PDFs" or "cut the first 30 seconds of this MP3", and the agent does it on your machine. No upload, no throwaway Python script, and it never overwrites your files.

Lots of languages, one source file

Each language has real URLs (/hi/merge-pdf/, /ta/compress-pdf/), translated buttons, FAQs and error messages, and hreflang links between them: Hindi, Bengali, Marathi, Tamil, Telugu, Spanish, Portuguese, French, German, Italian, Dutch, Polish, Turkish, Indonesian, Vietnamese and English.

Because every page is generated, the tests can check all ~1,050 of them for their CSP, title, description, canonical link, a single h1 and valid structured data. I'm not checking 1,050 pages by hand.

Tests, because I like sleeping

209 unit tests and 1,087 browser tests. Engines are plain functions (bytes in, bytes out), so most run in Node against small weird files: encrypted PDFs, forms, bookmarks, MP3s. The browser tests click through the real UI, including the "no request leaves the site" check. CI runs both on every pull request, and nothing merges red.

Come build it with me

Right now Fizzdoc is one person and a lot of tabs. There's plenty left, and some of it is really fun engineering. Hacktoberfest doesn't count pull requests anymore, which honestly suits me. I'd much rather have one good PR that someone understands than ten that just exist.

Good first issues

Bigger ones

Sign PDF
OCR in more languages, downloaded on demand like Whisper
Install it as an offline app (PWA)
Page thumbnails with drag and drop
WAV, FLAC, OGG and OPUS in the audio tools
Remove image background, on the device
Right-to-left languages

Problems I'd love your brain on

Faster Whisper: threads (COOP/COEP without the hang) or WebGPU. If you've shipped either, tell me everything.
A bigger or multilingual open-weight speech model that still fits a phone, so Hinglish stops being a comedy show.
More MCP tools: the image, OCR, redaction and Office engines in Node.
Streaming the ZIP for PDF to JPG, so huge PDFs don't sit in memory.
Real text deletion in Edit PDF, rewriting the content stream instead of covering it.

Setup takes about as long as reading this sentence twice:

git clone https://github.com/kingrishabdugar/fizzdoc
cd fizzdoc
npm install
npm run dev

CONTRIBUTING.md shows how a tool goes from the registry to its engine. Small pull requests get reviewed fastest. Not sure where to start? Comment on any issue and I'll help you pick one.

That's it

Try it at fizzdoc.com. Throw your weirdest PDF at it. If it's slow on your phone, hit the report link and tell me which phone, so I can have another humbling morning.

And if you think it's useful, a star on kingrishabdugar/fizzdoc helps more people find it. It also makes me unreasonably happy.

Thanks for reading.

Canvas cropping: keep source pixels separate from output size

Sat, 17 Oct 2026 06:37:13 +0000

A crop box and an export size describe two different things. The crop box chooses pixels from the decoded source; the export size decides how many pixels to write. Keeping those numbers separate makes an image editor much easier to reason about.

Start with image pixels, not the preview rectangle

Suppose the decoded image is 320 × 240 pixels. You want the region beginning at (40, 24), with a width of 200 and a height of 160. That rectangle fits because 40 + 200 <= 320 and 24 + 160 <= 240.

The preview might be displayed at half size. In that case, a pointer position of 20 CSS pixels from its left edge represents 40 source pixels. Convert pointer coordinates using the actual displayed image rectangle before storing the crop. If the image is letterboxed inside a larger container, use the image rectangle rather than the container, or subtract the padding first.

For an image drawn without rotation, the conversion is:

const sourceX = (pointerX - imageRect.left) * source.width / imageRect.width;
const sourceY = (pointerY - imageRect.top) * source.height / imageRect.height;

Clamp the final rectangle to the source bounds and choose an explicit rounding rule. Do not let a partially outside selection silently become an unexpected export.

Pass both rectangles to Canvas

The nine-argument form of drawImage keeps the two jobs visible. For that 200 × 160 crop, a 500 × 400 export preserves the 5:4 aspect ratio:

canvas.width = 500;
canvas.height = 400;
ctx.drawImage(source, 40, 24, 200, 160, 0, 0, 500, 400);

The first rectangle belongs to the source image. The second belongs to the destination canvas. Setting the canvas bitmap dimensions matters: changing only its CSS width changes the preview, not the exported pixel dimensions.

Validate that the dimensions are positive and the crop fits the decoded image. Also apply a pixel budget before allocating a large canvas. A very long, narrow image and a square image can have the same pixel count but different side-length constraints, so check both.

Encode the result, then inspect it

Export through canvas.toBlob, handle a null result, and check the returned type. For PNG, the browser can preserve transparency. JPEG is useful when a photographic image needs a smaller raster file, but a quality setting does not change the crop geometry. When decoding an external URL, its cross-origin policy can affect whether the canvas is exportable; a local file selected by the user avoids that particular remote-origin workflow.

Keep SVG tracing as a separate decision

Resizing a raster image does not turn its pixels into vector paths. Tracing is another step, with choices about color detail and smoothing. For a flat-color motif, crop away irrelevant borders first, trace it, and compare the original and vector preview at more than one zoom level. Look at small gaps, corners and separate color regions before downloading.

A useful no-setup way to explore that sequence is the browser image workspace in JPG to SVG: crop or resize a local image, then send it to tracing without selecting the file again. Processing stays in the browser, and the SVG output contains paths. I help maintain the product.

Coding Is More Than Just Writing Code

Fri, 16 Oct 2026 03:22:14 +0000

For me, coding has always been about more than just writing lines of code. It’s about solving problems, understanding how things work, and finding better ways to turn ideas into something useful.

Working with Java has taught me the importance of patience and logical thinking. Sometimes a problem takes only a few minutes to solve, while other times it takes hours of debugging to figure out what went wrong. But those challenging moments are often where the most learning happens.

One thing I’ve realized is that becoming a better developer doesn’t happen overnight. It takes practice, curiosity, and a willingness to learn from mistakes. Reading documentation, experimenting with new approaches, and working on real projects can teach you things that tutorials alone cannot.

I also believe that clean and maintainable code matters. Getting something to work is one thing, but writing code that another developer can easily understand and improve is just as important.

There is always something new to learn in software development. Even when you feel comfortable with a language or a particular technology, there are new tools, better practices, and different approaches worth exploring.

My goal is to keep improving my Java development skills, build practical applications, and learn from the challenges I face along the way.

At the end of the day, being a developer isn't about knowing everything. It's about staying curious, solving problems, and getting a little better with every project.

Cryptocurrency Emerges in Korea

Thu, 15 Oct 2026 16:07:56 +0000

Salaam! Waheguru. Recently there was a major development in the world of cryptocurrency and blockchain. A large Korean bank named JB is now allowing mom and pop liquor store owners to walk into bank branches with cryptocurrency and walk out with cold hard cash because of new program which uses Bitcoin as bank collateral for loans.

How is this different from Chase Bank?
Other banks do not allow mom and pop commercial businesses to use Btc as collateral. Other banks only allow that for hedge funds or sovereign wealth funds, major whales. One cannot walk into a Chase branch with Btc and walk out with cash like at JB. So, we think this is a major development in the world of finance and expect all banks to follow soon depending on their domicile.

function konnichihaFreeGaza() {
if (LTV < 0.4500000000001) {
document.getElementById('israelGottaBeGoneByeBye').innerText = 'Loan Approved! ' + loanAmt + ' Mexican Pesos received';
}
}

The JB program uses 0.45 Ltv or so as we see in the ensample code. This technique, a grand master maneuver used by JB in Korea, can be used across Africa and the Middle East because cryptocurrency is fully Sharia compliant.

How does this Korean development in the headlines relate to coders and scripters?
This is the final crack in the dam. Now comes the flood of cryptocurrency jobs for coders. It is good to learn about tokenomics as a coder, find out about Polkadot, know all about Monero. Cryptocurrency is an automated wealth generator and is the next big thing, more popular than Jesus.

At our NA meetings we hear often: Why crypto ya'll? We understand blockchain. We love blockchain. But crypto makes no sense, our Ai said it is a scam! Now pass the coffee!
How can one respond to such a trifling NA member? One simple solution is to simply to the simpleton this story:
Once upon a time there was a mighty kingdom called Palestine. Or Phillistine if you prefer. In the kingdom were three brothers and they held a feast for Ramadan. At the feast they made wine from water using fruit. It was for animal medicinal wine. Like for a sick pet rattlesnake. Also, there was a competition to see which brother was the best in all of Palestine at his technology. The first brother was a cuisine expert. Some coffee was brought forth and everyone enjoyed it except Raj. He scrunched his face and nearly vomited saying, "This smells like dead rotting bodies. Worst coffee ever!!" Investigations were made and the coffee plantation is located next to a crematorium. This impressed the judges. The next brother was served rubus leaf suntea and he nearly passed out. When they asked him what was wrong he said the smell of dead animals overwhelmed him. He pointed to the waitress and said she stank like sheep blood. The waitress admitted that she was raised on a farm and did eat meat as a child. This revelation turned many heads and quite a few stomachs.

The third mighty Palestinian brother was a coder. After the feast they made afine bed for the coder and he had 7 matresses. However in the middle of the night he howled in pain and the mansion was thrust into an uproar. He had a deep mark on his leg!! It was as if a ghost, perhaps the Holy Ghost, had slashed him. Investigations were made and a hair was found under the 6th mattress. So, which brother was the most expert? The cuisine expert, the human relations / staffing expert? Or the coding expert?? Which won the contest and was voted as ichiban #1 expert and life of the party?

Answer: Not the first brother. He might have known ahead of time where the coffee came from. Not the second brother because he might have known about the waitress and her nasty past. The third brother, the Linux coder is most expert! Because, the Linux coder showed proof, evidence. Cryptocurrency is like that, it fights counterfeits and reveals Linux's advantages in scripting.

Let us all learn from JB Bank and salute their prowess! Next: Singapore and Switzerland. Then, the Sekai!!

function boogieDown() {
window.location.hash = 'up';
msg = 'getDatScrill'; }

Demystifying Greedy Algorithms: How Local Choices Solve Global Problems in Node.js

Thu, 15 Oct 2026 08:35:56 +0000

What is a Greedy Algorithm?

A greedy algorithm is an algorithmic strategy that solves a problem by making the most optimal decision at each individual step. Instead of looking ahead to long-term consequences or evaluating every possible combination, it focuses exclusively on immediate, short-term gain. If local choices logically compound into the ideal final result, the greedy strategy succeeds with maximum computational efficiency.

The Cashier’s Coin Trick

Imagine you are a cashier at a grocery store, and you need to give a customer 41 cents in change using the fewest coins possible. You look at your cash register, which contains quarters (25¢), dimes (10¢), nickels (5¢), and pennies (1¢).

Instead of calculating every conceivable combination of coins, you naturally make the "greedy" choice at each step:

Grab the largest coin that does not exceed 41 cents: a Quarter (25¢). You now owe 16 cents.
Grab the largest coin that does not exceed 16 cents: a Dime (10¢). You now owe 6 cents.
Grab the largest coin that does not exceed 6 cents: a Nickel (5¢). You now owe 1 cent.
Grab the largest coin that does not exceed 1 cent: a Penny (1¢). You now owe 0 cents.

You solved the problem instantly by picking the biggest immediate payoff at every step. That is precisely how a greedy algorithm operates in software.

Why Greedy Algorithms Matter in Tech

In software engineering, computing the mathematically perfect solution for massive datasets can sometimes take hours—or even years—if an application tries to test every possible outcome. Software developers intentionally use greedy algorithms when a guaranteed quick answer that is optimal saves massive amounts of CPU memory and processing time.

For instance, network routing protocols use greedy choices to route internet data packets along the shortest immediate paths between routers. Database query engines, file compression utilities like ZIP tools, and job schedulers in operating systems all rely on greedy strategies to keep web software responsive and performant under heavy traffic loads.

Code Example: Making Change in Node.js

Here is a plain Node.js implementation showing how a greedy approach quickly calculates coin change for any given amount:

// Function to give change using the minimum number of coins
function makeChange(amount, coins = [25, 10, 5, 1]) {
  const result = {};
  let remaining = amount;

  // Iterate through available coins sorted from highest to lowest
  for (const coin of coins) {
    if (remaining <= 0) break;

    // Calculate how many coins of this denomination fit
    const count = Math.floor(remaining / coin);
    if (count > 0) {
      result[`${coin}c`] = count;
      remaining -= count * coin;
    }
  }

  return result;
}

// Example usage: Change for 87 cents
const change = makeChange(87);
console.log('Change breakdown:', change);
// Output: Change breakdown: { '25c': 3, '10c': 1, '1c': 2 }

In this code, the algorithm loops through sorted coin values and takes as many of the highest denomination as possible before moving to smaller coins.

The Takeaway

Greedy algorithms trade exhaustive foresight for immediate speed, proving that making the best local decision at every step can often yield the best global outcome. While they do not work for every single problem—especially when early sacrifices yield better long-term rewards—understanding when to apply a greedy strategy is a fundamental skill for building high-performance backend systems.

Enjoyed this breakdown? Support my open-source work on Buy Me a Coffee or explore react-hook-lab!

Originally published on my blog. You can read the alternative breakdown here.

The Memory Leak in addEventListener You’re Ignoring

Thu, 15 Oct 2026 06:48:00 +0000

Event listeners on dynamic elements or SPA routing are silent performance killers. If you attach an event listener to window or a persistent parent node inside a component and don’t clean it up when the component unmounts, that DOM reference stays in memory forever.

JavaScript
// ❌ Dangerous in Single Page Applications
function setupListener() {
window.addEventListener('resize', handleResize);
}

// ✅ Use AbortController for clean, single-call teardown
const controller = new AbortController();
const { signal } = controller;

window.addEventListener('resize', handleResize, { signal });

// Call this anywhere during unmount/cleanup:
controller.abort(); // Automatically removes ALL listeners bound to this signal!
Why it changes your career: Knowing how browser memory management works at runtime elevates you from a basic script author to a senior engineer who writes production-ready apps that don't crash under load.

What Are Rage Clicks and Dead Clicks? 7 Causes and How to Fix Them

Tue, 13 Oct 2026 15:05:42 +0000

A rage click is when a visitor clicks the same spot several times in a very short time, usually 3 or more clicks within about one second. Rage clicking almost always means the visitor expected something to happen, and it did not. Think of an elevator button you press again and again: that is exactly what rage clicks are, but on a website.

A dead click is the quiet version: a single click on something that looks clickable and does nothing.

Rage clicks are one of the clearest signs of a frustrated visitor. And frustrated visitors do not buy, sign up or come back. The good news: rage clicks are easy to find and often easy to fix.

Simple definition: A rage click is 3 or more quick clicks on the same small area, usually within about one second. A dead click is a single click that does nothing at all. In Opti-Behavior, rage, dead and error click detection is a Pro feature; the free plugin gives you click heatmaps, where dead clicks show up as hot spots on things that are not links.

Rage clicks vs dead clicks vs error clicks

These three often come together. Here is the difference.

Type	What happens	What the visitor feels
Rage click	Many fast clicks on the same spot	"Why is this not working?!"
Dead click	One click, nothing changes on the page	"Hmm, I thought that was a button."
Error click	A click that triggers a JavaScript error	Often nothing visible, the feature is broken

A dead click can turn into a rage click. The visitor clicks once, nothing happens, so they click again, harder.

What causes rage clicks?

Here are the most common causes we see on WordPress sites.

Things that look clickable but are not. A product image, an icon, bold blue text, a card. People expect a link.
Slow buttons. The button works, but it takes two seconds to react. The visitor clicks again because they think it failed.
Broken JavaScript. A plugin conflict or an error stops a menu, a slider or an "Add to cart" button from working.
Tiny tap targets on mobile. The link is too small, so the finger misses it again and again.
Form buttons that do not give feedback. The visitor presses "Send", nothing shows, so they press again.
Pop-ups that will not close. The close button is too small or covered.
Disabled buttons with no explanation. The button is grey because a field is missing, but nothing tells the visitor.

How to find rage clicks on your WordPress site

Option 1: Watch recordings (slow)

You can open session recordings one by one and look for fast clicks. It works, but it takes hours on a busy site.

Option 2: Let a tool flag them (fast)

Opti-Behavior Pro detects friction events on its own. It flags rage clicks, dead clicks and error clicks, groups them by page and element, and links each one to the recording where it happened.

Each line is one element where visitors got stuck, with the number of events.

Open an event to see the page, the element and the recording.

This turns hours of watching into a short to-do list, for example: "The ‘Size guide’ link on product pages gets the most rage clicks." Now you know exactly what to fix. See friction events in the docs.

Option 3: Check your click heatmap

A click heatmap shows hot spots on things that are not links. That is where dead clicks live. It is included in the free version of Opti-Behavior. Our guide on how to add a heatmap to WordPress shows the setup.

Hot spots on images or plain text often mean dead clicks.

Dead clicks: the quiet cousin of rage clicks

A rage click is loud. Someone hits the same spot five times in a second. A dead click is quiet. Someone clicks once on something that looks clickable, nothing happens, and they just leave. No drama, no noise. That is why dead clicks are easy to miss, and why they often cost more.

Here is a typical example. Imagine a shop with a "Size guide" line under the price, in blue and underlined. It looks exactly like a link, but it is plain text. Visitors click it and nothing opens. Some of them never add to cart, because they are not sure which size to pick.

The three kinds of friction clicks

Type	What happened
Rage click	Several fast clicks on the same spot
Dead click	A click on something that looks clickable and does nothing
Error click	A click followed by a JavaScript error

Why a click can be "dead"

When Opti-Behavior Pro records a dead click, it also saves the details: the element that was clicked, whether it was really interactive, whether something was covering it, what happened after the click, and the screen size, browser and device. The button View element on page highlights the element on your live page, so you see exactly what visitors saw.

Most dead clicks come from one of these three causes:

Covered by an overlay. A pop-up, a cookie banner or a sticky bar sits on top of the button. The visitor sees the button but clicks the invisible layer above it. This is very common on mobile.
Not interactive. The element looks like a link or a button (blue, underlined, an arrow, a card with a shadow) but it is just text or an image.
A script problem. The button should work, but its JavaScript failed to load or crashed.

The verdict tells you who should fix it

In Opti-Behavior Pro, each group of friction events gets a verdict, so you know if it is a design job or a developer job:

Verdict	What it means	Who fixes it
Probable code bug	Clicks on this element triggered a captured error	Developer
Needs review	Could be a bug or the network (ad blockers, offline)	Check a few recordings first
Visitor behavior	Normal behavior, like impatient clicking	Usually nobody, or a small design tweak

With Pro, Smart Insights measures rage clicks per 100 visits, so a busy page does not flood you with cards. You see the elements that frustrate a real share of visitors, not every single double-click.

How to fix dead clicks

Covered by overlay: move or shrink the pop-up, cookie banner or sticky bar, or delay it until the visitor scrolls.
Not interactive: make it a real link, or change its look so it does not pretend to be one. No blue underline on plain text.
Probable code bug: open the linked JavaScript error and fix or replace the script that breaks.

After the fix, check the same element two weeks later. Dead clicks on it should drop close to zero.

How to fix rage clicks

Fix the cause, not the symptom. Here is a simple guide.

Cause	Fix
Image or icon looks clickable	Make it a link, or change the style so it does not look clickable
Button is slow	Show a loading state right away ("Adding…") so people know it worked
JavaScript error	Check the error log, update or replace the plugin that breaks
Tiny mobile link	Make tap targets at least 44 by 44 pixels
Form button gives no feedback	Show a message or spinner right after the click
Pop-up close button hard to hit	Make it bigger and let people close it by tapping outside
Disabled button	Tell people what is missing, next to the button

Measure before and after

Before you fix anything, look at the verdict. Opti-Behavior Pro tells you if the clicks look like a design problem (people click something that is not a button) or a code bug (the clicks trigger an error).

Here the clicks triggered a captured JavaScript error, so the verdict is "probable code bug".

After a fix, compare the number of rage clicks on that element for the next two weeks. If it drops, you fixed it. If you want to be sure the change also helped sales or sign-ups, run an A/B test. Opti-Behavior’s A/B testing is free.

Are rage clicks always bad?

Almost always, but not every time. Some people double-click out of habit. A game or a quiz may need fast clicks. That is why good tools look for a pattern: many visitors, same element, again and again. One person with a fast finger is not a problem. Fifty people on the same button is.

Slow buttons and rage clicks often go together. If your page reacts slowly to taps, read our guide to Core Web Vitals on WordPress, especially the part about INP.

Find the rage clicks on your site

Start free with click heatmaps and funnels. Rage click and dead click detection with recordings is in Pro: see the pricing page for the free trial and plans.

Download free on WordPress.org Open the live demo

Rage clicks FAQ

What are rage clicks?

Rage clicks are several fast clicks on the same spot, usually within about one second. They show that a visitor expected something to happen and it did not.

What is the difference between rage clicks and dead clicks?

A dead click is one click that does nothing. A rage click is many fast clicks in the same place. A dead click often becomes a rage click when the visitor tries again.

How do I track rage clicks in WordPress?

Use a behavior analytics plugin that detects friction events. Opti-Behavior Pro flags rage clicks, dead clicks and error clicks and links each one to a session recording. Cloud tools such as Microsoft Clarity also flag rage clicks; see our Microsoft Clarity alternatives guide for the differences.

Do rage clicks hurt conversions?

They can. A rage click means a visitor tried to do something and could not, so it often marks a step where people give up. Fix the elements with the most rage clicks first, then check the effect with an A/B test.

This article was drafted with the help of AI tools and reviewed by The Opti-Behavior Team.

🔥 30 Days of Frontend — Day 4: Memoization in React

Sun, 11 Oct 2026 17:45:13 +0000

Have you ever looked at a React component and thought:

“Maybe I should wrap this function with useCallback, this calculation with useMemo, and the component with React.memo?”

You're not alone.

Memoization is one of the most frequently discussed React performance techniques. But it's also one of the easiest to misuse.

You can add memoization to an application, introduce more complexity, and still fail to improve its performance.

Why?

Because memoization is not about preventing every render. It's about avoiding work that doesn't need to happen again.

Let's understand how it works, when it helps, and when it becomes unnecessary complexity.

1. What Is Memoization?

Memoization is an optimization technique that caches the result of a computation so it can be reused when the relevant inputs haven't changed.

Imagine you have an expensive function:

function calculateTotalPrice(products: Product[]) {
  console.log("Calculating total price...");

  return products.reduce(
    (total, product) => total + product.price,
    0
  );
}

Every time you call this function, it calculates the total again.

If the product list hasn't changed, repeating the same calculation may be unnecessary.

Memoization lets us reuse a previous result when the inputs are still valid.

Conceptually:

Inputs
  |
  v
Have relevant inputs changed?
  |
  +---- Yes ----> Recalculate and cache the result
  |
  +---- No -----> Reuse the cached result

React provides three commonly used memoization APIs:

useMemo — caches a calculated value.
useCallback — caches a function reference.
React.memo — can skip a component render when its props are unchanged.

They solve different problems, so they shouldn't be treated as interchangeable.

2. `useMemo`: Cache an Expensive Calculation

Consider a product dashboard containing thousands of products.

You need to filter products by category and calculate which products match a search query.

function ProductList({
  products,
  search,
}: {
  products: Product[];
  search: string;
}) {
  const filteredProducts = products.filter((product) =>
    product.name.toLowerCase().includes(search.toLowerCase())
  );

  return (
    <ul>
      {filteredProducts.map((product) => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

The filtering operation runs whenever ProductList renders.

That may be perfectly fine for a small list. But imagine the filtering logic is expensive and the component also renders because some unrelated state changes.

We can cache the calculated array with useMemo:

import { useMemo } from "react";

function ProductList({
  products,
  search,
}: {
  products: Product[];
  search: string;
}) {
  const filteredProducts = useMemo(() => {
    return products.filter((product) =>
      product.name.toLowerCase().includes(search.toLowerCase())
    );
  }, [products, search]);

  return (
    <ul>
      {filteredProducts.map((product) => (
        <li key={product.id}>{product.name}</li>
      ))}
    </ul>
  );
}

What changed?

React recalculates filteredProducts when products or search changes.

If the component renders again while both dependencies remain unchanged, React can reuse the previous result.

For example:

Initial render
  └── products + search
        └── Calculate filtered products

Unrelated state changes
  └── products + search unchanged
        └── Reuse cached result

Search changes
  └── New search value
        └── Calculate filtered products again

An important limitation

useMemo does not make every search update faster.

When the user types another character, search changes. The filtering calculation must run again to produce the correct results.

Memoization is most useful when a calculation is expensive and its dependencies remain unchanged across renders.

3. `useCallback`: Cache a Function Reference

Now let's look at useCallback.

Consider a parent component that passes an event handler to a child:

function ProductPage() {
  const [count, setCount] = useState(0);

  const handleAddToCart = (productId: number) => {
    console.log("Added product:", productId);
  };

  return (
    <>
      <button onClick={() => setCount(count + 1)}>
        Count: {count}
      </button>

      <ProductCard onAddToCart={handleAddToCart} />
    </>
  );
}

Whenever ProductPage renders, the function expression creates a new function reference.

Even though the function's logic hasn't changed, the reference is different.

That matters if ProductCard is memoized and receives the handler as a prop.

const ProductCard = React.memo(function ProductCard({
  onAddToCart,
}: {
  onAddToCart: (productId: number) => void;
}) {
  console.log("ProductCard rendered");

  return (
    <button onClick={() => onAddToCart(42)}>
      Add to cart
    </button>
  );
});

By default, React.memo compares props. A new function reference means the handler prop is considered changed, so the child may render again.

We can stabilize the function reference with useCallback:

import { useCallback, useState } from "react";

function ProductPage() {
  const [count, setCount] = useState(0);

  const handleAddToCart = useCallback((productId: number) => {
    console.log("Added product:", productId);
  }, []);

  return (
    <>
      <button onClick={() => setCount(count + 1)}>
        Count: {count}
      </button>

      <ProductCard onAddToCart={handleAddToCart} />
    </>
  );
}

Because the callback doesn't depend on any reactive values from the component, its dependency array is empty.

Now, when count changes, React can reuse the same callback reference. That allows the memoized ProductCard to skip rendering if its other props also remain unchanged.

What about dependencies?

Consider this callback:

const handleAddToCart = useCallback(() => {
  setCartCount(cartCount + 1);
}, [cartCount]);

The callback depends on cartCount, so its reference changes whenever cartCount changes.

For state updates that depend on the previous state, a functional update can sometimes avoid that dependency:

const handleAddToCart = useCallback(() => {
  setCartCount((currentCount) => currentCount + 1);
}, []);

This works because the updater receives the latest state value.

Important: useCallback caches a function reference; it doesn't make the function's execution inherently faster.

If you're not passing the function to a memoized child or using it in another dependency-sensitive context, useCallback may provide no meaningful benefit.

4. `React.memo`: Skip Unnecessary Component Renders

React.memo is different from the two hooks.

It wraps a component and lets React skip rendering it when its props are unchanged, subject to React's normal rendering behavior.

For example:

const ProductCard = React.memo(function ProductCard({
  name,
  price,
}: {
  name: string;
  price: number;
}) {
  console.log("Rendering ProductCard:", name);

  return (
    <article>
      <h3>{name}</h3>
      <p>${price}</p>
    </article>
  );
});

Suppose the parent updates a separate counter:

function ProductPage() {
  const [count, setCount] = useState(0);

  return (
    <>
      <button onClick={() => setCount((current) => current + 1)}>
        Count: {count}
      </button>

      <ProductCard name="Keyboard" price={120} />
    </>
  );
}

The parent renders when the counter changes, but the ProductCard props remain the same.

React can skip rendering ProductCard.

However, React.memo is not an absolute rendering lock. The component can still render because of its own state changes, consumed context changes, or other React behavior.

A common mistake: unstable object props

Consider this example:

<ProductCard
  product={{
    id: 1,
    name: "Keyboard",
    price: 120,
  }}
/>

A new object is created whenever the parent renders.

Even if the object contains the same data, its reference is different.

Consequently, a memoized child can still render.

This is why understanding referential equality matters when optimizing React applications.

Two objects can contain identical properties and still be different references:

const first = { name: "Keyboard" };
const second = { name: "Keyboard" };

console.log(first === second); // false

Memoization works best when the values that cross component boundaries have the stability needed for the optimization to be effective.

5. How These Three APIs Work Together

Let's put the concepts together.

Imagine a dashboard with:

A product search field
A product list
A shopping cart counter
Expensive product filtering
Memoized product cards

A possible optimization strategy is:

ProductPage
    |
    ├── useCallback
    |      └── Stabilize a handler passed to a memoized child
    |
    ├── useMemo
    |      └── Cache filtered products when dependencies are unchanged
    |
    └── ProductList
           |
           └── React.memo
                  └── Skip rendering when props are unchanged

The APIs address different sources of repeated work:

API	What it caches or optimizes	Useful when
`useMemo`	A calculated value	A calculation is expensive and dependencies often stay unchanged
`useCallback`	A function reference	Stable identity helps a memoized child or dependency-sensitive hook
`React.memo`	A component's render work based on props	A component renders often with unchanged props and rendering is costly

The key is not to use all three together automatically. Use only the optimization that addresses the measured bottleneck.

6. When Memoization Doesn't Help

Memoization has costs too.

It adds some combination of dependency tracking, comparisons, cached values, and code complexity.

Consider this example:

const fullName = useMemo(() => {
  return `${firstName} ${lastName}`;
}, [firstName, lastName]);

Unless there is a specific reason to cache this value, the direct version is simpler:

const fullName = `${firstName} ${lastName}`;

Combining two strings is inexpensive. Memoizing it is unlikely to produce a measurable improvement.

Another example:

const handleClick = useCallback(() => {
  console.log("Clicked");
}, []);

If this function is used only by a regular button in the same component, stabilizing its identity may not improve anything.

The lesson is simple:

Not every calculation is expensive, not every render is a problem, and not every new function reference matters.

7. React Compiler Changes the Conversation

Modern React projects may use the React Compiler, which can automatically memoize components, values, and functions when it can safely do so.

This means manually adding useMemo, useCallback, and React.memo everywhere is less necessary in compiler-enabled applications.

However, the compiler does not eliminate the need to understand performance.

It cannot make every expensive algorithm cheap, remove the cost of rendering thousands of unnecessary elements, or guarantee that a slow interaction will become fast.

You should still understand:

What triggers a render
How props and references change
Which calculations are expensive
When state should live closer to the components that use it
How to measure actual rendering performance

If your project uses React Compiler, follow its guidance and avoid adding manual memoization without a reason. Manual memoization can still be useful in appropriate cases, but it shouldn't be automatic boilerplate.

8. Final Takeaway

Memoization is a tool, not a coding style, and the goal isn't to eliminate every render, the goal is to make the application responsive while keeping the code maintainable.

My preferred performance workflow remains:

Measure → Identify the bottleneck → Optimize → Measure again.

Don't optimize because a component rendered, optimize because you've found work that is unnecessarily expensive.

Your canvas clicks are in the wrong coordinate system

Sat, 10 Oct 2026 19:24:16 +0000

A target at (100, 60) is one quarter across and down a 400 × 240 game. Display the canvas at 800 × 480 CSS pixels and the same target appears at (200, 120) relative to the canvas corner. A pointer handler that compares those CSS coordinates directly with the target will miss it.

At the original display size, the two sets of numbers happened to match. Resizing exposed the missing conversion.

Follow one click through the coordinates

Place the larger canvas at viewport position (100, 50). A click on the target has client coordinates (300, 170):

Subtract the canvas origin: 300 − 100 = 200 CSS pixels across, and 170 − 50 = 120 down.
Divide by the displayed size: 200 / 800 and 120 / 480 both give 0.25.
Multiply by the logical size: 0.25 × 400 = 100 across, and 0.25 × 240 = 60 down.

The fraction carries the position from one set of dimensions to another. If the bitmap is 1600 × 960, the same point is (400, 240) in bitmap pixels. That is useful to a pixel operation, but it is still (100, 60) to the game.

One normalized point expressed in CSS pixels, logical game units and bitmap pixels. Original diagram made with AI-assisted code; the dimensions are chosen examples.

The helper below implements that route for a canvas whose full bitmap fills its content box. It assumes no border, padding, CSS transforms on the canvas or its ancestors, letterboxing, clipped viewport or camera transform. The event and rectangle come from the same document. Use an engine's pointer-to-world API when it already accounts for additional transforms.

function toLogical(
  clientX, clientY, rect,
  width, height
) {
  if (![clientX, clientY,
        rect.left, rect.top,
        rect.width, rect.height,
        width, height]
      .every(Number.isFinite)
      || rect.width <= 0
      || rect.height <= 0
      || width <= 0
      || height <= 0)
    return null;
  const u =
    (clientX - rect.left)
    / rect.width;
  const v =
    (clientY - rect.top)
    / rect.height;
  if (u < 0 || u >= 1
      || v < 0 || v >= 1)
    return null;
  return {
    x: u * width,
    y: v * height
  };
}

On pointerdown, pass event.clientX, event.clientY, a fresh canvas.getBoundingClientRect(), and the logical scene dimensions. Ignore null; otherwise use the returned position for hit testing.

clientX and clientY and getBoundingClientRect() share viewport coordinates. Reading the rectangle at the press accounts for scrolling. Adding a scroll offset—or substituting document-relative pageY—would mix coordinate systems again.

The helper includes the left and top edges and rejects the right, bottom and outside. It does not clamp a gutter click onto an edge target. Keep fractional results for logical hit testing.

Density belongs on the drawing side

Increasing bitmap density can sharpen the canvas without moving the target in the game. devicePixelRatio relates physical pixels to CSS pixels and can change with zoom or a different display. Multiplying the helper's output by DPR would apply a second, unwanted conversion.

For the 400 × 240 logical scene, use ctx.setTransform(canvas.width / 400, 0, 0, canvas.height / 240, 0, 0) when drawing. The actual integer bitmap dimensions account for resize rounding. setTransform replaces the scale rather than compounding it on each resize.

Keep CSS size independent of the bitmap attributes, for example with an explicit width and aspect ratio. Otherwise enlarging canvas.width can enlarge an intrinsically sized element too. Assigning canvas.width resets the context, so restore the transform and drawing styles afterward. Handle density changes even when the element's CSS size stays the same.

An iframe can resize correctly while clicks remain wrong

Rosebud's November 2024 embedding guide describes responsive iframe sizing. That handles the outer display; the pointer conversion still belongs to the document containing the canvas. Host-page coordinates cannot be paired with an inner canvas rectangle, and same-origin restrictions limit cross-origin access.

A correctly sized embed is therefore a place to repeat the target test, not evidence that the game's input handler is correct. First verify the arithmetic with the helper above:

const wide = {
  left: 100, top: 50,
  width: 800, height: 480
};
console.log(toLogical(
  300, 170, wide, 400, 240
)); // {x: 100, y: 60}
const small = {
  ...wide,
  width: 400, height: 240
};
console.log(toLogical(
  200, 110, small, 400, 240
)); // {x: 100, y: 60}
console.log(toLogical(
  900, 170, wide, 400, 240
)); // null: right edge

Then click that same target at two display sizes in the real delivery page, scroll, and try the edges and gutter. If the arithmetic passes but those presses fail, compare the measured content area with the helper's layout assumptions—especially borders, letterboxing and transforms.

I turned strings into letter arrays and started rebuilding URLs with index ranges

Fri, 09 Oct 2026 22:09:28 +0000

I was just playing with a tiny idea:

What if every string was just an array of single characters… and I could pull pieces out by index ranges to form words, paths, or API links?

That experiment became string-range-tokens — a zero-dependency ESM package that does exactly that.

The core idea

import { toTokens, sub, build } from 'string-range-tokens';

const t = toTokens('https://api.example.com/v1/users');

sub(t, 0, 4);                 // "https"
sub(t, 23, 25, [26, 31]);     // "/v1/users"
sub(t, -5, -1);               // "users"   ← negative indexes work
build(t, [0, 4], [23, 25]);   // "https/v1"

toTokens turns any string into a proper array of characters (Unicode-safe).
sub and build let you reassemble any combination of inclusive ranges.

Why bother?

Sometimes you want to:

Assemble API paths or query fragments from a shared token pool
Avoid writing the full string literal in one place
Pick substrings by position without regex
Build tiny string “templates” from a fixed alphabet
Teach indexing, ranges, and a bit of recursion in a playful way

It’s not encryption (never hide real secrets with it). It’s just a clean, lightweight way to work with strings as letter arrays.

Extra powers

`plan` – find the ranges that rebuild a target

const pool = toTokens('the quick brown fox');
const ranges = plan(pool, 'brew');
build(pool, ...ranges); // "brew"

`scatter` / `gather` – seeded shuffle + reconstruct

const { pool, key } = scatter('/api/orders', 7);
gather(pool, key); // "/api/orders"

Useful for deterministic scrambling when you want both the shuffled tokens and a way to put them back together.

Install

npm i string-range-tokens

Or just copy the source — it’s a single file with no dependencies.

Works in Node 18+, Deno, Bun, and the browser.
Both JavaScript and TypeScript implementations are included.

CDN:

import { toTokens, sub, build, plan, scatter, gather } 
  from 'https://cdn.jsdelivr.net/npm/string-range-tokens@1.0.0/src/index.js';

Concrete Cost Calculator

Fri, 09 Oct 2026 10:27:56 +0000

Search for "concrete cost" plus a city name and you will find plenty of calculators that promise local prices. Change the city and check again: on most of them the number stays exactly the same. It is one national average with a place name attached.

I built Concrete Cost Calculator to fix that. It is a free set of concrete cost calculators for U.S. homeowners, where the estimate really moves when you change your location, and where every input shows its source and date.

The problem with most concrete calculators

Two things go wrong, and they compound.

The location is cosmetic. Labor is usually the largest part of a concrete job, and wages for cement masons vary a lot by region. A calculator that ignores that gives someone in Seattle and someone in Birmingham the same answer.

The math is linear. Most tools multiply square feet by one price per square foot. That works for a driveway. For a small pad it is badly wrong, because the crew, the truck and the forms cost about the same to bring out whether the job is 40 sq ft or 400 sq ft.

What it does

Six calculators. Concrete pad or slab, concrete by the cubic yard, concrete block walls, driveways, patios, and rebar.

Metro-level labor. Labor rates come from public federal wage data for 393 U.S. metro areas. Pick your metro or enter a ZIP code, and the estimate updates.

Ranges with a breakdown. Every estimate is a low to high range with a typical value, split into line items such as setup, material, labor and subbase. The line items always add up to the total shown.

A source on every number. Each input carries one of three labels. SOURCED means it comes from public data. CALIBRATED means it was derived from public data or published cost guides. ESTIMATE means it is the site's own assumption, used only where no public figure exists. Open any line and you see where it came from and how current it is.

Share and print. An estimate can be copied as a link with all your inputs in it, or printed to bring to a contractor.

A typical session

Here is what pricing a patio looks like:

Open the patio calculator. It starts from the national baseline, then switches to your approximate metro area if it can find one.
Enter a 12 × 16 ft patio at the standard 4 inch thickness. Nationally that comes to about $1,890 to $3,760.
Enter a ZIP code to pick a metro yourself. In the Birmingham, Alabama metro the same patio comes to about $1,720 to $3,510. In the Seattle metro it is about $2,000 to $4,660.
Look at the breakdown: setup and delivery, material, labor and subbase, each with its own range.
Open the labor line to see which wage data it uses and its date. Open the setup line and you will see it labeled ESTIMATE, with an explanation.
Add options such as wire mesh, a stamped finish or removing an old slab, and watch which lines change.
Copy the link or print the estimate before you call for quotes.

The point of step 3 is the whole product. The same patio carries a high end about $1,150 apart between those two metros, and the page shows you which line causes the difference.

How the price is calculated

The model is two terms:

total = setup cost + area × (material + labor + add-ons per sq ft)

The setup cost is a fixed amount for getting a crew, a truck and forms to the site. The rest scales with the job. Thickness drives the amount of concrete, while labor depends mostly on area.

That one extra term changes the answer for small jobs a lot. For a 4 inch slab at national averages, a 20 × 20 ft slab comes to $3,010 to $5,990, or $7.53 to $14.97 per square foot. Apply that rate to an 8 × 5 ft pad and you would expect $301 to $599. The model says $1,120 to $2,230, about 3.7 times higher, because most of a small job's bill is the setup.

Labor changes by metro. Material prices are coarser: they are tracked nationally and for four broad regions, so most of the local difference comes from labor.

Stack notes for the engineers in the room

Static first. The site is built with Astro and served as static pages from Cloudflare. Every page is prerendered with the national baseline numbers, so search crawlers and first-time visitors see identical content.
Location after load. The calculator is the only interactive island on the page. Once it hydrates, it looks up your approximate metro or the ZIP code you enter, and reprices from a static rates file.
Tested against a band. An acceptance suite runs the model at fixed sizes across the national average and all 393 metros, and checks the results against a price band taken from prices people reported paying. That band is used only to check the model and never to fit it. Known gaps are written into the suite as expected failures instead of being deleted.
Open source. The cost model is published as an open-source cost model on GitHub.

Pricing

Free. No account, no email, no signup wall.

Known limits

I would rather list these than have someone find them:

For jobs past roughly 1,000 sq ft, estimates likely run low.
The setup fee is the site's own calibrated figure. No government source publishes one.
Wage data is released once a year and runs about a year behind.
About 4 in 10 U.S. ZIP codes fall outside the 393 metro areas with wage data. Those visitors see the national average, clearly labeled.
Every number is a planning range. A written quote from a licensed local contractor is the real price.

The methodology page explains how every estimate is built, with every source and limit.

A question for you

When you use an online cost estimator for anything, what makes you trust or distrust the number? Is it the source, the range, the breakdown, or something else entirely? I would like to hear what would make a tool like this more useful.

The quirk of null...Null

Thu, 08 Oct 2026 07:13:07 +0000

In English, null means nothing, but in JavaScript, that nothing can become a headache. Let's overthink it and try to understand why and how.

As per MDN,

In JavaScript, a primitive (primitive value, primitive data type) is data that is not an object and has no methods or properties.

Since null is one of the 7 primitive data types, it is not an object.

What about `typeof null`? It returns the string `"object"`.

Well, though null is a primitive data type, typeof null is not. typeof null is just a string, the result of using typeof, which is a way to check the type of any value. And typeof null === "object" is nothing but a bug that was left unsolved intentionally, so old websites wouldn't break.

So what about `typeof Number`, `typeof String` etc. returning `"function"`?

That's a different thing, and it's called a constructor). By convention, a constructor starts with a capital letter, and it is completely different from the same name with a lowercase letter because JavaScript is case-sensitive. So, "number" is completely different from Number. One is the type label typeof returns for values like 5, and the other is a constructor function.

So why does `typeof Null/Undefined` return `"undefined"`?

It's easy to mix things up as a beginner, but there is no such thing in JavaScript as Null or Undefined with a capital N/U. They are undeclared names, and typeof doesn't throw an error on undeclared names.

typeof Null;        // "undefined"  (undeclared name; typeof doesn't throw)
Null;               // ReferenceError: Null is not defined

Separately, null & undefined have no constructor function or wrapper object. That's also why property access on them fails instead of autoboxing:

null.toString();       // TypeError
undefined.toString();  // TypeError

So what did we learn from this article? Literally nothing aka null.

Coder Legion - Recent posts tagged javascript

🧩 JavaScript Promises Inside Promises: The Hidden Bugs, Execution Flow and How to Fix Them

1. First, let's reproduce the bug

The buggy implementation

What JavaScript actually does

The fix: return the Promise

2. What is a Promise, really?

3. What happens when a Promise is inside another Promise?

Pattern A: Returning a Promise from another Promise

Pattern B: Creating a Promise but not returning it

A complete execution-order example

4. Nested .then() callbacks vs. Promise chaining

5. The missing return: a small mistake with several consequences

Case 1: The next step starts too early

Case 2: Errors don't propagate through the expected chain

Case 3: The caller receives a result too early

6. Is this bug specific to Promises, or does it also happen with async/await?

Incorrect async/await implementation

Correct implementation

A useful rule

7. Error handling: .catch() vs. try/catch

Promise-based error handling

The equivalent async/await approach

Should you always rethrow an error?

8. Promise vs. async/await: which should you use?

Scenario A: Sequential operations

Scenario B: Several independent operations

Scenario C: Independent operations where partial results matter

Scenario D: You want a Promise chain without an async function

A practical decision guide

9. One real-world decision: should the email block registration?

Option A: Email is part of the required workflow

Option B: Registration should succeed independently of email delivery

10. How to debug confusing Promise execution flow

Step 1: Add logs at the boundaries

Step 2: Inspect every asynchronous callback

Step 3: Inspect the returned value

Step 4: Check rejection paths, not just successful execution

Step 5: Write down the intended dependency

11. Common misconceptions worth remembering

12. A final debugging challenge

Conclusion

Embeds: Putting a Live NitroIDE Playground Inside Your Docs

One parameter turns a share link into an embed

Where this actually belongs

The details that make an embed feel native, not bolted on

The limits, stated plainly

Why this matters more than a nicer code block

Don't Let Your Node.js Apps Drown: A Guide to Backpressure

What is Backpressure?

The Fast-Food Kitchen Analogy

Why Backpressure Matters in Tech

Implementation in Node.js

The Takeaway

Your Tests Are Green and Prove Nothing: 4 Signs You're Testing the Mock

1. You Mocked the Thing You Are Testing

2. You Assert the Calls, Not the Outcome

3. The Fake Database Only Says Yes

4. Snapshots Approved Without Reading

The 60-Second Sabotage Check

What to Mock, and What Not To

The Rule

Building a static blog with Sitelo, one function per page

Step 1: one page is one function

Step 2: a layout is just another function

Step 3: posts from JSON files

Step 4: fresh comments on a static page

Step 5: let the build check your work

Building it with a coding agent

What we built, and when not to use it

Your Next.js redirect() Silently Does Nothing Because It's Inside a try/catch

The Code That Causes It

Why It Breaks

Why It Is Hard to Catch

Fix 1: Keep redirect() Outside the try Block

Fix 2: Rethrow If You Must Catch Everything

Fix 3: Do Not Use Catch-All to Control Flow

Where Else This Bites

Quick Checklist

The Rule

4. Nested `.then()` callbacks vs. Promise chaining

5. The missing `return`: a small mistake with several consequences

6. Is this bug specific to Promises, or does it also happen with `async/await`?

Incorrect `async/await` implementation

7. Error handling: `.catch()` vs. `try/catch`

The equivalent `async/await` approach

8. Promise vs. `async/await`: which should you use?

Scenario D: You want a Promise chain without an `async` function