Skip to main content
rule CX Codex

client-localstorage-schema — Claude Code rule for localStorage

The client-localstorage-schema rule guides Claude Code to version localStorage keys and keep only fields the UI needs. Use it when changing client-side settings or cached user data.

MIT ★ 7,191 updated 2026-10-24

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/client-localstorage-schema.md
Open on GitHub

What client-localstorage-schema does

The rule recommends adding a version to each localStorage key so data from different schema versions stays separate. Its migration example converts older settings to the new shape, saves them under the updated key, then removes the old entry.

It also calls for storing only UI-required fields and wrapping reads and writes in try-catch. That limits the chance of retaining tokens, personal data, or internal flags. In private browsing, when storage is disabled, or after the quota is exceeded, localStorage operations can throw; code without error handling can fail there.

What it helps with

  • separate stored data by schema version
  • move settings from an old key to a new one
  • cache only the user fields the UI needs
  • handle failed localStorage reads and writes

Example prompts for the agent

  • Review the settings code and apply client-localstorage-schema to its localStorage usage.
  • Add a versioned key and migrate the existing settings under client-localstorage-schema.
  • Trim the user cache to UI-required fields and handle localStorage errors using client-localstorage-schema.

How to install client-localstorage-schema

Manually: put the files in place

.claude/rules/client-localstorage-schema.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about client-localstorage-schema

How do I install client-localstorage-schema in Claude Code?

Add the rule file at .claude/rules/client-localstorage-schema.md.

What does client-localstorage-schema do?

It guides Claude Code to version localStorage keys, keep only necessary fields, and catch storage errors.

How does the rule handle a change in the storage key version?

Its example reads the old userConfig:v1 entry, converts the settings, writes them under the new version, and removes the old entry.

Source text

client-localstorage-schema.md · MIT
---
title: Version and Minimize localStorage Data
impact: MEDIUM
impactDescription: prevents schema conflicts, reduces storage size
tags: client, localStorage, storage, versioning, data-minimization
---

## Version and Minimize localStorage Data

Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.

**Incorrect:**

```typescript
// No version, stores everything, no error handling
localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
const data = localStorage.getItem('userConfig')
```

**Correct:**

```typescript
const VERSION = 'v2'

function saveConfig(config: { theme: string; language: string }) {
  try {
    localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
  } catch {
    // Throws in incognito/private browsing, quota exceeded, or disabled
  }
}

function loadConfig() {
  try {
    const data = localStorage.getItem(`userConfig:${VERSION}`)
    return data ? JSON.parse(data) : null
  } catch {
    return null
  }
}

// Migration from v1 to v2
function migrate() {
  try {
    const v1 = localStorage.getItem('userConfig:v1')
    if (v1) {
      const old = JSON.parse(v1)
      saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
      localStorage.removeItem('userConfig:v1')
    }
  } catch {}
}
```

**Store minimal fields from server responses:**

```typescript
// User object has 20+ fields, only store what UI needs
function cachePrefs(user: FullUser) {
  try {
    localStorage.setItem('prefs:v1', JSON.stringify({
      theme: user.preferences.theme,
      notifications: user.preferences.notifications
    }))
  } catch {}
}
```

**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.

**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.

© tech-leads-club · MIT · tech-leads-club/agent-skills

Similar IDE rules

All IDE rules for Frontend and UI →

From the same set130

The whole set →
js-length-check-first js-length-check-first — a rule for Claude Code that prompts the AI to check array lengths before running expensive operations like sorting or deep equality checks. If lengths differ, arrays cannot be equal—no expensive work needed. CX Codex +1 ★ 7,191repo stars js-tosorted-immutable The js-tosorted-immutable rule replaces mutating .sort() with .toSorted(), keeping React props and state arrays unchanged during sorting. CX Codex +1 ★ 7,191repo stars patterns-children-over-render-props patterns-children-over-render-props — a Claude rule that pushes React components toward composition with children instead of renderX props, so call sites read as plain JSX. CX Codex +1 ★ 7,191repo stars js-cache-function-results js-cache-function-results instructs the agent to cache repeated function calls using a module-level Map. It eliminates redundant computations across renders and utility calls. CX Codex +1 ★ 7,191repo stars client-event-listeners client-event-listeners — a Claude rule that keeps a single keydown listener on window no matter how many components call the shortcut hook. CX Codex +1 ★ 7,191repo stars server-after-nonblocking server-after-nonblocking instructs the agent to schedule logging, analytics, and cleanup with Next.js after(). This sends responses right away without waiting for background work. CX Codex +1 ★ 7,191repo stars rerender-lazy-state-init The rerender-lazy-state-init rule recommends lazy useState initialization for costly starting values. It helps when a React component reads stored settings or builds a data structure. CX Codex +1 ★ 7,191repo stars async-defer-await async-defer-await — a rule that moves await operations into code branches where they're actually needed, preventing blockage of execution paths that may exit early. CX Codex +1 ★ 7,191repo stars

Project sponsors

Companies that keep this analytics open