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
.claude/rules/client-localstorage-schema.mdWhat 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
localStoragereads and writes
Example prompts for the agent
- Review the settings code and apply
client-localstorage-schemato itslocalStorageusage. - Add a versioned key and migrate the existing settings under
client-localstorage-schema. - Trim the user cache to UI-required fields and handle
localStorageerrors usingclient-localstorage-schema.
How to install client-localstorage-schema
Manually: put the files in place
.claude/rules/client-localstorage-schema.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/client-localstorage-schema.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/client-localstorage-schema.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/client-localstorage-schema.mdManually: put the files in place
.clinerules/client-localstorage-schema.mdStep 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