Client-Side Rate Limiter

Interactive coding environments allow users to execute code repeatedly. Without constraints, this can lead to performance issues. This article explains how to implement a rate limiter pattern that's commonly used in web applications:

• Excessive CPU usage in the browser
• Degraded performance for the user
• Accidental abuse via rapid clicks or loops
• Increased backend or execution service load (if present)

The system needs a lightweight execution throttle that limits how frequently code can be run while preserving a smooth developer experience.

Design Goals

The rate limiter is intentionally pragmatic and UX-focused, not security-focused. It's designed to:

• Prevent accidental or excessive execution, not malicious abuse
• Stay entirely client-side, no server round trips
• Work in SSR setups (Next.js) without crashing on window or localStorage
• Degrade gracefully if browser storage is unavailable
• Be simple to explain and debug

Things it explicitly does not try to do:

• Enforce hard security guarantees
• Track users across devices or sessions
• Prevent a determined user from bypassing the limit

This is a guardrail, not a firewall.

The Core Idea: Fixed-Window Counter

The system uses a classic fixed-window rate limiter:

• Choose a window duration (e.g. 60 seconds)
• Choose a max number of executions allowed in that window (e.g. 10)
• Keep a simple counter of how many executions occurred in the current window

Configuration:

TSfile.typescript
1const EXECUTIONS_PER_MINUTE = 10;
2const WINDOW_DURATION_MS = 60 * 1000; // 1 minute

On each execution attempt:

1. Load the stored state from localStorage (if any)
2. If there's no state, create a new window starting now
3. If the current time has passed the stored resetTime, start a fresh window
4. If the count is below the max, increment and allow
5. If the count has reached the max, block and tell the user when they can try again

The stored entry is simple:

TSfile.typescript
1interface RateLimitEntry {
2  count: number;      // executions in the current window
3  resetTime: number;  // timestamp when the window resets
4}

Per-Page Isolation

Different pages in the app have different execution contexts (e.g. practice, playground, snippet practice). They shouldn't share a rate limit.

To keep them isolated, the limiter uses namespaced keys stored in localStorage:

TSfile.typescript
1function getStorageKey(page: 'practice' | 'playground' | 'snippet-practice'): string {
2  return `rate_limit_${page}`;
3}

This guarantees:

• Heavy use on one page doesn't throttle another
• Each feature can be reasoned about independently

Public API: How the UI Uses It

The main entrypoint is a single function you call before executing any user code:

TSfile.typescript
1export interface RateLimitResult {
2  allowed: boolean;
3  retryAfter?: number;  // seconds until next allowed execution
4  remaining?: number;   // remaining executions in current window
5}
6
7export function checkRateLimit(
8  page: 'practice' | 'playground' | 'snippet-practice'
9): RateLimitResult

Typical UI flow:

1. User clicks Run
2. Call checkRateLimit(page)
3. Branch on the response:

If allowed: true

• Proceed with code execution
• Optionally show "You have X runs left this minute" using remaining

If allowed: false

• Block execution
• Show a friendly message like:

  "You've hit the rate limit. Try again in 12 seconds."

There are also two supporting APIs:

TSfile.typescript
1// Reset the rate limit (useful for testing)
2resetRateLimit(page: 'practice' | 'playground' | 'snippet-practice'): void
3
4// Check remaining without consuming an execution
5getRemainingExecutions(page: 'practice' | 'playground' | 'snippet-practice'): number | null

This keeps the UI logic clean and makes the limiter easy to integrate in multiple places.

TSfile.typescript
1localStorage
2└── rate_limit_<page>
3    ├── count: number
4    └── resetTime: timestamp

Implementation Details

Here's the complete implementation of checkRateLimit:

TSfile.typescript
1export function checkRateLimit(
2  page: 'practice' | 'playground' | 'snippet-practice'
3): RateLimitResult {
4  if (typeof window === 'undefined') {
5    // Server-side: always allow (rate limiting is client-side only)
6    return { allowed: true };
7  }
8
9  const storageKey = getStorageKey(page);
10  const now = Date.now();
11
12  try {
13    const stored = localStorage.getItem(storageKey);
14    
15    if (!stored) {
16      // First execution: create new entry
17      const entry: RateLimitEntry = {
18        count: 1,
19        resetTime: now + WINDOW_DURATION_MS,
20      };
21      localStorage.setItem(storageKey, JSON.stringify(entry));
22      return {
23        allowed: true,
24        remaining: EXECUTIONS_PER_MINUTE - 1,
25      };
26    }
27
28    const entry: RateLimitEntry = JSON.parse(stored);
29
30    // Check if window has expired
31    if (now >= entry.resetTime) {
32      // Reset the window
33      const newEntry: RateLimitEntry = {
34        count: 1,
35        resetTime: now + WINDOW_DURATION_MS,
36      };
37      localStorage.setItem(storageKey, JSON.stringify(newEntry));
38      return {
39        allowed: true,
40        remaining: EXECUTIONS_PER_MINUTE - 1,
41      };
42    }
43
44    // Window is still active
45    if (entry.count >= EXECUTIONS_PER_MINUTE) {
46      // Rate limit exceeded
47      const retryAfter = Math.ceil((entry.resetTime - now) / 1000);
48      return {
49        allowed: false,
50        retryAfter,
51      };
52    }
53
54    // Increment count
55    entry.count += 1;
56    localStorage.setItem(storageKey, JSON.stringify(entry));
57    
58    return {
59      allowed: true,
60      remaining: EXECUTIONS_PER_MINUTE - entry.count,
61    };
62  } catch (error) {
63    // If localStorage fails (e.g., in private browsing), allow execution
64    // This is a graceful degradation
65    console.warn('Rate limiter: localStorage access failed', error);
66    return { allowed: true };
67  }
68}

Key aspects of this implementation:

• SSR-safe: Early return when window is not defined
• Four distinct paths: first execution, expired window, over limit, under limit
• Defensive try/catch around localStorage usage
• Fail-open behavior: if storage breaks, we don't block the user
• User-friendly data: remaining and retryAfter are ready for UI consumption

Error Handling and Degraded Mode

Browsers can (and do) fail localStorage reads/writes in some scenarios:

• Private/incognito mode with strict settings
• Full storage quota
• User or extensions blocking access

Rather than punishing the user for that, the limiter chooses:

• If storage fails → allow execution
• Log a warning so it's debuggable in development
• Accept that in rare cases, the limiter won't be enforced

This is a conscious tradeoff:

"A broken limiter should never prevent someone from learning or experimenting."

Tradeoffs and Edge Cases

Fixed-Window Bursting

A user can run code at the end of one window and immediately again at the beginning of the next, briefly exceeding the "average" rate.

Tradeoff: For UX-focused throttling, this is totally fine.

Multi-Tab Behavior

Different tabs share the same localStorage entry, but writes are not synchronized in a strongly consistent way.

Tradeoff: In practice, it's rare for users to spam "Run" across many tabs simultaneously, so we accept the minor risk.

Client Trust

Users can clear storage, edit devtools values, or change system time.

Tradeoff: This limiter is not meant to stop a determined attacker, only to prevent accidental overload.

How This Feels in the UI

When wired into the UI, the experience can be very friendly:

Normal usage:

• "Run" always works, and maybe you see a subtle indicator like "7/10 runs left this minute."

Heavy usage:

• After hitting the limit, the button might disable and a small tooltip appears:

  "You've hit the limit of 10 runs per minute. Try again in 23s."

Dev / QA:

• There might be a hidden "Reset rate limit" action that calls resetRateLimit(page) so you can quickly test behavior without waiting.

The final result: smooth interactions by default, guardrails when needed, and no surprises.

Example Integration

Here's how you might wire this into a React component:

TSXcomponent.tsx
1function CodeEditor({ page }: { page: 'practice' | 'playground' | 'snippet-practice' }) {
2  const [status, setStatus] = useState<string>('');
3  const [isRunning, setIsRunning] = useState(false);
4
5  const handleRun = async () => {
6    const result = checkRateLimit(page);
7
8    if (!result.allowed) {
9      setStatus(`Rate limit exceeded. Try again in ${result.retryAfter}s.`);
10      return;
11    }
12
13    setIsRunning(true);
14    setStatus('');
15    
16    try {
17      await executeCode();
18      
19      if (result.remaining !== undefined && result.remaining <= 3) {
20        setStatus(`${result.remaining} runs remaining this minute`);
21      }
22    } finally {
23      setIsRunning(false);
24    }
25  };
26
27  return (
28    <div>
29      <button onClick={handleRun} disabled={isRunning}>
30        {isRunning ? 'Running...' : 'Run Code'}
31      </button>
32      {status && <div className="text-sm text-muted-foreground mt-2">{status}</div>}
33    </div>
34  );
35}

You can also show remaining executions proactively:

TSXcomponent.tsx
1function ExecutionBadge({ page }: { page: 'practice' | 'playground' | 'snippet-practice' }) {
2  const remaining = getRemainingExecutions(page);
3  
4  if (remaining === null) return null;
5  
6  return (
7    <Badge variant={remaining <= 3 ? 'warning' : 'default'}>
8      {remaining} / {EXECUTIONS_PER_MINUTE} runs left
9    </Badge>
10  );
11}

Possible Future Upgrades

If requirements tighten or usage grows, this client-side limiter can evolve:

• Token bucket for smoother burst handling
• Sliding window for more accurate enforcement
• Cross-tab sync using the storage event
• Server-side enforcement layered on top for authenticated users
• Per-user quotas based on auth/session data

But even in its current form, it already hits an important sweet spot: simple, local, and good enough for most educational and interactive environments.

Takeaways

• You don't need a backend to protect your app from excessive usage.
• A tiny client-side rate limiter can dramatically improve UX by preventing runaway execution.
• Storing a simple counter and reset timestamp in localStorage is often all you need.
• Designing for degraded mode and clarity matters more than perfect enforcement in user-facing tools.

---

Have you built similar client-side protection mechanisms? I'd love to hear about your approach in the comments below.