JSON, localStorage and Browser Storage
Serialise data with JSON, persist state in localStorage and sessionStorage, understand cookies and IndexedDB, and keep stored data safe.
Choose Storage for the Lifetime You Need
A browser page's JavaScript variables disappear when the page is reloaded or closed. Browser storage can preserve selected data, but each mechanism has different lifetime, access, and complexity. A theme preference is a good candidate for simple local persistence; credentials, payment records, and authoritative account state are not.
| Mechanism | Typical use | Important trade-off |
|---|---|---|
| localStorage | Small string preferences that survive reloads | Synchronous, origin-scoped, readable by page scripts |
| sessionStorage | Short-lived state for one browsing context | String-only and cleared when that page session ends |
| Cookies | Small values sent with matching HTTP requests | Cookie attributes and server configuration matter |
| IndexedDB | Structured, larger client-side data | Asynchronous API with more setup and lifecycle handling |
Browser storage is origin-scoped: scheme, host, and port distinguish origins. A local preference is not automatically shared with a different subdomain or another browser. Server-side data should still be validated and authorized by the server on every relevant request.
Serialize Plain Data with JSON
JSON is a text format for exchanging data. JSON.stringify() converts supported JavaScript values to text, and JSON.parse() reads JSON text back into values. JSON supports strings, numbers, booleans, null, arrays, and objects with string keys. It does not preserve functions, undefined object properties, prototypes, or special object types such as Date without an explicit conversion strategy.
const preferences = {
theme: 'dark',
language: 'en',
completedLessonIds: ['js-01', 'js-02'],
}
const jsonText = JSON.stringify(preferences)
const restored = JSON.parse(jsonText)
console.log(jsonText)
console.log(restored.completedLessonIds)Parsing untrusted or corrupted text can throw a SyntaxError. A successful parse only proves that the text follows JSON syntax; it does not prove that the values match the shape or rules your application expects. Validate data after parsing, just as you validate values received from a network.
Save and Restore a Preference Safely
localStorage offers setItem(), getItem(), and removeItem() for string keys and values. Access can fail, for example when storage is disabled or unavailable in the current context. Wrap reads and writes that affect the user experience in error handling. Provide a useful default if a saved value is absent or invalid.
const STORAGE_KEY = 'chaduvuko.preferences.v1'
function isPreferences(value) {
return value !== null &&
typeof value === 'object' &&
(value.theme === 'light' || value.theme === 'dark') &&
typeof value.language === 'string'
}
function loadPreferences() {
try {
const saved = localStorage.getItem(STORAGE_KEY)
if (saved === null) return { theme: 'light', language: 'en' }
const parsed = JSON.parse(saved)
return isPreferences(parsed) ? parsed : { theme: 'light', language: 'en' }
} catch (error) {
console.warn('Preferences could not be loaded:', error)
return { theme: 'light', language: 'en' }
}
}
function savePreferences(preferences) {
try {
localStorage.setItem(STORAGE_KEY, JSON.stringify(preferences))
return true
} catch (error) {
console.warn('Preferences could not be saved:', error)
return false
}
}The key includes a simple version marker so later code can distinguish older formats. When the data shape changes, validate the old shape and migrate it deliberately, or discard the old preference and use a safe default. Do not assume stored values will be present just because the current page saved them earlier.
Understand localStorage, sessionStorage and Events
localStorage generally remains available across browser restarts until cleared. sessionStorageis intended for a page session and is separated by origin and browsing context; it is useful for temporary state that should not become a lasting preference. Both APIs are synchronous, so avoid repeated reads and writes in a hot rendering path.
sessionStorage.setItem('checkout.step', 'address')
const step = sessionStorage.getItem('checkout.step')
console.log(step)
// The storage event is delivered to other same-origin documents
// when storage changes; it is not fired in the document that made the change.
window.addEventListener('storage', (event) => {
if (event.key === 'chaduvuko.preferences.v1') {
console.log('Preferences changed in another page', event.newValue)
}
})Do not use storage events as a database synchronization protocol. They notify other documents about a change, but simultaneous updates can still conflict, and they do not make a client-side value authoritative. For cross-device synchronization or important account state, use a server API with a clear conflict and authorization policy.
Use Cookies or IndexedDB for Their Intended Jobs
Cookies are small key-value data attached to matching HTTP requests according to their attributes. Servers commonly use secure, HttpOnly, and SameSite settings for session cookies; HttpOnly prevents ordinary page scripts from reading the cookie. Cookie security depends on correct server configuration, transport security, and application controls. Do not place a sensitive session token in a JavaScript-readable cookie or localStorage by default.
IndexedDB is an asynchronous database API for structured client-side data, including records and indexes. It can suit offline-capable apps or larger caches better than synchronous Web Storage. It takes more code to manage transactions, schema upgrades, and failures. Consider a well-maintained abstraction if an application needs IndexedDB, and keep a plan for clearing stale cached data.
| Question | Prefer |
|---|---|
| Does a server need the value on each matching request? | A carefully configured cookie |
| Is this a tiny, non-sensitive preference? | localStorage |
| Should it last only during a page session? | sessionStorage |
| Do you need async structured client-side records? | IndexedDB |
Version, Validate and Clear Persisted State
Persisted data can outlive a deployment. Include a version in the key or value when formats may change, validate the parsed shape, and migrate only when you can do so reliably. If validation fails, discard the invalid value and continue with a documented default rather than repeatedly crashing the page.
function loadCompletedLessons() {
const key = 'chaduvuko.completed-lessons.v1'
try {
const saved = localStorage.getItem(key)
if (saved === null) return []
const value = JSON.parse(saved)
if (!Array.isArray(value) || !value.every((id) => typeof id === 'string')) {
localStorage.removeItem(key)
return []
}
return value
} catch (error) {
console.warn('Saved lesson progress is unavailable:', error)
return []
}
}
function clearLocalProgress() {
localStorage.removeItem('chaduvuko.completed-lessons.v1')
}- Decide what data truly needs to persist and how sensitive it is.
- Choose a storage mechanism that matches its lifetime and access needs.
- Use a namespaced key and explicit JSON serialization for structured values.
- Parse inside a failure boundary, then validate the value shape.
- Define a default, migration, and clear-data path for stale or invalid values.
A clear-data action should remove only the application's own keys unless the user intentionally requests broader browser data removal. Keep stored values minimal and avoid retaining personal information without a product need.
Common Mistakes
Passing an object directly to localStorage.setItem
Why: Web Storage stores strings, so an object is coerced into an unhelpful string representation.
Fix: Serialize supported data with JSON.stringify and parse it with JSON.parse when reading.
Assuming JSON.parse validates the application schema
Why: Valid JSON can still contain the wrong fields or value types.
Fix: Check the parsed value shape and domain rules before using it.
Storing secrets or sensitive state in browser storage
Why: JavaScript-readable storage can be exposed by script injection and is controlled by the user.
Fix: Keep sensitive session handling server-controlled and store only minimal, non-sensitive client preferences.
Assuming storage is always available and up to date
Why: Access can fail, old versions can leave invalid data, and multiple tabs can overwrite each other.
Fix: Handle exceptions, validate versions, provide defaults, and use a server for authoritative synchronization.
Persist a Learner's Display Preferences
Practice
A safe, versioned preference store
- Define a preference object for theme and language, then serialize and restore it with JSON.
- Write a validator that rejects a missing theme, an unsupported theme value, or a non-string language.
- Wrap localStorage reads and writes in try/catch and fall back to defaults if parsing or access fails.
- Add a versioned key and describe how you would migrate a previous version with a different field name.
- Use sessionStorage for a temporary multi-step form position and explain why it should not be a permanent preference.
- Write a short threat-model note explaining why login tokens, payment details, and authoritative progress are excluded.
Hint: Test with a missing key, malformed JSON, valid JSON with an invalid shape, and storage access that throws.
🎯 Key Takeaways
- ✓JSON serializes supported plain data to text, but parsing does not validate the application schema.
- ✓localStorage and sessionStorage are synchronous string stores with different intended lifetimes.
- ✓Cookies are sent with matching requests and need deliberate security attributes and server configuration.
- ✓IndexedDB is an asynchronous option for structured client-side data and requires transaction and version planning.
- ✓Validate persisted data, handle access and parse errors, and provide safe defaults and a clear-data path.
- ✓Never treat client-side storage as a secure vault or an authoritative source for sensitive account state.
Next
What comes next
Make failures easier to understand with deliberate errors, browser DevTools, and resilient code.
Lesson 08 · Error Handling and Debugging in the Browser →HELP US IMPROVE
How was this lesson?
Your note is shared with the Chaduvuko team for review. Please don’t include personal or sensitive information.
Spotted a mistake or something unclear? Suggest a fix on GitHub or email us. Select the text first and it is quoted for you.
Discussion
0Have a better approach? Found something outdated? Share it — your knowledge helps everyone learning here.
