Forem: kcsujeet

Generating self-Contained HTML Snapshots Without Puppeteer

kcsujeet — Wed, 25 Feb 2026 22:42:49 +0000

The Problem

I needed to preserve a webpage exactly as it appears (layout, styles, images, and all) in a format that stayed responsive across device sizes. That last part was the dealbreaker. Screenshots and PDFs are static, fixed-dimension artifacts. They don't reflow. On a phone, you're pinch-zooming into a blurry mess. On a tablet, the layout doesn't adapt. For our use case, the snapshot had to behave like a real web page: fluid, responsive, and readable on any screen.

That immediately ruled out the screenshot/PDF route. Services like ResPack, Browserless.io, and Cloudflare's browser rendering API are built around producing flat outputs. Puppeteer itself can capture HTML via page.content(), but it gives you a raw DOM with the same broken external dependencies and missing CSSOM styles. None of these tools solve the real problem: producing a single self-contained file that actually renders correctly on its own.

So I went down a different path: capturing the actual DOM and inlining every asset into one self-contained HTML file. It was harder than I expected, and the roadblocks were genuinely bizarre.

Starting Point: Raw HTML Is Just a Skeleton

My first instinct was simple: run document.documentElement.outerHTML in the browser console, save the result, and open it in a new tab.

const html = document.documentElement.outerHTML

The result was barely recognizable. Inline styles and any CSS written directly in <style> tags survived, but all externally linked stylesheets, images, and fonts were missing. The page was mostly unstyled, and I couldn't tell yet whether that accounted for all the breakage. Raw HTML gives you the bone structure, but nothing else. I needed a way to capture the skin too.

The Frontend's Job: Extracting Hidden CSS

I figured I could write a quick JavaScript function to grab all the <link rel="stylesheet"> tags, fetch their contents, and replace them with inline <style> blocks.

// Naive approach: fetch each stylesheet and inline it
// (Note: forEach doesn't await async callbacks, so this is a simplified illustration)
document.querySelectorAll('link[rel="stylesheet"]').forEach(async (link) => {
  const response = await fetch(link.href)
  const css = await response.text()
  const style = document.createElement('style')
  style.textContent = css
  link.replaceWith(style)
})

I wrote the script, captured the DOM, saved the file, and opened it.

Still broken. The layout was completely gone.

The Invisible CSS Problem

The culprit was MUI (Material UI), which uses Emotion for styling under the hood. Emotion is a CSS-in-JS library that dynamically generates styles at runtime based on component props and state. In production, it injects these styles using CSSStyleSheet.insertRule, which writes directly into the browser's CSS Object Model (CSSOM) without ever placing readable CSS text into the DOM.

Because these styles never exist as text content in the DOM, my HTML extraction completely missed them. The fix was to manually crawl document.styleSheets, extract those hidden rules, and inject them into a physical <style> tag before capturing anything.

// Extract styles that were injected via CSSStyleSheet.insertRule
let css = ''
const sheets = Array.from(document.styleSheets)
for (const sheet of sheets) {
  if (sheet.href) continue // skip external sheets
  const rules = Array.from(sheet.cssRules || [])
  for (const rule of rules) {
    css += rule.cssText + '\n'
  }
}

Then Came CORS

With the CSS problem solved, I tried adding fetch calls to grab images and convert them to base64 strings right there in the browser.

// Attempt to inline images from the frontend
// (Note: forEach doesn't await async callbacks, so this is a simplified illustration)
document.querySelectorAll('img').forEach(async (img) => {
  const response = await fetch(img.src)
  const blob = await response.blob()
  const reader = new FileReader()
  reader.onloadend = () => { img.src = reader.result }
  reader.readAsDataURL(blob)
})

The console lit up red with CORS errors. The browser was blocking my attempts to read image data from our external S3 buckets.

This was the moment I realized the frontend couldn't do everything. Its job was to prepare a clean DOM (including those hidden styles) and then hand it off to a backend server that could fetch external assets without CORS restrictions.

The Code: Preparing the DOM

Here's the complete TypeScript function. It extracts the hidden dynamic styles, strips out unwanted scripts and UI elements, and produces a clean HTML string ready for the server:

/**
 * Iterates over document.styleSheets to find rules injected by libraries
 * like MUI, Emotion, or Styled Components.
 */
const extractCssFromStyleSheets = (): string => {
  let css = ''
  const sheets = Array.from(document.styleSheets)

  for (const sheet of sheets) {
    // Skip external stylesheets (these will be handled by the backend)
    if (sheet.href) continue

    try {
      const rules = Array.from(sheet.cssRules || [])
      for (const rule of rules) {
        css += rule.cssText + '\n'
      }
    } catch (e) {
      // Silently fail for cross-origin sheets that deny access
      console.warn('Cannot access cssRules for stylesheet', e)
    }
  }

  return css
}

export const prepareDomForSnapshot = (ignoreSelectors: string[] = []): string => {
  // 1. Clone the document to avoid mutating the live page
  const domElement = document.documentElement.cloneNode(true) as HTMLElement

  // 2. Remove scripts (we want a static snapshot, not a running app)
  domElement.querySelectorAll('script').forEach((script) => script.remove())

  // 3. Remove favicons (they reference external URLs that would fail silently
  //    in a standalone file, and aren't visually relevant to the snapshot)
  domElement
    .querySelectorAll('link[rel="icon"], link[rel="shortcut icon"]')
    .forEach((el) => el.remove())

  // 4. Remove specific UI elements we don't want captured (e.g., '.chat-widget')
  if (ignoreSelectors.length > 0) {
    ignoreSelectors.forEach((selector) => {
      domElement.querySelectorAll(selector).forEach((el) => el.remove())
    })
  }

  // 5. Extract CSSOM styles and physically inject them into the head
  const dynamicCss = extractCssFromStyleSheets()
  if (dynamicCss) {
    const style = document.createElement('style')
    style.setAttribute('data-snapshot', 'dynamic-css')
    style.textContent = dynamicCss
    domElement.querySelector('head')?.appendChild(style)
  }

  // 6. Return the full HTML string including DOCTYPE
  return '<!DOCTYPE html>\n' + domElement.outerHTML
}

At this point I had a clean HTML string with all the hidden styles baked in. Time to hand it to the server.

The Backend's Job: Inlining Everything Else

I pushed the remaining work to a Ruby on Rails service. Since the backend makes plain HTTP requests, CORS is irrelevant.

The plan was straightforward: parse the prepared HTML, fetch external stylesheets and replace <link> tags with inline <style> blocks, then fetch images and convert them to base64 data URIs.

There was one catch I hadn't anticipated: base64 encoding increases file size by roughly 33%. A 1MB image becomes about 1.33MB when inlined. With multiple images on a page, the snapshot would balloon quickly. To keep things manageable, I added a resizing step that scales images down to a max width of 800px before encoding. This brought the file sizes back to something reasonable without noticeably hurting visual quality.

I also ran into intermittent failures where some images would come out broken. Network hiccups, slow responses, or transient errors during download or processing meant that occasionally an image just wouldn't make it. I added a retry mechanism that wraps the entire pipeline (fetch, resize, and base64 encode) with a few attempts per image to handle this gracefully.

I wrote the service, ran it, and opened the result. The CSS worked perfectly, the layout was an exact match. But as I scrolled down, every single image was broken.

The Active Storage Redirect Trap

This one took serious debugging. Our app uses Rails Active Storage for image uploads. In the DOM, image src attributes look like /rails/active_storage/blobs/redirect/.... When a browser hits that URL, Rails validates the request and issues an HTTP 302 redirect to a short-lived, signed S3 URL where the actual binary lives.

My Ruby HTTP client wasn't a browser. It hit the URL, received the 302, and stopped. Even configuring Faraday to follow redirects didn't fully solve it, since those Active Storage endpoints sometimes rely on session cookies or specific headers that a server-to-server background job doesn't have.

The fix was to bypass Active Storage's redirect controller entirely. Before fetching an image, I check whether the URL matches an Active Storage path and, if so, resolve it directly to the underlying authenticated S3 URL.

The Code: The Complete Inlining Service

Here's the full Ruby service. It handles stylesheet fetching, image resizing, and the Active Storage bypass. I also added concurrent-ruby to fetch assets in parallel and keep generation fast:

require 'nokogiri'
require 'base64'
require 'addressable/uri'
require 'faraday'
require 'concurrent-ruby'
require 'mini_magick'

class DomSnapshotService
  # Configuration
  TIMEOUT_SECONDS = 10
  USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36'
  THREAD_POOL_SIZE = 8

  # Image Optimization (base64 adds ~33% size overhead, so resize first)
  DEFAULT_MAX_WIDTH = 800
  DEFAULT_MAX_HEIGHT = 800
  DEFAULT_QUALITY = 80
  DEFAULT_FORMAT = 'jpeg'
  MAX_RETRIES = 3

  def initialize(html, base_url:)
    @doc = Nokogiri::HTML.parse(html)
    @base_url = base_url
  end

  def call
    @http_client = build_http_client

    inline_stylesheets!
    convert_images_to_base64!
    remove_script_tags!

    "<!DOCTYPE html>\n" + @doc.to_html
  end

  private

  def full_absolute_url(href)
    return nil if href.blank?
    return href if href.start_with?('data:')

    begin
      url = Addressable::URI.join(@base_url, href).to_s

      # Bypass Active Storage redirects for direct S3 URLs
      if url.include?('/rails/active_storage/')
        url = resolve_direct_s3_url(url)
      end

      url
    rescue Addressable::URI::InvalidURIError, URI::Error
      nil
    end
  end

  def resolve_direct_s3_url(active_storage_url)
    # Implementation depends on your app. Generally:
    # blob_signed_id = extract_id_from_url(active_storage_url)
    # blob = ActiveStorage::Blob.find_signed!(blob_signed_id)
    # blob.url(expires_in: 5.minutes)
    active_storage_url # Placeholder
  end

  def build_http_client
    Faraday.new do |faraday|
      faraday.options.timeout = TIMEOUT_SECONDS
      faraday.options.open_timeout = TIMEOUT_SECONDS
      faraday.headers['User-Agent'] = USER_AGENT
      faraday.adapter Faraday.default_adapter
    end
  end

  def fetch_content(url)
    return nil unless url
    return nil if url.start_with?('data:')

    response = @http_client.get(url)
    response.success? ? response.body : nil
  rescue => e
    Rails.logger.warn("Snapshot Warning: Failed to fetch #{url} - #{e.message}")
    nil
  end

  def inline_stylesheets!
    links = @doc.css('link[rel="stylesheet"]').to_a
    return if links.empty?

    execute_in_threads(links) do |link|
      href = full_absolute_url(link['href'])
      css = fetch_content(href)

      if css
        sanitized_css = css.gsub(/@font-face\s*{[^}]*}/, '')
        { node: link, content: sanitized_css, success: true }
      else
        { node: link, success: false }
      end
    end.each do |result|
      if result[:success]
        style = Nokogiri::XML::Node.new('style', @doc)
        style.content = result[:content]
        result[:node].replace(style)
      end
    end
  end

  def convert_images_to_base64!
    images = @doc.css('img').to_a
    return if images.empty?

    execute_in_threads(images) do |img|
      src_url = full_absolute_url(img['src'])

      if src_url&.start_with?('data:')
        { node: img, content: src_url, success: true }
      else
        result = with_retries(MAX_RETRIES) do
          image_data = fetch_content(src_url)
          raise "Failed to download #{src_url}" unless image_data

          processed = process_and_resize(image_data)
          raise "Failed to process #{src_url}" unless processed

          processed
        end

        if result
          { node: img, content: result, success: true }
        else
          { node: img, success: false }
        end
      end
    end.each do |result|
      if result[:success]
        result[:node]['src'] = result[:content]
        result[:node].remove_attribute('srcset')
        result[:node].remove_attribute('loading')
      end
    end
  end

  def remove_script_tags!
    @doc.css('script').each(&:remove)
  end

  def execute_in_threads(items, &block)
    pool = Concurrent::ThreadPoolExecutor.new(
      min_threads: 1,
      max_threads: [THREAD_POOL_SIZE, items.size].min,
      max_queue: 0
    )

    promises = items.map do |item|
      Concurrent::Promise.execute(executor: pool) { block.call(item) }
    end

    promises.map(&:value)
  ensure
    pool&.shutdown
    pool&.wait_for_termination(5)
  end

  def with_retries(max_attempts)
    attempts = 0
    begin
      attempts += 1
      yield
    rescue => e
      if attempts < max_attempts
        sleep(0.5 * attempts)
        retry
      end
      Rails.logger.warn("Snapshot Warning: Failed after #{max_attempts} attempts - #{e.message}")
      nil
    end
  end

  def process_and_resize(image_data)
    image = MiniMagick::Image.read(image_data)
    image.resize "#{DEFAULT_MAX_WIDTH}x#{DEFAULT_MAX_HEIGHT}>"
    image.format DEFAULT_FORMAT
    image.quality DEFAULT_QUALITY

    base64 = Base64.strict_encode64(image.to_blob)
    image.destroy!

    "data:image/#{DEFAULT_FORMAT};base64,#{base64}"
  rescue => e
    Rails.logger.warn("Snapshot Warning: Image processing failed - #{e.message}")
    nil
  end
end

Wiring It Up

Here's the controller that ties everything together:

def create
  raw_html = params[:html]
  base_url = request.base_url

  snapshot_html = DomSnapshotService.new(raw_html, base_url: base_url).call

  filename = "snapshots/#{Time.current.to_i}_#{SecureRandom.hex(4)}.html"
  S3_BUCKET.object(filename).put(
    body: snapshot_html,
    content_type: 'text/html'
  )

  render json: { url: S3_BUCKET.object(filename).public_url }
end

Why This Was Worth the Effort

What I love about this approach is that the result is a single HTML file with zero external dependencies. The browser loads one file with no additional network requests for stylesheets, fonts, or images. It's a moment frozen in time. External references break as assets get deleted or CDNs change, but an inlined snapshot stays exactly as it was.

And unlike screenshots or PDFs, these snapshots remain fully responsive. They look right on every screen size. If you ever need a PDF or image later, you can generate one from this HTML, but you can't go the other direction. You can't generate responsive HTML from a flat image.

The journey to get here was full of bizarre debugging sessions (invisible CSS rules, silent CORS failures, redirect traps) but each one taught me something real about how browsers render pages and how little of that rendering lives in the DOM you can see.

If you're building something similar, my advice boils down to this: let the frontend prepare the DOM (including those hidden styles), offload asset fetching to the server (where CORS can't touch you), and inline everything so the result is truly self-contained.

Thanks for reading! If you have thoughts, improvements, or questions, drop a comment below. 👋

Enforcing React Hook Form Best Practices with Custom Biome Rules

kcsujeet — Thu, 22 Jan 2026 22:21:46 +0000

React Hook Form (RHF) is the gold standard for managing forms in React. Its performance rely on a subscription model that avoids unnecessary re-renders. However, it's easy to accidentally introduce patterns that trigger full-form re-renders on every keystroke.

I recently migrated my projects from ESLint to Biome and I needed to bring over several custom rules used to prevent these performance pitfalls. While Biome's GritQL engine is powerful, I found that the documentation for creating custom rules in Biome is still limited.

In this post, I'll share how to use Biome to catch three common RHF anti-patterns before they reach production. This might be helpful to you if you are also navigating the same migration or looking to enforce RHF best practices automatically.

The Custom Rules

First, create a file named react-hook-form-rules.grit in your project root.

Here is the complete GritQL pattern I wrote. It looks for three specific scenarios that degrade RHF performance:

any {
  // Rule 1: Prevent direct formState access on the methods object
  `$m1.formState` where {
    register_diagnostic(
      span=$m1, 
      message="Don't access formState from methods object. Use useFormState hook instead for better performance."
    )
  },

  // Rule 2: Discourage .watch() in favor of useWatch()
  `$m2.watch($a1)` where {
    register_diagnostic(span=$m2, message="Use of .watch() method from react-hook-form is not allowed. Consider using useWatch() instead.")
  },
  `watch($a2)` where {
    register_diagnostic(span=$a2, message="Direct use of watch() from react-hook-form is not allowed. Consider using useWatch() instead.")
  },

  // Rule 3: Prevent the 'methods' object from entering dependency arrays
  `methods` as $m3 where {
    $m3 <: within `[$d1]` as $a3 ,
    $a3 <: within any {
      `useEffect($_, $a3)`,
      `useMemo($_, $a3)`,
      `useCallback($_, $a3)`
    } ,
    register_diagnostic(
      span=$m3, 
      message="React Hook Form 'methods' object should not be in dependency array. Destructure it and include only specific methods needed."
    )
  }
}

Let's break down why these rules exist.

1. The formState Proxy Trap

The Anti-Pattern:
Accessing formState directly from the useForm return object.

// ❌ Bad
const { formState, register } = useForm();
// OR
const methods = useForm();
console.log(methods.formState.errors);

Why it's bad:
RHF uses a proxy to track which fields you are observing. If you destructure formState or access it at the root level of your component, RHF has to assume you are subscribed to all changes. This often leads to the entire component re-rendering whenever any validation state changes.

The Fix:
Use the useFormState hook. This isolates the subscription to that specific hook call, allowing you to re-render only the components that actually need the error messages, rather than the whole form.

// ✅ Good
const { control } = useForm();
const { errors } = useFormState({ control });

2. watch vs. useWatch

The Anti-Pattern:
Using the imperative watch function to monitor input changes.

// ❌ Bad
const { watch } = useForm();
const firstName = watch("firstName");

Why it's bad:
Similar to the issue above, watch triggers a re-render of the host component (the component calling useForm) whenever the watched field changes. If you have a large form, typing in the "First Name" field shouldn't force the "Address" section to re-render.

The Fix:
useWatch is a hook specifically designed for performance. It subscribes to the store internally and can be used in child components to isolate re-renders to just that child.

// ✅ Good
const firstName = useWatch({ control, name: "firstName" });

I have written a separate detailed article on this topic: React Hook Form: Understanding watch vs useWatch.

3. The Dependency Array Hazard

The Anti-Pattern:
Passing the entire methods object into a useEffect or useCallback.

// ❌ Bad
const methods = useForm();

useEffect(() => {
  methods.reset();
}, [methods]); // <--- This is dangerous

Why it's bad:
While useForm tries to be stable, the methods object itself contains many properties. If you depend on the whole object, you risk infinite loops or effect firings whenever any part of the internal form state updates (depending on how the object reference is handled in your specific RHF version).

The Fix:
Destructure the methods and only include the specific function you need. RHF guarantees stability for functions like setValue, getValues, and reset.

// ✅ Good
const { reset } = useForm();

useEffect(() => {
  reset();
}, [reset]);

Configuring Biome

Once you have created your .grit file, integrating it is incredibly simple. You don't need to inline complex logic strings into your JSON config.

Just reference the file in your biome.json plugins array:

{
  "plugins": ["./react-hook-form-rules.grit"]
}

(Note: Custom GritQL rules are an advanced feature in Biome. Ensure you are on a compatible version).

This keeps your configuration clean while moving code review feedback from "after the PR is open" to "the moment you type the code."

Conclusion

Tools like Biome are exciting not just because they are fast (and Biome is incredibly fast), but because they allow us to codify team knowledge.

Instead of writing "Please use useWatch" on pull requests for the 100th time, we can bake that knowledge into the toolchain, saving everyone mental energy and keeping our forms buttery smooth.

Have you written any custom rules for your projects yet? Let me know in the comments!

ilamy Calendar v1.0.0: Resource Calendar is Here! 🎉

kcsujeet — Mon, 13 Oct 2025 20:06:55 +0000

Big news! ilamy Calendar v1.0.0 is officially released! 🎉

A few months ago, I introduced ilamy Calendar as a React-first calendar library built for developers who wanted full control over styling without fighting CSS. The response has been incredible, and today I'm excited to share v1.0.0 with its most requested feature:

What's New in v1.0.0

Resource Calendar - The Star of v1.0.0

Resource Calendar lets you visualize and manage events across multiple resources in a timeline layout. Perfect for:

Conference room scheduling
Equipment booking systems
Team member availability
Vehicle fleet management
Any resource-based scheduling scenario

Here's how simple it is to use:

import { IlamyResourceCalendar } from '@ilamy/calendar';
import type { Resource, ResourceCalendarEvent } from '@ilamy/calendar';
import dayjs from 'dayjs';

const resources: Resource[] = [
  {
    id: 'room-a',
    title: 'Conference Room A',
    color: '#3B82F6',
    backgroundColor: '#EFF6FF',
  },
  {
    id: 'room-b',
    title: 'Conference Room B',
    color: '#EF4444',
    backgroundColor: '#FEF2F2',
  },
  {
    id: 'room-c',
    title: 'Conference Room C',
    color: '#8B5CF6',
    backgroundColor: '#F5F3FF',
  },
];

const events: ResourceCalendarEvent[] = [
  {
    id: 'event-1',
    title: 'Team Meeting',
    start: dayjs('2025-10-15T09:00:00'),
    end: dayjs('2025-10-15T10:00:00'),
    uid: '[email protected]',
    resourceId: 'room-a', // Assigned to Room A
  },
];

function MyResourceCalendar() {
  return (
    <IlamyResourceCalendar
      resources={resources}
      events={events}
      initialView="week"
      renderResource={(resource) => (
        <div className="flex items-center gap-2 p-2">
          <div className="flex flex-col">
            <span className="font-semibold">{resource.title}</span>
            <span className="text-xs text-gray-500">Available</span>
          </div>
        </div>
      )}
    />
  );
}

Key capabilities:

Timeline view with resources as rows
Month, Week, and Day views for resource scheduling
Drag and drop events between resources and time slots
Cross-resource events using resourceIds array
Custom resource rendering with colors and styling
Works seamlessly with recurring events and all calendar features

That's it for major new features! v1.0.0 is primarily about bringing Resource Calendar to production along with various improvements and refinements throughout the library.

Powerful Features (Quick Reminder)

If you haven't tried ilamy Calendar yet, here's what it already had before v1.0.0:

RFC 5545 Recurring Events

Full RRULE support powered by rrule.js:

Daily, weekly, monthly, yearly patterns
Complex rules (last Friday of month, every 2 weeks, etc.)
Exception dates (EXDATE) and modified instances
Proper timezone handling
Compatible with Google Calendar, Outlook, and other iCalendar apps

Drag & Drop

Intuitive interactions across all views:

Move events between dates and time slots
Resize events to change duration
Collision detection
Smooth animations

Multiple Views

Four built-in views:

Month - Traditional calendar grid
Week - 7-day timeline with hourly slots
Day - Single day with full detail
Year - Annual overview

Internationalization

100+ locales via dayjs
Configurable week start day
Full timezone support
Proper date/time formatting per locale

Complete Styling Control

Zero CSS shipped by default
Bring your own design system
Tailwind CSS integration
Custom event rendering
CSS variables for theming

iCalendar Export

RFC 5545 compliant .ics file generation
Export events to Google Calendar, Outlook, Apple Calendar
Proper recurring event handling in exports

Upgrading to v1.0.0

Good news! v1.0.0 is fully backward compatible. If you're already using ilamy Calendar, upgrading is seamless:

npm install @ilamy/calendar@latest
# or
yarn upgrade @ilamy/calendar
# or
pnpm update @ilamy/calendar
# or
bun update @ilamy/calendar

What you get:

✅ All existing code continues to work
✅ Access to the new Resource Calendar component
✅ Slightly smaller bundle size
✅ Performance improvements under the hood
✅ No breaking changes

To use the new Resource Calendar:

// Just import the new component - everything else stays the same!
import { IlamyResourceCalendar } from '@ilamy/calendar';
import type { Resource, ResourceCalendarEvent } from '@ilamy/calendar';

// Your existing IlamyCalendar usage remains unchanged

That's it! No migration required, just upgrade and optionally start using the new Resource Calendar when you need it.

Real-World Use Cases

Since the initial release, developers have been using ilamy Calendar for:

🏢 Enterprise Apps

Meeting room booking systems
Employee scheduling platforms
Project timeline management

🏥 Healthcare

Patient appointment systems
Doctor availability calendars
Facility resource management

📚 Education

Class schedules
Assignment calendars
Resource booking (labs, equipment)

🎫 Events & Hospitality

Venue booking systems
Event planning tools
Restaurant reservation systems

💼 Professional Services

Client appointment scheduling
Consultant availability
Service booking platforms

What's Next?

Future Ideas:

Agenda/List view for events
Print-friendly layouts
Conflict detection UI
Mobile gesture support
Improved accessibility (ARIA, keyboard nav)
Virtual scrolling for massive event lists
Native integrations (Google Calendar, Outlook)
Recurring event templates
Event templates and presets
Advanced search and filtering

Community & Support

Thank you to everyone who:

⭐ Starred the repo (44 stars and counting!)
🐛 Reported bugs and issues
💡 Suggested features
📖 Improved documentation
🔧 Contributed code

Get involved:

If you found this useful, consider giving the project a ⭐ on GitHub. Every star helps more developers discover the project!

Debugging Next.js App Router Navigation Lag: Dynamic Routes and Prefetching

kcsujeet — Thu, 28 Aug 2025 13:24:23 +0000

The Problem

Last month, our team started getting complaints that our Next.js application felt sluggish. Users were experiencing slower navigation between pages, even though we hadn't made any major changes recently. The app was noticeably slower in production environments.

So I started investigating this performance regression and what I discovered was a subtle but impactful issue with how Next.js handles prefetching for dynamic routes.

The Investigation

Our application uses Next.js 15 with App Router, and we were using the standard Link component which handles prefetching automatically. Initially, this seemed fine—prefetching should make navigation faster, not slower. So why were we seeing the opposite?

The breakthrough came when I examined our recent routing changes. We had recently implemented internationalization by nesting all our routes under a dynamic locale segment:

Before: /about, /products, /contact
After:  /[locale]/about, /[locale]/products, /[locale]/contact

This seemingly innocent change had a massive impact on our app's performance, and here's why.

Understanding Next.js Prefetching Behavior

According to the Next.js documentation, Next.js handles prefetching differently for static and dynamic routes:

Route Type	Prefetched	What Gets Cached
Static Routes	Yes, full route	Entire page until app reload
Dynamic Routes	No, unless `loading.js` present	Only layout shell for 30 seconds

The key insight: When you make routes dynamic (like adding [locale]), Next.js can no longer prefetch the full page content automatically.

As the Next.js documentation explains: "By skipping or partially prefetching dynamic routes, Next.js avoids unnecessary work on the server for routes the users may never visit. However, waiting for a server response before navigation can give the users the impression that the app is not responding."

This is exactly what we were experiencing—our users felt like the app wasn't responding because navigation required server responses instead of using prefetched content.

The Root Cause

By nesting all our pages under /[locale]/, we inadvertently converted every single page in our application from static to dynamic. This meant:

No automatic prefetching of page content
Only layout prefetching when loading.js is present
Slower navigation as pages had to be fetched on-demand

The Solution

I implemented a comprehensive approach to restore fast navigation:

1. Changed from `Opt-Out` to `Opt-In` Prefetching Strategy

First, we fundamentally changed our prefetching approach. By default, Next.js uses an opt-out strategy where prefetching is enabled automatically (prefetch=null). However, given our dynamic routing structure and the performance issues it caused, we switched to an opt-in strategy.

Understanding the prefetch prop values is crucial here:

"auto" or null (default): Prefetch behavior depends on whether the route is static or dynamic
true: The full route will be prefetched for both static and dynamic routes
false: Prefetching will never happen both on entering the viewport and on hover

So, we created a wrapper component that disables prefetching by default:

// components/Link.jsx - Our custom Link wrapper
import NextLink from 'next/link'

export default function Link({ prefetch = false, ...props }) {
  return <NextLink prefetch={prefetch} {...props} />
}

This approach gave us granular control over which pages should be prefetched, rather than relying on Next.js's automatic behavior which wasn't working effectively for our dynamic routes.

2. Explicit Prefetching for High-Traffic Pages

For our most frequently accessed pages, we enabled explicit prefetching by setting prefetch={true} on the Link components.

// Before (using default Next.js Link)
import Link from 'next/link'
<Link href="/en/products">Products</Link>

// After (using our custom wrapper with explicit prefetch)
import Link from '@/components/Link'  // Our custom wrapper
<Link href="/en/products" prefetch={true}>Products</Link>

Important: Prefetching only works in production, so you won't see the performance benefits during development.

3. Added Loading States

I created loading.js files for our dynamic route segments to enable layout prefetching:

// app/[locale]/loading.js
export default function Loading() {
  return (
    <div className="animate-pulse">
      <div className="h-8 bg-gray-200 rounded mb-4"></div>
      <div className="space-y-2">
        <div className="h-4 bg-gray-200 rounded w-3/4"></div>
        <div className="h-4 bg-gray-200 rounded w-1/2"></div>
      </div>
    </div>
  )
}

The Results

The impact was immediate and dramatic:

Navigation felt instant again ⚡
Performance metrics improved significantly 📊
Better user experience across the entire app 🎉

Additional Optimizations

On top of the core fixes that resolved our immediate performance issues, we implemented several additional optimization strategies to further enhance navigation speed and reduce unnecessary network overhead. These techniques help you fine-tune prefetching behavior for different types of pages and user interactions:

Use Explicit Prefetching Strategically

// High-traffic pages
<Link href="/[locale]/checkout" prefetch={true}>Checkout</Link>

// Lower-priority pages
<Link href="/[locale]/terms" prefetch={false}>Terms</Link>

Implement Comprehensive Loading States

// Create loading.js at each dynamic segment level
app/[locale]/loading.js
app/[locale]/products/loading.js  
app/[locale]/products/[id]/loading.js

Optimize Data-Heavy Pages with Hover-Based Prefetching

For pages displaying large datasets (like record tables), automatic prefetching can become a performance bottleneck. We discovered this when implementing a records table that displayed 25 items per page—Next.js was attempting to prefetch all 25 record detail pages simultaneously, causing excessive network traffic.

The Problem with Large Lists:

// This creates 25 simultaneous prefetch requests!
{records.map(record => (
  <Link key={record.id} href={`/records/${record.id}`}>
    {record.title}
  </Link>
))}

The Solution - Hover-Triggered Prefetching:

'use client'
import Link from '@/components/Link'
import { useState } from 'react'

export function HoverPrefetchLink({ href, children }) {
  const [shouldPrefetch, setShouldPrefetch] = useState(false)

  return (
    <Link
      href={href}
      prefetch={shouldPrefetch ? true : false}
      onMouseEnter={() => setShouldPrefetch(true)}
    >
      {children}
    </Link>
  )
}

// Usage in your records table
{records.map(record => (
  <HoverPrefetchLink key={record.id} href={`/records/${record.id}`}>
    {record.title}
  </HoverPrefetchLink>
))}

This approach reduces initial network overhead while still providing fast navigation for pages users actually intend to visit.

Key Takeaways

Dynamic routes change prefetching behavior fundamentally - Even a single dynamic segment can affect your entire application's performance
Locale-based routing has performance implications - Consider the trade-offs when implementing i18n with dynamic routes
Explicit prefetching gives you control - Don't rely solely on automatic prefetching for critical user journeys
Loading states are crucial for dynamic routes - They enable layout prefetching and provide better UX
Monitor performance after routing changes - Seemingly small changes can have outsized impacts
Optimize for your specific use case - Use hover-based prefetching for data-heavy pages to avoid unnecessary network requests

Conclusion

Performance regressions can be sneaky, especially when they stem from architectural decisions that seem beneficial on the surface. Our internationalization implementation improved the user experience for global users but inadvertently broke our prefetching strategy.

The lesson here is clear: understand how your routing architecture affects Next.js's built-in optimizations. Dynamic routes aren't inherently bad, but they require different performance strategies than static routes.

By combining explicit prefetching with proper loading states and smart optimization strategies for different page types, we were able to restore—and even improve upon—our original navigation performance while maintaining the benefits of our localized routing structure.

Comparing Javascript test frameworks: Jest vs Vitest vs Bun

kcsujeet — Tue, 12 Aug 2025 23:25:55 +0000

If you’ve ever felt like running your tests is like waiting for water to boil, you’re not alone. I’ve been there. For my latest project, ilamy Calendar (intro article here), I wanted to keep things simple and stick to one toolchain for everything: runtime, package manager, and testing. That led me to try Bun’s built-in test runner.

What happened next surprised me: I wrote some tests, ran the tests and saw my tests run instantly. I’m talking milliseconds.

I’ve used Jest before. I’ve used Vitest too. Jest, in particular, has always felt slow to me — slow enough to grab coffee while waiting for the test suite to finish. But I wanted real numbers to see just how much faster Bun was, so I ran a little experiment.

Disclaimer: These benchmarks are only the findings from my specific project. They might differ in your own setup, and the fastest option for me may not be the fastest for you. Everything here is based on my personal experience and opinions.

The Experiment

I set up Jest, Vitest, and Bun test in the same project. Then I ran:

The same 223 tests
Across 14 files
Ten times for each runner

No code changes, just swapping the runner.

The Results

Here’s the average runtime across those ten runs:

Test Runner	Avg. Time (seconds)
Bun Test	~2.15s
Vitest	~5.3s
Jest	~9.8s

And here’s the raw data for the curious:

Jest:

Run #	Time (s)
1	12.689
2	10.299
3	9.521
4	9.392
5	9.542
6	10.265
7	9.469
8	9.670
9	9.584
10	9.374

Lowest: 9.374 | Highest: 12.689 | Average: 9.980

Vitest:

Run #	Time (s)
1	5.930
2	5.250
3	5.320
4	5.130
5	5.130
6	5.180
7	5.450
8	5.160
9	5.270
10	5.300

Lowest: 5.130 | Highest: 5.930 | Average: 5.312

Bun Test:

Run #	Time (s)
1	2.160
2	2.130
3	2.200
4	2.130
5	2.130
6	2.130
7	2.160
8	2.140
9	2.210
10	2.140

Lowest: 2.130 | Highest: 2.210 | Average: 2.153

The speed difference is so significant that even small projects benefit immediately. When you scale up to hundreds or thousands of tests, the time saved becomes massive.

Try It Yourself — Realtime Demo

I’ve set up a live demo where you can run tests with Jest, Vitest, and Bun side-by-side and see the difference for yourself:

💻 Demo and Source code: View on CodeSandbox

Migrating to Bun Test

If you’re using Jest or Vitest, migrating is surprisingly easy:

Install Bun

curl -fsSL https://bun.sh/install | bash

Run your tests

bun test

Most of your Jest-style tests will work out of the box. If you use custom mocks, setup files, or advanced Jest features, you might need minor adjustments, but Bun’s compatibility is improving rapidly.

Final Thoughts

I went into this expecting Bun to be fast. I didn’t expect it to be this fast. If you care about developer productivity, fast feedback loops, and less time watching spinners, you owe it to yourself to try Bun’s test runner.

It might just ruin other test runners for you.

Introducing ilamy Calendar: A Modern React Calendar Built for Developers

kcsujeet — Mon, 21 Jul 2025 20:16:36 +0000

TL;DR: ilamy Calendar is a React-first calendar library that gives you complete control over styling while providing powerful features like drag-and-drop, multiple views, and timezone support out of the box.

Try the live demo → | View docs →

Ever tried integrating a calendar into a React app and ended up wrestling with CSS overrides, fighting JavaScript APIs that weren't built for React, or struggling to customize interactions without breaking things? I've been there too many times.

That's why I built ilamy Calendar — a modern, React-first calendar library that actually feels like it belongs in your React codebase.

The Problem with Existing Solutions

FullCalendar: Powerful but not React-first
React Big Calendar: Good React integration but limited customization options
Commercial solutions: Expensive and often overkill for most use cases
CSS nightmares: Spending more time fighting default styles than building features

I wanted something that was:

React-first (built for React)
Fully customizable (without CSS hacks)
TypeScript native for better DX
Modern build tools (built with Bun)
Zero opinions about your design system

Features at a Glance

Drag and Drop Support
Month / Week / Day / Year views
Fully customizable via props
Zero CSS shipped — full design control
Locale and timezone aware
Custom event rendering
Built with Bun from end to end

Quick Start

Get up and running in under 2 minutes:

# Using Bun
bun add @ilamy/calendar

# Or npm/pnpm/yarn
npm install @ilamy/calendar
pnpm install @ilamy/calendar
yarn add @ilamy/calendar

Basic Setup

import { IlamyCalendar } from '@ilamy/calendar'

function MyApp() {
  const events = [
    {
      id: '1',
      title: 'Team Meeting',
      start: new Date('2024-01-15T10:00:00'),
      end: new Date('2024-01-15T11:00:00'),
      color: '#3b82f6'
    }
  ]

  return <IlamyCalendar events={events} />
}

Configure Tailwind CSS

One of the bold choices I made: not shipping any CSS. If you’ve ever wrestled with a library’s default styles, you know how frustrating that can be.

Instead, ilamy Calendar gives you clean, unstyled structure which you can style using your own Tailwind config. You need to register the source path in your CSS file to ensure all component styles are included:

/* In your main CSS file (e.g., globals.css) */
@source "../node_modules/@ilamy/calendar/dist";

This tells Tailwind to scan the calendar package for classes and include them in your build. This is especially important since node_modules are typically ignored by Tailwind by default.

Day.js Plugin Configuration

Important: If you're using Day.js in your project (i.e. installed in your package.json dependencies), you'll need to extend it with required plugins:

import dayjs from 'dayjs';
import isSameOrAfter from 'dayjs/plugin/isSameOrAfter.js';
import isSameOrBefore from 'dayjs/plugin/isSameOrBefore.js';
import timezone from 'dayjs/plugin/timezone.js';
import utc from 'dayjs/plugin/utc.js';

dayjs.extend(isSameOrAfter);
dayjs.extend(isSameOrBefore);
dayjs.extend(timezone);
dayjs.extend(utc);

This prevents "isSameOrBefore is not a function" errors when using the calendar.

That's it! You now have a fully functional calendar.

Advanced Features & Examples

Custom Event Rendering

Take full control over how events look:

<IlamyCalendar
  events={events}
  renderEvent={(event) => (
    <div className="px-2 py-1 bg-gradient-to-r from-blue-500 to-purple-600 text-white rounded-md shadow-sm">
      <div className="font-semibold">{event.title}</div>
      <div className="text-xs opacity-90">{event.description}</div>
    </div>
  )}
/>

Event Handlers & Interactions

Handle user interactions with ease:

<IlamyCalendar
  events={events}
  onEventClick={(event) => {
    // Open event details modal
    openEventModal(event)
  }}
  onCellClick={(date) => {
    // Create new event
    createEvent(date)
  }}
  onViewChange={(view) => {
    // Track analytics or update URL
    analytics.track('calendar_view_changed', { view })
  }}
/>

Complete API Reference

Here's everything you can customize:

interface CalendarProps {
  // Core functionality
  events?: CalendarEvent[]
  firstDayOfWeek?: 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday'

  // Event handling
  onEventClick?: (event: CalendarEvent) => void
  onCellClick?: (date: Date) => void
  onViewChange?: (view: 'month' | 'week' | 'day' | 'year') => void

  // Customization
  renderEvent?: (event: CalendarEvent) => React.ReactNode
  headerComponent?: React.ReactNode

  // Localization
  locale?: string
  timezone?: string

  // Behavior
  disableCellClick?: boolean
  disableEventClick?: boolean
  disableDragAndDrop?: boolean
  dayMaxEvents?: number

  // Styling
  stickyViewHeader?: boolean
  viewHeaderClassName?: string
}

interface CalendarEvent {
  id: string
  title: string
  start: dayjs.Dayjs | Date | string
  end: dayjs.Dayjs | Date | string
  description?: string
  color?: string
  allDay?: boolean
}

Pro Tips for Better Performance

Memoize your event renderer:

const renderEvent = useCallback((event: CalendarEvent) => <CustomEventComponent event={event} />, [])

Use stable event arrays:

const events = useMemo(() => fetchEvents(), [dependency])

Built with Modern Tools

Ilamy Calendar leverages the latest tools for the best developer experience:

Tool	Purpose	Why We Chose It
Bun	Package manager, bundler, test runner	Incredibly fast, all-in-one solution
TypeScript	Type safety	Better DX and fewer runtime errors
Tailwind CSS v4	Styling	Utility-first, highly customizable
Day.js	Date manipulation	Lightweight, timezone-aware
Framer Motion	Animations	Smooth, performant animations

What's Next

The roadmap is packed with exciting features:

Coming Soon

Resource Calendar: Visualize events by resources (rooms, people, equipment)

Future Ideas

Accessibility: ARIA compliance and keyboard navigation
Performance: Virtual scrolling for large datasets
Export/Import: iCal, Google Calendar integration

Complete Documentation

Interactive Demo

GitHub Repository

Join the Community

ilamy Calendar is just getting started, and I'd love your feedback:

Found a bug? Open an issue
Have an idea? Start a discussion
Like the project? Give it a star on GitHub
Share it! Help other React developers discover Ilamy

Thanks for reading, and happy building! 🚀

P.S. If you end up using ilamy Calendar in production, I'd love to hear about it. : )

Google Calendar-Style Time Picker for MUI and shadcn/ui

kcsujeet — Sun, 29 Jun 2025 01:29:55 +0000

Introduction

Today I tackled a small but annoying problem: time pickers that make you click way too much.

If you’ve ever used the default time pickers in popular UI libraries like Material-UI (MUI) or shadcn/ui, you probably know what I mean. They’re not terrible—but they’re definitely not fast.

You have to:

Select the hour.
Select the minutes.
Select AM or PM.
Sometimes even seconds.

All of those steps are separate—and it’s just too many clicks (or too much typing) for something that should be quick and intuitive.

Why I Built This

There’s one time picker I actually love: the one in Google Calendar.

In Google Calendar, you just start typing “9:30” or “2pm,” and it immediately suggests times. No extra clicks, no separate dropdowns. It feels natural.

Since I couldn’t find an equivalent in MUI or shadcn/ui, I decided to build one myself.

What It Does

This time picker:

✅ Lets you type any time (e.g., “9:30”, “14:15”, “2pm”)

✅ Instantly shows matching options in a dropdown

✅ Works seamlessly with MUI and shadcn/ui

✅ Requires zero configuration—just copy the component and use it

How I Built It

I started by prototyping the component with Lovable. Honestly, Lovable did a pretty great job generating most of the initial code. I refined the code a little bit and added a bunch of tests to ensure reliability.

Usage

You don’t need to install any packages—just grab the code:

GitHub Repo:

👉 https://github.com/kcsujeet/autocomplete-timepicker

Available components:

MuiAutocomleteTimePicker.tsx (Material-UI)
ShadcnAutocomleteTimePicker.tsx (shadcn/ui)

Live Demo

You can try it out here:

🔗 Live Demo

Final Thoughts

This was a small side quest that made a big difference in user experience for me. If you also find default time pickers frustrating, give this a try in your project.

I’d love to hear any feedback or suggestions!

Happy building—and fewer clicks! 🚀

JIRA Avatars Not Showing in Chrome on Mac? Here’s What Worked for Me

kcsujeet — Tue, 15 Apr 2025 23:52:12 +0000

One of the most frustrating parts of debugging isn’t always the bug itself—it’s when you can’t find a single working solution anywhere. That’s exactly what happened to me when JIRA avatars stopped showing in Chrome on my Mac.

It's not a huge issue but it's so irritating and it affected my flow so much. I scoured the entire internet trying to find a solution but to no avail. Atlassian's own documentation? Useless. Community forums? A bunch of unanswered threads or people saying “same issue here.” It honestly felt like even the Atlassian team had no idea what was going on.

I also tried asking ChatGPT and Deepseek but nothing there either. Alas, after trying all the usual tricks and hitting a wall, I finally found a fix that worked—and it was surprisingly simple.

🧠 The Setup

Device: MacBook (latest macOS)
Browser: Chrome (latest version)
Issue: Avatars not showing on the JIRA board (but everything else loaded fine)
Tried:
- Refreshing ✅
- Clearing cache/cookies ✅
- Chrome update ✅
- Disabling extensions ✅
- Incognito mode ✅
- Shouting at my screen (also ✅)

Still nothing.

🎯 The Fix: DNS

Turns out, the culprit was DNS resolution.

Chrome was defaulting to the DNS provider to the one provided by OS and for some reason the avatar domains were not being resolved by it.

Once I manually changed the DNS provider in Chrome’s settings, avatars magically reappeared.

Here’s how you can try this fix:

🔧 Steps (Chrome on Mac)

Open Chrome
Go to: chrome://settings/security
Scroll down to Advanced → Use secure DNS
Enable it if not enabled already
On Select DNS Provider dropdown, choose a known good one, like: Google or Cloudflare
Refresh JIRA

Boom. Avatars back.

💬 Final Thoughts

It’s such a tiny bug, but man does it break your flow. If you’re stuck seeing blank faces on your JIRA board and nothing else works—give DNS a shot.

How to Handle Date and Time Correctly to Avoid Timezone Bugs

kcsujeet — Tue, 25 Feb 2025 01:25:40 +0000

Introduction

Working with date and time in software applications can be surprisingly tricky. A date that makes perfect sense in one timezone may be completely incorrect in another. Timezone-related bugs are a nightmare for developers. They often lead to various issues that result in confused, frustrated users and even potential financial losses.

In this guide, I’ll share the learnings I’ve gathered while navigating these challenges over the years and show you how you can avoid common pitfalls when working with date and time in your applications.

What We Will Cover
✅ Why Do Timezone Issues Occur
✅ Real-world examples of timezone-related problems
✅ How to test timezone differences in your browser
✅ Best practices for handling date-time correctly
✅ Best practices for displaying date-time in the front end
✅ Conclusion

Why Do Timezone Issues Occur?

Storing Only Dates Can Cause Issues

One of the most common sources of timezone-related issues is the way dates are stored. Many systems store dates in the format YYYY-MM-DD (e.g., 2025-01-01). However, this format does not contain all the information necessary to correctly interpret the date, especially information about time zones.

For example, consider an event management system:

A user in Tokyo schedules an online event for 2025-01-01.
The system stores just 2025-01-01 without specifying a timezone.
A user in Toronto sees 2025-01-01 but assumes it is their local date.
Due to timezone differences, when it's January 1 in Tokyo, it is still December 31 in Toronto.
This could lead to the Toronto user missing the event entirely because they interpreted the date incorrectly.

Storing Only Time Can Also Be a Problem

Similarly, many systems store time separately, using formats like HH:MM (e.g., 10:00) or as seconds since midnight (eg. 36000). However, without the date and timezone context, this can cause serious issues.

For example, consider a global meeting scheduling app:

A user in Tokyo schedules a meeting at 10:00 (i.e 10 am).
The system stores just 10:00 without specifying the timezone.
A user in Toronto sees 10:00 but assumes it is their local time, which is incorrect.
The meeting happens at the wrong time for the Toronto user, leading to confusion.

This demonstrates why both date and time should always be stored with timezone information.

Real-world examples of timezone-related problems

Let's look at some more examples to understand the timezone issues better.

Example 1: Server Misinterprets the Date

Let's say you have a SaaS app with a subscription-based service.
A user in Toronto (UTC-5) signs up to your app and sets a subscription renewal date as Jan 1, 2025.
So, the value 2025-01-01 is sent to the server and stored in the database.
The user expects their subscription to renew at midnight in Toronto on 2025-01-01.
However, the server is in Tokyo (JST) and thus, the server interprets 2025-01-01 in JST timezone, which is 14 hours earlier than Toronto time—meaning it's still 2024-12-31 in Toronto.
As a result, the user will think they were charged before the set date and may lose trust in the service.

Code Illustration:
Server-Side (Ruby):

# Server stores renewal date as "2025-01-01" in JST
renewal_date = Date.parse('2025-01-01')

puts "Renewal Date (JST): #{renewal_date}" 
# Output: "Renewal Date (JST): 2025-01-01"

Client-Side (JavaScript):

// Server sends renewal date as "2025-01-01" (JST)
const renewalDate = "2025-01-01";

// Browser parses it in the user's local time zone (Toronto, UTC-5)
const renewalDateLocal = new Date(renewalDate);
console.log("Local Renewal Date:", renewalDateLocal); 
// Output: Tue Dec 31 2024 19:00:00 GMT-0500 (Eastern Standard Time)

Example 2: Client Misinterprets the Date

Let's say you have an app where students can register for an examination online.
A registration deadline of 2025-01-01 is scheduled for an examination.
The server, which is in Tokyo (JST), processes the deadline as midnight JST.
A student is in Toronto (UTC-5), which is 14 hours behind JST.
The student's browser gets the deadline and parses it in Toronto timezone (EST), so the student sees 7:00 PM on Dec 31, 2024.
However, the backend will stop accepting applications at midnight JST, which is still 10:00 AM on Dec 31, 2024, in Toronto.
Therefore, when the student tries to register for the exam at 11:00 am on Dec 31, 2024 (Toronto time), thinking they’re within the deadline, the system rejects the registration since the deadline has already passed in JST.

Code Illustration:

Server-Side (Ruby):

# Server stores deadline as "2025-01-01" in JST
deadline = Date.parse('2025-01-01')

puts "Deadline (JST): #{deadline}" 
# Output: "Deadline (JST): 2025-01-01"

Client-Side (JavaScript):

// Server sends deadline as "2025-01-01" (JST)
const deadline = "2025-01-01";

// Browser parses it in the student's local time zone (Toronto, UTC-5)
console.log(new Date(deadline)); 
// Output: Tue Dec 31 2024 19:00:00 GMT-0500 (Eastern Standard Time)

How to test timezone differences in your browser

You can change the timezone for a specific tab in your browser using Chrome DevTools.

Open Developer Tools (F12 or Ctrl + Shift + I on Windows/Linux, Cmd + Option + I on macOS).
Go to the Sensors: Three dots at top right → More tools → Sensors.
Under the location dropdown, select a different location (e.g., San Francisco or Tokyo).
Run the following JavaScript snippet in the browser console:

console.log("Current Local Time:", new Date());

console.log("2025-01-01 in local timezone:", new Date('2025-01-01'));

Try these same values with different timezones and see what outputs you get.

Best practices for handling date-time correctly

The golden rule for handling either date or time is to always store date and time in UTC in ISO8601 format. ISO8601 is a standard date-time format that ensures consistency across different systems and timezones. By using this format, your application will be able to represent dates and times accurately, regardless of where your users are located.

The full ISO8601 format looks like this: YYYY-MM-DDTHH:mm:ssZ

YYYY: Year (4 digits)
MM: Month (2 digits, from 01 to 12)
DD: Day of the month (2 digits, from 01 to 31)
T: Separator between date and time
HH: Hour (2 digits, from 00 to 23, in 24-hour format)
mm: Minute (2 digits, from 00 to 59)
ss: Second (2 digits, from 00 to 59)
Z: UTC time (indicates zero timezone offset) or a specific timezone offset like +09:00 for Tokyo, or -05:00 for Toronto.

In the format YYYY-MM-DDTHH:mm:ssZ, the Z indicates that the time is in UTC (Coordinated Universal Time). The Z can also be replaced with the appropriate timezone offset.

Examples of ISO8601 with Different Timezones:

UTC (Coordinated Universal Time):
- 2025-01-01T00:00:00Z
- The Z at the end indicates that this time is in UTC (i.e., zero offset).
Tokyo (Japan Standard Time - JST, UTC +9 hours):
- 2025-01-01T00:00:00+09:00
- The +09:00 offset indicates that this time is 9 hours ahead of UTC (Japan Standard Time).
Toronto (Eastern Standard Time - EST, UTC -5 hours):
- 2025-01-01T00:00:00-05:00
- The -05:00 offset indicates that this time is 5 hours behind UTC (Eastern Standard Time).

Converting date to ISO format:

On the Server Side (Ruby):

Always use timestamps (for both date and time fields) instead of just dates or times. In Ruby, it's best to use the Time (instead of Date or DateTime) class for precise timestamps, as it includes both the date and the time, along with timezone support.

require 'time'

# Create a time object with a specific date and time
birthday = Time.new 

# Convert to ISO8601 format
iso_string = birthday.iso8601
puts iso_string 
# Output: "2025-01-01T00:00:00+00:00"

On the Client Side (JavaScript):

Again, always use timestamps. When sending date or time to the back-end, use ISO8601 format. In JavaScript, the Date object has a .toISOString() method that converts it to an ISO8601 string.

Example:

// Get current date and time
const deadline = new Date();

// Convert to ISO8601 format
const isoString = deadline.toISOString();
console.log(isoString); 
// Output: "2025-01-01T00:00:00.000Z"

A great feature of modern browsers is that when you send a Date object in an HTTP request (like in a JSON payload), the browser automatically converts it to ISO8601 format using .toISOString.

Example with HTTP Request:

const birthDay = new Date();
fetch('https://dummyjson.com/users/add', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    firstName: 'Anil',
    lastName: 'Devkota',
    age: 25,
    birthDay // automatically converted to ISO format
  })
})
.then(res => res.json())
.then(console.log);

If you open the browser’s network tab, you'll see a payload that looks something like this.

{
    age: 25
    birthDay: "2025-01-01T00:00:00.000Z"
    firstName: "Anil"
    lastName: "Devkota"
}

NOTE: The .toISOString() method always converts the time to UTC, regardless of the local timezone of the user. This means that if the user is in a different timezone (e.g., Toronto, Eastern Standard Time, UTC-5), the output of .toISOString() will be in UTC rather than their local time.

Example:
Let's say the local time is 2025-01-01T05:00:00 in Toronto (Eastern Standard Time). When you use .toISOString(), the time will be converted to UTC (which will be 2025-01-01T10:00:00.000Z).
const localTime = new Date('2025-01-01T05:00:00')
const isoString = localTime.toISOString()
console.log(isoString) // Output: `2025-01-01T10:00:00.000Z`
This is perfectly fine. This is what we want, a UTC timestamp. Don't get confused.

But how does ISO8601 format help to avoid timezone issues?

You might be wondering why this format prevents timezone issues. To illustrate this, let’s revisit the examination deadline example.

The Issue:

The server (in Tokyo, JST) sets the deadline as midnight JST (2025-01-01).
A student in Toronto (UTC-5) receives this but their browser displays it in local time as 7:00 PM on Dec 31, 2024.
However, the system stops accepting applications at 10:00 AM on Dec 31, 2024 (Toronto time)—midnight JST.
The student, thinking they have until 11:59 PM Toronto time, registers too late and gets rejected.

The Fix: Use ISO8601 with UTC

By storing and sending 2024-12-31T15:00:00Z (midnight JST in UTC), the client correctly converts it to local time.

Server-Side (Ruby)

require 'time'

# Store deadline with explicit UTC time
deadline = Time.new.getutc

puts deadline.iso8601  
# Output: "2024-12-31T15:00:00Z"

Client-Side (JavaScript)

// Server sends "2024-12-31T15:00:00Z"
const deadline = "2024-12-31T15:00:00Z";

// When creating a new Date object, the browser converts UTC to local time
console.log(new Date(deadline));  
// Output in Toronto (UTC-5): Tue Dec 31 2024 10:00:00 GMT-0500 (Eastern Standard Time)

Why This Works

When you pass an ISO8601 UTC string (2024-12-31T15:00:00Z) into new Date(), the browser automatically converts it to the user’s local time zone.

So, instead of assuming 7:00 PM local time, the browser correctly displays the deadline as 10:00 AM on Dec 31, 2024 (Toronto time). This prevents confusion and ensures users see the actual deadline in their timezone.

This behaviour is the opposite of .toISOString(), which always converts dates to UTC. Using both correctly ensures consistent storage and accurate timezone conversions, preventing misunderstandings.

Best practices for displaying date-time in the front end

There's no single best way to display date-time in the front-end as it largely depends on product requirements and team consensus. Different applications have different needs, whether it's prioritizing localization, clarity, or usability.

That said, I really like how Stripe handles this. Instead of just showing a raw timestamp, Stripe displays a text value, and when you hover over it, a tooltip appears with the same timestamp in three different time zones:

Local Time – The user's browser time zone.
UTC – A universal reference, useful for consistency.
Organization Time Zone – A user-selected time zone, typically set during sign-up or in account settings.

This approach strikes a great balance between readability and flexibility, making it easy for users across different time zones to interpret the date-time correctly.

You can use libraries like dayjs or date-fns to format date to different timezones.

Conclusion

Handling timezones correctly is essential to avoid errors and inconsistencies in applications. By following these best practices—storing timestamps in UTC, using timezone-aware objects, and converting for display—you can ensure a smooth experience for users worldwide.

🚀 Final Takeaways:

Always work with timestamps instead of just date or time.
Always use full ISO8601 format (i.e.YYYY-MM-DDTHH:mm:ssZ).

React Hook Form: Understanding watch vs useWatch

kcsujeet — Tue, 04 Feb 2025 14:12:29 +0000

Introduction

When working with forms in React, handling state efficiently is crucial to maintaining good performance. React Hook Form (RHF) provides two powerful utilities, watch and useWatch, to track form values in real-time. However, many developers struggle to understand their differences and when to use each.

When I worked with RHF, I thought both do the same thing and one is a replacement of other. The RHF documentation also doesn't go into depth explaining the differences between these two. It simply say " useWatch behaves similarly to the watch API, however, this will isolate re-rendering at the custom hook level" and that's it.

I knew this meant useWatch gives better performance but I wasn't sure in what way or by how much. I also wasn't aware how important the difference between these two is. This was until I hit a bottleneck in a very large form.

So, in this article I will layout my findings and we'll explore:
✅ Key differences between them
✅ Real-world examples
✅ When to use watch vs useWatch for better performance

Let's dive in! 🚀

Differences between watch and useWatch:

The main difference that we are concerned with is performance. According to the docs:

watch : This API will trigger re-render at the root of your app or form.
useWatch : Behaves similarly to the watch API, however, this will isolate re-rendering at the custom hook level.

Now, what does this mean? … Let's see the differences using real world examples.

Real-world examples:

watch triggers a re-render the root level i.e. at the component where you initialize the form.

Check it out yourself: https://codesandbox.io/p/sandbox/how-watch-works-gvllkd

useWatch only triggers a re-render in the component where you call the hook.

Check it out yourself: https://codesandbox.io/p/sandbox/how-usewatch-works-x2szsd

When to Use watch vs useWatch?

As a rule of thumb, always use useWatch. The performance difference between these two is insignificant in small forms with just a few inputs such as a login form. However, in large forms with several inputs such as date-pickers, selects, comboboxes etc, the performance difference is clearly noticeable, especially in older devices.

So, does this mean you should never use watch? Absolutely not, there's always a case where one tool might be useful over the other. However, I have yet to come across such situation in a real world scenario. So, I'd suggest stick to useWatch unless you find it not fit to your use case.

Conclusion

Both watch and useWatch are essential tools in React Hook Form, but one re-renders entire form and the other re-renders just the component where it's used.

🚀 Final Takeaways:

Use useWatch almost always.
Use watch when you are absolutely sure it's what you need.

Forem: kcsujeet

Generating self-Contained HTML Snapshots Without Puppeteer

The Problem

Starting Point: Raw HTML Is Just a Skeleton

The Frontend's Job: Extracting Hidden CSS

The Invisible CSS Problem

Then Came CORS

The Code: Preparing the DOM

The Backend's Job: Inlining Everything Else

The Active Storage Redirect Trap

The Code: The Complete Inlining Service

Wiring It Up

Why This Was Worth the Effort

Enforcing React Hook Form Best Practices with Custom Biome Rules

The Custom Rules

1. The formState Proxy Trap

2. watch vs. useWatch

3. The Dependency Array Hazard

Configuring Biome

Conclusion

ilamy Calendar v1.0.0: Resource Calendar is Here! 🎉

What's New in v1.0.0

Resource Calendar - The Star of v1.0.0

Powerful Features (Quick Reminder)

RFC 5545 Recurring Events

Drag & Drop

Multiple Views

Internationalization

Complete Styling Control

iCalendar Export

Upgrading to v1.0.0

Real-World Use Cases

What's Next?

Community & Support

Debugging Next.js App Router Navigation Lag: Dynamic Routes and Prefetching

The Problem

The Investigation

Understanding Next.js Prefetching Behavior

The Root Cause

The Solution

1. Changed from Opt-Out to Opt-In Prefetching Strategy

2. Explicit Prefetching for High-Traffic Pages

3. Added Loading States

The Results

Additional Optimizations

Use Explicit Prefetching Strategically

Implement Comprehensive Loading States

Optimize Data-Heavy Pages with Hover-Based Prefetching

Key Takeaways

Conclusion

Comparing Javascript test frameworks: Jest vs Vitest vs Bun

The Experiment

The Results

Jest:

Vitest:

Bun Test:

Try It Yourself — Realtime Demo

Migrating to Bun Test

Final Thoughts

Introducing ilamy Calendar: A Modern React Calendar Built for Developers

The Problem with Existing Solutions

Features at a Glance

Quick Start

Basic Setup

Configure Tailwind CSS

Day.js Plugin Configuration

Advanced Features & Examples

Custom Event Rendering

Event Handlers & Interactions

Complete API Reference

Pro Tips for Better Performance

Built with Modern Tools

What's Next

Coming Soon

Future Ideas

Join the Community

Google Calendar-Style Time Picker for MUI and shadcn/ui

Introduction

Why I Built This

What It Does

1. Changed from `Opt-Out` to `Opt-In` Prefetching Strategy