Forem: Richard Lau

I Built a PDF-to-QBO Converter: From a 480-Search Keyword to a Niche SaaS

Richard Lau — Sat, 21 Mar 2026 08:10:51 +0000

The Hook

I've shipped several AI-powered tool sites over the past year. Some got traction; others barely moved the needle. While digging through Google Trends one evening, I stumbled on a keyword that most people would ignore: "pdf to qbo converter" — roughly 480 monthly searches.

The search volume was tiny. But the CPC? North of $20. That usually means one thing: real demand, underserved supply.

Why This Niche?

QBO (QuickBooks Online file format) is what millions of US small businesses and bookkeepers use to import bank transactions into QuickBooks. QuickBooks dominates small business accounting in North America — something like 80%+ market share. Banks, however, hand you PDFs. QuickBooks wants structured data. The languages don't match.

Who feels the pain?

Small business owners — monthly bank statement imports for bookkeeping
Bookkeepers and accountants — processing PDFs for multiple clients
Freelancers — QuickBooks for taxes, receipts and statements in PDF form

Manual copy-paste is tedious and error-prone. The alternative — PDF → Excel → CSV → QuickBooks — has strict formatting rules: remove standalone zeros, no numbers in description, specific column headers, uniform date format. One wrong cell and the import fails.

Existing tools are mostly desktop software: clunky, Windows-only, or require a sales call for pricing. A focused web tool that "just works" felt like an opportunity.

The Technical Problem (and Why It's Non-Trivial)

At first glance, "PDF to QBO" sounds simple. It's not.

QBO files are OFX-based — a structured text format (think XML with specific tags). Each transaction needs <DTPOSTED>, <TRNAMT>, <FITID>, <NAME>, etc. QuickBooks rejects imports if tags are malformed, dates are wrong, or FITIDs (unique transaction IDs) are duplicated.

The real challenge: PDF parsing. Banks don't publish their PDF layouts. Chase looks different from Bank of America from Wells Fargo. Some PDFs are text-based (you can select and copy); others are scanned images and need OCR. A rule-based parser for Chase won't work for BofA without a separate parser.

I chose a parser registry pattern: each bank gets its own parser implementing a BankPdfParser interface — canParse(text) to detect the bank from PDF text, and parse(text) to extract transactions. The system tries parsers in order, uses the first match, then feeds the result into a shared QBO generator. Adding a new bank = new parser + one line in the registry.

What I Built

A simple web app: upload PDF → auto-detect bank → parse → generate QBO → download. No signup required for the core flow. No desktop app. Just a browser.

Stack

Next.js — full-stack, API routes for conversion
pdf-parse — extracts text from PDFs (Node.js)
Cloudflare R2 — store PDFs and QBO files, CDN delivery
Stripe — ready for subscriptions (Pro/Enterprise with 3-day trial); not gating conversions yet

The Chase Parser (First Bank)

Chase credit card statements have recognizable patterns: "ACCOUNT SUMMARY", "Opening/Closing Date", "Payment Credits", "Purchases", "New Balance". The parser uses regex to find these blocks, extract dates in YYYY-MM-DD, and map amounts to the right OFX fields. For credit cards, we generate synthetic transactions (payment credits, purchases) from the summary when the full transaction list isn't in a parseable table. It's not perfect for every Chase variant, but it covers the common paperless statement format.

QBO Generation

The output must be valid OFX: correct header, <BANKACCTFROM>, <BANKTRANLIST>, and each <STMTTRN> with <TRNTYPE>, <DTPOSTED>, <TRNAMT>, <FITID>, <NAME>. Amounts need two decimals. FITIDs must be unique (we use date + sequence). Get any of this wrong and QuickBooks silently fails or duplicates entries.

Competitive Landscape

The space isn't empty. DocuClipper and similar tools offer bank statement OCR, invoice processing, and QBO export — 10,000+ businesses, robust features. But they're generalists: bank statements, invoices, receipts, reconciliation, APIs. Pricing is page-based and scales up.

I'm betting on focus: one job, done well. PDF bank statement → QBO. Simpler UX, simpler pricing (conversion count, not pages). For bookkeepers handling a few accounts per month, a dedicated tool might be enough. No need for the full DocuClipper suite.

The MVP Mindset

I'm not gating conversions behind login or subscription yet. Why? I want to observe first.

Does anyone use it? Where do they come from? Which banks do they need? What breaks? Adding auth and paywalls before I have data would be premature. Build → Measure → Learn. The core loop works; the next step is learning from real usage before investing in Bank of America parsers, batch processing, or conversion limits.

What I Learned

Small keywords can be valuable. 480 searches/month sounds like nothing. But if those are accountants willing to pay $20+/month for a focused tool, it adds up. High CPC often signals underserved demand.
Niche beats broad. One well-solved problem (PDF → QBO) is better than a generic "do everything" product. Easier to ship, easier to explain.
MVP means "minimum" for a reason. Ship the core flow. Observe. Then invest. Don't overbuild before you know people care.
Parser architecture matters. The registry pattern makes adding banks straightforward. Each bank is an isolated module — no giant if/else chain.
Format specs are strict. QBO/OFX has rules. Read the docs, test with real QuickBooks imports. A working converter is 90% format correctness.

Roadmap (If It Works)

Bank of America parser — second biggest US bank by demand
Wells Fargo, Capital One — expand coverage
Conversion history — for logged-in users
Usage-based limits — Pro/Enterprise tiers once we validate demand
Scanned PDFs — OCR for image-based statements (higher complexity)

Try It

The tool is live at pdf-to-qbo.com. If you have Chase bank statement PDFs (or know someone who does), give it a spin. I'd love to hear what works, what doesn't, and which banks to support next.

Built with Next.js, pdf-parse, Cloudflare R2, Stripe, and a lot of regex. Happy to answer questions or swap indie hacker stories.

Using Cron on Vercel: Tips, Tricks, and Examples

Richard Lau — Sun, 14 Dec 2025 07:04:00 +0000

Using Cron on Vercel: Tips, Tricks, and Examples

Cron jobs are fundamental yet powerful tools in the world of serverless computing. These time-based task schedulers are essential for developers building modern web applications, enabling them to automate recurring tasks without managing servers or infrastructure.

This article aims to demystify Cron jobs on Vercel. It provides a comprehensive guide explaining what Vercel Cron is, how it works, and most importantly, how to use it to automate repetitive tasks in your serverless applications.

Whether your goal is to set up automatic data synchronization, run scheduled scripts at specific times, or automate maintenance tasks for your serverless applications, this article will show you how Vercel Cron can make it all possible. Let's get started!

What is Vercel Cron?

Vercel Cron is a serverless cron job scheduler that allows you to run scheduled tasks in your Vercel deployments. Unlike traditional cron jobs that run on a server, Vercel Cron executes your functions on a schedule, leveraging Vercel's serverless infrastructure.

It's most commonly used for automating maintenance tasks, data processing, API health checks, and periodic data synchronization, but it can be used for any purpose that requires regular, scheduled execution of serverless functions.

How Vercel Cron Works

At its core, Vercel Cron operates as a serverless scheduling service. When you configure a cron job, Vercel automatically invokes your specified API route or Serverless Function at the scheduled intervals.

The system checks your cron configuration and triggers the appropriate endpoints when the scheduled time arrives. This naturally leads to the next key aspect of setting up Vercel Cron operations—configuration files.

Cron Configuration Files

The vercel.json file is the heart of the Vercel Cron job scheduling system. This configuration file contains the cron schedule definitions that tell Vercel when and how to execute your scheduled functions.

Each cron job entry in the vercel.json file represents a separate scheduled task and includes information about when the job should run, along with the path to the function or API route that should be executed.

Essentially, Vercel Cron configurations are defined in your project's vercel.json file, which should be placed at the root of your project directory. Here's what you need to know about the key details.

Cron Syntax Basics

Cron jobs in Vercel are defined using standard cron syntax, which consists of five time fields followed by the path to your function or API route. The basic syntax for a Vercel Cron job is as follows:

{
  "crons": [
    {
      "path": "/api/cron",
      "schedule": "0 0 * * *"
    }
  ]
}

Understanding the Cron Schedule Structure

Let's break down the schedule component:

Minute (0-59)
This field specifies the minute at which the command will run. It can be a value between 0 and 59. For example, setting it to 0 will run the command at the start of the hour.

Hour (0-23)
The hour field is specified in 24-hour format. It determines the hour of day for execution. For example, setting it to 14 will run the command at 2:00 PM.

Day of Month (1-31)
This field specifies the day of the month when the command will run. It can be any value from 1 to 31, depending on the number of days in the month. For example, setting it to 1 will run the command on the first day of each month.

Month (1-12)
The month field determines the month when the command should execute. It can be a value from 1 (January) to 12 (December). For example, setting it to 12 will execute commands in December.

Day of Week (0-6)
This field specifies which day of the week the command should run. It can be a value from 0 (Sunday) to 6 (Saturday). For example, setting the command to 5 will run every Friday.

Special Characters in Cron Syntax

Cron syntax also supports special characters to specify more complex scheduling patterns:

Asterisk (*): Represents "every" time unit. For example, * in the hour field means "every hour."

Comma (,): Allows specifying a list of values. For example, 1,3,5 in the day-of-week field means "run on Monday, Wednesday, and Friday."

Hyphen (-): Specifies a range of values. For example, 9-17 in the hour field means "from 9 AM to 5 PM."

Slash (/): Specifies increments. For example, */10 in the minute field means "every 10 minutes."

When working with complex cron schedules, online tools like Crontab Calculator provide powerful web-based interfaces to help you visualize and validate your cron expressions before implementing them in your Vercel configuration.

Setting Up Vercel Cron Jobs

Now that we've covered the theory, let's get into the exciting part: creating your first Vercel Cron job.

Basic Setup

To create a Vercel Cron job, you'll need to:

Create or update yourvercel.json file in the root of your project
Add acrons array with your scheduled jobs
Create the API route or Serverless Function that will be executed

Example: Creating a Daily Cleanup Job

Let's create a simple example that runs a cleanup task every day at midnight:

Step 1: Create vercel.json

{
  "crons": [
    {
      "path": "/api/cleanup",
      "schedule": "0 0 * * *"
    }
  ]
}

Step 2: Create the API Route

In your pages/api/cleanup.js (for Pages Router) or app/api/cleanup/route.ts (for App Router):

// app/api/cleanup/route.ts
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  // Verify the request is from Vercel Cron
  const authHeader = request.headers.get('authorization')
  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return NextResponse.json({ message: 'Unauthorized' }, { status: 401 })
  }

  try {
    // Your cleanup logic here
    console.log('Running daily cleanup...')

    // Example: Delete old database records
    // await deleteOldRecords()

    return NextResponse.json({ 
      success: true, 
      message: 'Cleanup completed',
      timestamp: new Date().toISOString()
    })
  } catch (error) {
    console.error('Cleanup failed:', error)
    return NextResponse.json(
      { success: false, error: error.message },
      { status: 500 }
    )
  }
}

Step 3: Set Environment Variable

Add CRON_SECRET to your Vercel environment variables for security.

Creating Multiple Cron Jobs

You can define multiple cron jobs in a single vercel.json file:

{
  "crons": [
    {
      "path": "/api/daily-backup",
      "schedule": "0 2 * * *"
    },
    {
      "path": "/api/hourly-sync",
      "schedule": "0 * * * *"
    },
    {
      "path": "/api/weekly-report",
      "schedule": "0 9 * * 1"
    }
  ]
}

Security Best Practices

Protecting Your Cron Endpoints

Since cron endpoints are accessible via HTTP, it's crucial to secure them. Vercel provides a VERCEL_CRON_SECRET header that you can verify:

export async function GET(request: Request) {
  const authHeader = request.headers.get('authorization')

  if (authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response('Unauthorized', { status: 401 })
  }

  // Your cron job logic
}

Alternatively, you can check for the x-vercel-cron header:

if (request.headers.get('x-vercel-cron') !== '1') {
  return new Response('Unauthorized', { status: 401 })
}

Common Cron Job Examples

Here are several practical examples covering most common scheduling scenarios:

Every Minute

{
  "path": "/api/health-check",
  "schedule": "* * * * *"
}

Every Hour

{
  "path": "/api/hourly-task",
  "schedule": "0 * * * *"
}

Every Day at Midnight

{
  "path": "/api/daily-task",
  "schedule": "0 0 * * *"
}

Every Day at 2 AM

{
  "path": "/api/nightly-backup",
  "schedule": "0 2 * * *"
}

Every Monday at 9 AM

{
  "path": "/api/weekly-report",
  "schedule": "0 9 * * 1"
}

Every 15th of the Month

{
  "path": "/api/monthly-billing",
  "schedule": "0 0 15 * *"
}

Every 5 Minutes

{
  "path": "/api/frequent-check",
  "schedule": "*/5 * * * *"
}

Every Hour During Business Hours (9 AM - 5 PM)

{
  "path": "/api/business-hours-sync",
  "schedule": "0 9-17 * * *"
}

Every Tuesday and Thursday at 4 AM

{
  "path": "/api/biweekly-task",
  "schedule": "0 4 * * 2,4"
}

Advanced Use Cases

Database Cleanup

// app/api/cleanup-db/route.ts
export async function GET(request: Request) {
  // Verify cron secret
  if (request.headers.get('authorization') !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response('Unauthorized', { status: 401 })
  }

  try {
    // Delete records older than 30 days
    const thirtyDaysAgo = new Date()
    thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30)

    // await db.deleteMany({
    //   where: {
    //     createdAt: {
    //       lt: thirtyDaysAgo
    //     }
    //   }
    // })

    return NextResponse.json({ 
      success: true,
      deleted: 0 // Replace with actual count
    })
  } catch (error) {
    return NextResponse.json({ error: error.message }, { status: 500 })
  }
}

API Health Check

// app/api/health-check/route.ts
export async function GET(request: Request) {
  const endpoints = [
    'https://api.example.com/health',
    'https://another-api.com/status'
  ]

  const results = await Promise.allSettled(
    endpoints.map(url => fetch(url))
  )

  const failed = results.filter(r => r.status === 'rejected').length

  if (failed > 0) {
    // Send alert
    // await sendAlert(`${failed} endpoints are down`)
  }

  return NextResponse.json({
    checked: endpoints.length,
    failed,
    timestamp: new Date().toISOString()
  })
}

Data Synchronization

// app/api/sync-data/route.ts
export async function GET(request: Request) {
  try {
    // Fetch data from external API
    const response = await fetch('https://external-api.com/data')
    const data = await response.json()

    // Process and store data
    // await db.upsertMany(data)

    return NextResponse.json({
      success: true,
      synced: data.length,
      timestamp: new Date().toISOString()
    })
  } catch (error) {
    return NextResponse.json({ error: error.message }, { status: 500 })
  }
}

Troubleshooting Cron Jobs

Unfortunately, when Cron jobs fail to run, it can be frustrating. Here are some guidelines for investigating the issue.

Verify Cron Configuration

The first step in troubleshooting is to ensure your cron job is defined correctly. Verify that:

Yourvercel.json file is in the root directory
The syntax is correct (you can useCrontab Calculator to validate)
The path to your API route is correct
Your deployment includes thevercel.json file

Check Function Logs

View your function logs in the Vercel dashboard to see if the cron job is being triggered and what errors might be occurring:

Go to your project in Vercel dashboard
Navigate to the "Functions" tab
Find your cron endpoint and view its logs

Test Manually

Before relying on automated execution, test your function manually by making a direct HTTP request to the endpoint:

curl -X GET https://your-project.vercel.app/api/your-cron-endpoint \
  -H "Authorization: Bearer your-cron-secret"

This helps you determine if the issue is with the function itself or with the cron scheduling.

Common Issues

Issue: Cron job not running

Ensurevercel.json is committed and deployed
Verify the cron syntax is correct
Check that your function exists at the specified path

Issue: Function timing out

Vercel has execution time limits (10 seconds on Hobby plan, 60 seconds on Pro)
Optimize your function or break it into smaller tasks
Consider using Vercel's Edge Functions for faster execution

Issue: Authentication failures

VerifyCRON_SECRET is set in environment variables
Check that your authorization header matches exactly
Usex-vercel-cron header as an alternative verification method

Best Practices and Tips

Test your functions manually before relying on cron scheduling to ensure they work as expected.
Use absolute paths and environment variables in your functions to avoid path-related issues.
Implement proper error handling and logging to capture any issues during execution.
Set up monitoring for your cron jobs to be notified when they fail.
Be mindful of Vercel's execution limits when scheduling resource-intensive tasks.
Use cron expressions wisely—consider using online tools like Crontab Calculator to validate complex schedules.
Secure your endpoints by verifying the cron secret or using the x-vercel-cron header.
Add idempotency to your functions to handle cases where they might run multiple times.
Monitor costs—while Vercel Cron is included in most plans, be aware of function execution costs if you have high-frequency cron jobs.
Document your cron jobs in your codebase so team members understand what scheduled tasks exist and why.

Conclusion

Vercel Cron is an essential tool for serverless application development. It provides a powerful and versatile solution for scheduling and automating tasks without managing servers or infrastructure.

The beauty of Vercel Cron lies in its simplicity and precision. From simple commands executed every minute to complex scripts scheduled for specific dates and times, cron adapts to many needs.

Through Vercel's serverless infrastructure and straightforward configuration via vercel.json, cron jobs provide developers with the flexibility to customize task scheduling according to their specific requirements.

By leveraging the insights and examples in this article, you'll be well on your way to scheduling success, increased productivity, and unlocking new possibilities in your serverless application journey.

For more detailed information, Vercel's documentation contains excellent information and explanations about how the cron system works on their platform.

Thank you for your time! Your feedback and comments are always welcome.

Implementing Real-Time Status Updates with Server-Sent Events in Next.js

Richard Lau — Fri, 12 Dec 2025 04:55:10 +0000

In modern web applications, providing real-time status updates is crucial for delivering an exceptional user experience. While traditional polling mechanisms work, they often introduce unnecessary latency and resource consumption. This article explores how we implemented Server-Sent Events (SSE) in our Next.js-based image processing platform to achieve near-instant status updates with minimal overhead.

The Challenge: Real-Time Image Processing Status

At Online Image Upscaler, users upload images for AI-powered enhancement that can take 10-30 seconds to complete. Our initial implementation used polling every 2-5 seconds, which resulted in:

High latency: Users waited 1-2 seconds after processing completed before seeing results
Resource waste: 15+ HTTP requests per image during a 30-second processing window
Poor user experience: Visible delays and unnecessary server load

We needed a better solution that could push status updates in real-time while maintaining simplicity and reliability.

Why Server-Sent Events?

When evaluating real-time communication options, we considered three approaches:

Feature	Traditional Polling	SSE	WebSocket
Latency	High (polling interval dependent)	Near real-time	Real-time
Complexity	Simple	Simple	Complex
Resource Usage	High (frequent requests)	Low (long connection)	Low
Auto-Reconnect	Manual	Native browser support	Manual
HTTP Protocol	Standard HTTP	Standard HTTP	Protocol upgrade required

SSE emerged as the ideal choice because:

Near real-time performance: Updates are pushed immediately when state changes occur
Simple implementation: Built on standard HTTP, no protocol upgrades needed
Automatic reconnection: Browser handles reconnection automatically
Better security: Works seamlessly with existing authentication and HTTPS
Lower overhead: Single persistent connection vs. multiple polling requests

Architecture Overview

Our implementation follows this flow:

User uploads image
    ↓
Processing task created (returns historyId)
    ↓
Frontend establishes SSE connection
    ↓
Backend processes image via Replicate API
    ↓
Webhook receives completion notification
    ↓
SSE pushes status update to clients
    ↓
Frontend updates UI in real-time

Implementation Details

1. SSE Connection Manager

We created a lightweight connection manager to handle multiple SSE connections efficiently:

// lib/sse-manager.ts
interface SSEConnection {
  write: (data: string) => void
  close?: () => void
}

class SSEManager {
  private connections = new Map<number, Set<SSEConnection>>()

  addConnection(historyId: number, connection: SSEConnection) {
    if (!this.connections.has(historyId)) {
      this.connections.set(historyId, new Set())
    }
    this.connections.get(historyId)!.add(connection)
  }

  removeConnection(historyId: number, connection: SSEConnection) {
    const conns = this.connections.get(historyId)
    if (conns) {
      conns.delete(connection)
      if (conns.size === 0) {
        this.connections.delete(historyId)
      }
    }
  }

  broadcast(historyId: number, data: unknown) {
    const conns = this.connections.get(historyId)
    if (!conns || conns.size === 0) return

    const message = `data: ${JSON.stringify(data)}\n\n`
    conns.forEach(connection => {
      try {
        connection.write(message)
      } catch (error) {
        // Connection closed, remove it
        this.removeConnection(historyId, connection)
      }
    })
  }
}

export const sseManager = new SSEManager()

This manager allows us to:

Track connections by historyId (processing task ID)
Broadcast messages to all clients watching the same task
Automatically clean up closed connections

2. SSE API Endpoint

Our Next.js API route creates the SSE connection:

// app/api/realtime/status/route.ts
import { NextRequest } from 'next/server'
import { sseManager } from '@/lib/sse-manager'
import { auth } from '@/lib/auth'

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams
  const historyId = parseInt(searchParams.get('historyId') || '0')

  // Validate user permissions
  const session = await auth()
  // ... permission checks ...

  // Create SSE stream
  const encoder = new TextEncoder()
  let isClosed = false

  const stream = new ReadableStream({
    start(controller) {
      // Send initial connection message
      controller.enqueue(
        encoder.encode(`data: {"type":"connected","historyId":${historyId}}\n\n`)
      )

      // Create connection object
      const connection: { write: (data: string) => void; close?: () => void } = {
        write: (data: string) => {
          if (!isClosed) {
            try {
              controller.enqueue(encoder.encode(data))
            } catch (error) {
              isClosed = true
              sseManager.removeConnection(historyId, connection)
            }
          }
        },
        close: () => {
          if (!isClosed) {
            isClosed = true
            controller.close()
          }
        },
      }

      // Register connection
      sseManager.addConnection(historyId, connection)

      // Handle connection abort
      request.signal.addEventListener('abort', () => {
        isClosed = true
        sseManager.removeConnection(historyId, connection)
        controller.close()
      })

      // Heartbeat to keep connection alive
      const heartbeatInterval = setInterval(() => {
        if (!isClosed) {
          try {
            controller.enqueue(encoder.encode(': heartbeat\n\n'))
          } catch (error) {
            clearInterval(heartbeatInterval)
            isClosed = true
            sseManager.removeConnection(historyId, connection)
          }
        } else {
          clearInterval(heartbeatInterval)
        }
      }, 30000) // Every 30 seconds
    },
  })

  return new Response(stream, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache, no-transform',
      'Connection': 'keep-alive',
      'X-Accel-Buffering': 'no', // Disable Nginx buffering
    },
  })
}

Key implementation details:

Initial connection message: Confirms the connection is established
Heartbeat mechanism: Sends a comment line every 30 seconds to keep the connection alive
Connection cleanup: Properly handles client disconnects and aborts
Security: Validates user permissions before allowing connections

3. Webhook Integration

When the external AI processing service completes, it sends a webhook to our backend:

// app/api/replicate/webhook/route.ts
import { sseManager } from '@/lib/sse-manager'

export async function POST(request: NextRequest) {
  const webhookData = await request.json()
  const predictionId = webhookData.id
  const status = webhookData.status // 'succeeded', 'failed', 'canceled'

  // Find the corresponding processing history
  const processingHistory = await prisma.processingHistory.findFirst({
    where: { referenceId: predictionId, referenceType: 'replicate_prediction' }
  })

  if (status === 'succeeded' && webhookData.output) {
    // Update database
    await prisma.processingHistory.update({
      where: { id: processingHistory.id },
      data: { status: 'COMPLETED', /* ... */ }
    })

    // Broadcast SSE notification
    sseManager.broadcast(processingHistory.id, {
      type: 'completed',
      historyId: processingHistory.id,
      status: 'completed',
      message: 'Processing completed',
      timestamp: new Date().toISOString(),
    })
  }
}

This ensures that as soon as processing completes, all connected clients receive immediate notification.

4. Frontend Implementation

On the client side, we use the native EventSource API with a hybrid approach:

// hooks/useImageProcessor.ts
const startPollingStatus = (imageId: string, historyId: number) => {
  let eventSource: EventSource | null = null

  // Establish SSE connection
  const sseUrl = `/api/realtime/status?historyId=${historyId}`
  eventSource = new EventSource(sseUrl)

  eventSource.onopen = () => {
    console.log('SSE connection established')
    // Use long-interval polling as backup (30 seconds)
    backupPollingInterval = setInterval(() => poll(), 30000)
  }

  eventSource.onmessage = (event) => {
    const data = JSON.parse(event.data)

    // Ignore heartbeat messages
    if (data.type === 'connected') return

    if (data.status === 'completed') {
      // Immediately fetch full result from database
      poll()

      // Clean up
      eventSource?.close()
      clearInterval(backupPollingInterval)
    }
  }

  eventSource.onerror = (error) => {
    console.warn('SSE connection error, falling back to polling')
    // Fallback to regular polling
  }
}

Hybrid Strategy Benefits:

Primary: SSE provides near-instant updates
Fallback: 30-second polling ensures reliability if SSE fails
Best of both worlds: Real-time performance with guaranteed delivery

Performance Results

After implementing SSE, we observed significant improvements:

Metric	Before (Polling)	After (SSE)	Improvement
Average latency	1-2 seconds	< 100ms	10-20x faster
HTTP requests per task	15+	1	93% reduction
Server load	High	Low	Significant reduction
User experience	Noticeable delay	Instant updates	Much improved

Key Takeaways

SSE is perfect for one-way updates: If you only need server-to-client communication, SSE is simpler than WebSocket
Hybrid approach ensures reliability: Combining SSE with polling provides both real-time performance and guaranteed delivery
Connection management matters: Properly tracking and cleaning up connections prevents memory leaks
Heartbeat keeps connections alive: Regular heartbeat messages prevent proxy servers from closing idle connections
Security is crucial: Always validate user permissions before allowing SSE connections

Conclusion

Implementing SSE in our Next.js application dramatically improved the user experience while reducing server load. The solution is simple, maintainable, and leverages browser-native features. For applications that need real-time server-to-client updates, SSE offers an excellent balance of performance, simplicity, and reliability.

If you're dealing with similar real-time status update challenges, I highly recommend considering SSE as your solution. The implementation is straightforward, and the performance gains are substantial.

Have you implemented SSE in your projects? Share your experiences and challenges in the comments below!

From Zero to Production: Building a Scalable QR Code Generator with React

Richard Lau — Fri, 31 Oct 2025 03:47:30 +0000

A practical guide to building a production-ready QR code generator from scratch, covering real-world challenges, user experience design, and lessons learned from shipping a live product.

Last month, I launched CustomQR.pro, a free QR code generator that has already processed over 10,000 QR codes. Building it taught me invaluable lessons about client-side rendering, performance optimization, and user experience design that I want to share with the DEV community.

This isn't just another tutorial — it's a deep dive into the real challenges we faced and how we solved them, from handling edge cases to optimizing for different devices.

The Problem We're Solving

Most QR code generators have significant pain points:

🐌 Slow generation: Network latency makes real-time preview impossible
🔒 Privacy concerns: Users hesitate to send sensitive data (WiFi passwords, contacts) to servers
💰 Hidden costs: Many "free" services have usage limits or require registration
📱 Poor mobile experience: Complex forms that don't work well on small screens

Our solution: Build everything client-side with React, ensuring instant generation, complete privacy, and a mobile-first design.

Architecture Decisions: Why We Chose Client-Side

The Server vs Client Debate

When we started, we considered two approaches:

Option 1: Server-Side Generation

// ❌ What we initially considered
POST /api/generate-qr
Body: { data: "https://example.com", config: {...} }
Response: { imageUrl: "https://cdn.example.com/qr.png" }

Problems:

Network latency (200-500ms per generation)
Server costs ($10-50/month for reasonable traffic)
Privacy concerns (all data passes through our servers)
Rate limiting complexity

Option 2: Client-Side Generation ✅

// ✅ What we built
import QRCode from 'qrcode'
const qrCode = await QRCode.toDataURL(data, config)
// Generated instantly, no server involved

Benefits:

⚡ 0ms latency: Generated instantly in browser
💰 $0 server cost: Static hosting is free
🔒 100% private: Data never leaves user's device
📈 Unlimited scale: No API rate limits

We chose client-side, and it was the best decision we made.

Real-World Implementation Challenges

Challenge 1: Handling Large QR Codes

Problem: Generating large QR codes (800x800px+) caused browser freezing.

Initial Solution (That Didn't Work):

const generateQR = async (data: string) => {
  const canvas = await QRCode.toCanvas(data, {
    width: 1000, // Too large!
    errorCorrectionLevel: 'H'
  })
  // Browser freezes for 2-3 seconds
}

Our Solution: Use Web Workers for large generations:

// qr-worker.ts
self.onmessage = async (e) => {
  const { data, config } = e.data

  // Dynamic import in worker
  const QRCode = await import('qrcode')
  const qrDataURL = await QRCode.default.toDataURL(data, config)

  self.postMessage({ qrDataURL })
}

// Component
const generateQRLarge = async (data: string) => {
  const worker = new Worker('/qr-worker.js')

  return new Promise((resolve, reject) => {
    worker.postMessage({ data, config: { width: 1000 } })

    worker.onmessage = (e) => {
      resolve(e.data.qrDataURL)
      worker.terminate()
    }

    worker.onerror = reject
  })
}

Result: Large QR codes generate without blocking the UI thread.

Challenge 2: Memory Leaks with Canvas

Problem: After generating 50+ QR codes, browser memory usage spiked.

Root Cause: Canvas elements weren't being properly cleaned up:

// ❌ Memory leak
const generateQR = async (data: string) => {
  const canvas = document.createElement('canvas')
  await QRCode.toCanvas(canvas, data)
  const url = canvas.toDataURL('image/png')
  // Canvas never cleaned up!
  return url
}

Solution: Proper cleanup in a useEffect cleanup function:

useEffect(() => {
  let isMounted = true
  let canvas: HTMLCanvasElement | null = null

  const generate = async () => {
    canvas = document.createElement('canvas')
    await QRCode.toCanvas(canvas, data)

    if (!isMounted) {
      // Component unmounted, cleanup immediately
      canvas.width = 0
      canvas.height = 0
      return
    }

    setQrCode(canvas.toDataURL('image/png'))
  }

  generate()

  return () => {
    isMounted = false
    if (canvas) {
      canvas.width = 0
      canvas.height = 0
      canvas = null
    }
  }
}, [data])

Challenge 3: Logo Upload UX

Problem: Users complained about logo upload being confusing.

User Research Finding: 60% of users didn't realize they could upload logos until after generating their first QR code.

Our Solution: Progressive disclosure with visual preview:

const LogoUpload: React.FC = () => {
  const [logoPreview, setLogoPreview] = useState<string>('')
  const [dragActive, setDragActive] = useState(false)

  const handleDrop = (e: React.DragEvent) => {
    e.preventDefault()
    setDragActive(false)

    const file = e.dataTransfer.files[0]
    if (file && file.type.startsWith('image/')) {
      const reader = new FileReader()
      reader.onload = (e) => {
        setLogoPreview(e.target?.result as string)
      }
      reader.readAsDataURL(file)
    }
  }

  return (
    <div
      onDragOver={(e) => {
        e.preventDefault()
        setDragActive(true)
      }}
      onDragLeave={() => setDragActive(false)}
      onDrop={handleDrop}
      className={`
        border-2 border-dashed rounded-lg p-8 text-center
        ${dragActive ? 'border-blue-500 bg-blue-50' : 'border-gray-300'}
        transition-all duration-200
      `}
    >
      {logoPreview ? (
        <div className="space-y-4">
          <img src={logoPreview} alt="Logo preview" className="w-24 h-24 mx-auto rounded" />
          <p className="text-sm text-gray-600">Logo ready! Your QR code will include this logo.</p>
        </div>
      ) : (
        <>
          <p className="text-gray-600 mb-2">Drag & drop your logo here</p>
          <p className="text-xs text-gray-400">or click to browse</p>
        </>
      )}
    </div>
  )
}

Result: Logo upload usage increased by 300%.

Mobile-First Design Patterns

Touch-Friendly Color Pickers

Mobile users struggled with standard color inputs. We built a custom solution:

const MobileColorPicker: React.FC<{ value: string; onChange: (color: string) => void }> = ({
  value,
  onChange
}) => {
  const presets = [
    '#000000', '#1a73e8', '#ea4335', '#fbbc04',
    '#34a853', '#9c27b0', '#ff9800', '#00bcd4'
  ]

  return (
    <div className="space-y-3">
      {/* Quick presets for mobile */}
      <div className="flex gap-2 flex-wrap">
        {presets.map((color) => (
          <button
            key={color}
            onClick={() => onChange(color)}
            className={`
              w-10 h-10 rounded-full border-2 transition-all
              ${value === color ? 'border-gray-800 scale-110' : 'border-gray-300'}
            `}
            style={{ backgroundColor: color }}
            aria-label={`Select color ${color}`}
          />
        ))}
      </div>

      {/* Full picker for desktop */}
      <div className="hidden md:block">
        <input
          type="color"
          value={value}
          onChange={(e) => onChange(e.target.value)}
          className="w-full h-12 rounded-lg cursor-pointer"
        />
      </div>
    </div>
  )
}

Responsive QR Preview

QR codes need to be scannable, but also visually appealing in the UI:

const QRPreview: React.FC<{ qrCode: string }> = ({ qrCode }) => {
  const [isExpanded, setIsExpanded] = useState(false)

  return (
    <div className="relative">
      {/* Compact view for mobile */}
      <div className="md:hidden">
        <img
          src={qrCode}
          alt="QR Code"
          className="w-48 h-48 mx-auto rounded-lg shadow-lg"
          onClick={() => setIsExpanded(true)}
        />
        <button
          onClick={() => setIsExpanded(true)}
          className="mt-2 text-sm text-blue-600"
        >
          Tap to expand
        </button>
      </div>

      {/* Full view for desktop/modal */}
      <div className={`
        hidden md:block fixed inset-0 bg-black/50 z-50
        flex items-center justify-center p-4
        ${isExpanded ? 'md:block' : 'md:hidden'}
      `}>
        <div className="bg-white rounded-lg p-6 max-w-md">
          <img src={qrCode} alt="QR Code" className="w-full max-w-sm mx-auto" />
          <button
            onClick={() => setIsExpanded(false)}
            className="mt-4 w-full py-2 bg-blue-600 text-white rounded-lg"
          >
            Close
          </button>
        </div>
      </div>
    </div>
  )
}

Error Handling & Edge Cases

Handling Invalid Data

Users enter all sorts of data. Here's how we handle edge cases:

const validateQRData = (type: QRType, data: any): { valid: boolean; error?: string } => {
  switch (type) {
    case 'url':
      try {
        new URL(data)
        return { valid: true }
      } catch {
        return { valid: false, error: 'Please enter a valid URL (e.g., https://example.com)' }
      }

    case 'wifi':
      if (!data.ssid || data.ssid.length < 1) {
        return { valid: false, error: 'WiFi network name is required' }
      }
      if (data.security !== 'nopass' && !data.password) {
        return { valid: false, error: 'WiFi password is required' }
      }
      return { valid: true }

    case 'vcard':
      if (!data.name || !data.phone || !data.email) {
        return { valid: false, error: 'Name, phone, and email are required' }
      }
      return { valid: true }

    default:
      if (!data || data.trim().length === 0) {
        return { valid: false, error: 'Please enter some data to encode' }
      }
      return { valid: true }
  }
}

// Usage in component
const generateQR = async () => {
  const validation = validateQRData(type, formData)

  if (!validation.valid) {
    setError(validation.error)
    return
  }

  setError(null)
  // Proceed with generation...
}

Handling Large File Sizes

SVG QR codes can be large. We optimize for download:

const downloadQR = async (format: 'png' | 'svg', qrCode: string) => {
  if (format === 'svg') {
    // SVG: Direct download (small file size)
    const blob = new Blob([qrCode], { type: 'image/svg+xml' })
    const url = URL.createObjectURL(blob)

    const link = document.createElement('a')
    link.href = url
    link.download = `qrcode.${format}`
    link.click()

    // Cleanup after 1 second
    setTimeout(() => URL.revokeObjectURL(url), 1000)
  } else {
    // PNG: Optimize for file size
    const img = new Image()
    img.onload = () => {
      const canvas = document.createElement('canvas')
      const ctx = canvas.getContext('2d')!

      // Scale down if too large (for mobile users)
      const maxSize = 800
      const scale = img.width > maxSize ? maxSize / img.width : 1

      canvas.width = img.width * scale
      canvas.height = img.height * scale
      ctx.drawImage(img, 0, 0, canvas.width, canvas.height)

      // Use lower quality for smaller file size
      canvas.toBlob((blob) => {
        if (blob) {
          const url = URL.createObjectURL(blob)
          const link = document.createElement('a')
          link.href = url
          link.download = `qrcode.${format}`
          link.click()
          setTimeout(() => URL.revokeObjectURL(url), 1000)
        }
      }, 'image/png', 0.9) // 90% quality
    }
    img.src = qrCode
  }
}

Performance Metrics & Optimization

We tracked real performance metrics:

Metric	Before Optimization	After Optimization
Initial Load	2.1s	0.8s
QR Generation	150ms	45ms
Memory Usage (50 generations)	180MB	45MB
Mobile Score (Lighthouse)	62	94

Key Optimizations

Code Splitting: Lazy load QR library only when needed

const QRCode = dynamic(() => import('qrcode'), { ssr: false })

Debouncing: Prevent excessive generations during typing

const debouncedData = useDebounce(formData, 300)

Canvas Pooling: Reuse canvas elements

const canvasPool: HTMLCanvasElement[] = []
const getCanvas = () => canvasPool.pop() || document.createElement('canvas')

User Experience Wins

Instant Feedback

Users loved the real-time preview. Here's our implementation:

const QRGenerator: React.FC = () => {
  const [formData, setFormData] = useState(initialData)
  const [qrCode, setQrCode] = useState('')
  const [isGenerating, setIsGenerating] = useState(false)

  // Auto-generate on any change
  useEffect(() => {
    const timer = setTimeout(async () => {
      setIsGenerating(true)
      try {
        const qr = await generateQR(formData)
        setQrCode(qr)
      } finally {
        setIsGenerating(false)
      }
    }, 300) // 300ms debounce

    return () => clearTimeout(timer)
  }, [formData])

  return (
    <div>
      {/* Form inputs */}
      <QRForm data={formData} onChange={setFormData} />

      {/* Instant preview */}
      <div className="relative">
        {isGenerating && (
          <div className="absolute inset-0 bg-white/80 flex items-center justify-center">
            <div className="animate-spin">⚡</div>
          </div>
        )}
        {qrCode && <img src={qrCode} alt="QR Code" />}
      </div>
    </div>
  )
}

Progressive Enhancement

We ensure the app works even without JavaScript (for SEO):

// Static HTML fallback for crawlers
export default function QRGeneratorPage() {
  return (
    <>
      <noscript>
        <div className="p-4 bg-yellow-50 border border-yellow-200 rounded">
          <p>JavaScript is required to generate QR codes. Please enable JavaScript in your browser.</p>
        </div>
      </noscript>

      {/* Client-side generator */}
      <QRGeneratorClient />
    </>
  )
}

Lessons Learned

What Worked Well ✅

Client-side generation: Zero server costs, instant feedback
Mobile-first design: 60% of our users are on mobile
Progressive disclosure: Show advanced options only when needed
Error prevention: Validate input before generation

What We'd Do Differently 🔄

Add analytics earlier: We wish we'd tracked user behavior from day one
More QR types initially: Users requested features we didn't anticipate
Better onboarding: First-time users need more guidance

Surprising Findings 📊

Logo usage: Only 15% of users add logos (we expected 40%+)
Format preference: 70% download PNG, 25% SVG, 5% JPG
Mobile vs Desktop: Mobile users generate simpler QR codes (mostly URLs)

Open Source & Community

We've open-sourced parts of our implementation. Key components:

// useQRGenerator.ts - Reusable hook
export function useQRGenerator(initialData: string) {
  const [qrCode, setQrCode] = useState('')
  const [isGenerating, setIsGenerating] = useState(false)
  const [error, setError] = useState<string | null>(null)

  const generate = async (data: string, config: QRConfig) => {
    setIsGenerating(true)
    setError(null)

    try {
      const qr = await QRCode.toDataURL(data, config)
      setQrCode(qr)
    } catch (err) {
      setError(err instanceof Error ? err.message : 'Generation failed')
    } finally {
      setIsGenerating(false)
    }
  }

  return { qrCode, isGenerating, error, generate }
}

Conclusion

Building a production QR code generator taught us that user experience and performance are inseparable. Every technical decision should be evaluated through the lens of user impact.

Key Takeaways:

✅ Client-side generation is superior for this use case
✅ Mobile-first design is essential (not optional)
✅ Error handling and edge cases matter as much as happy paths
✅ Performance optimizations directly impact user satisfaction
✅ Real user feedback > assumptions

If you're building something similar, I'd love to hear about your challenges and solutions! Drop a comment below or check out CustomQR.pro to see these patterns in action.

Cover image: Screenshot of CustomQR.pro in action