Typesafe Local Storage illustration showing code and data structures

Build Typesafe Local Storage in JavaScript

Stop struggling with unreliable local storage data. This guide shows you how to create a typesafe local storage solution that prevents common errors and makes your web applications more robust.

Published on: Apr 14, 2025

Time to complete: 15 minutes

Why Type Safety for Local Storage Is Essential

Browser local storage is powerful but risky. The simple key-value API makes it easy to store strings, but complex data requires manual serialization and deserialization. Without type checking, you risk runtime errors when data doesn’t match your expectations.

Common local storage problems include:

Storing complex objects without proper serialization
Retrieving data with unexpected structure
Missing properties in stored objects
No schema validation for stored data

A typesafe approach solves these issues by enforcing data structure at compile time.

Building a Schema-Based Foundation for Local Storage

First, define a schema that describes all possible data structures you’ll store:

1
import { z } from 'astro/zod';
2

3
// Define schemas for different types of data
4
export const ZContactFormSchema = z.object({
5
  name: z.string(),
6
  email: z.string().email(),
7
  message: z.string(),
8
  submitted: z.boolean().optional(),
9
});
10

11
export const ZAnalyticsSchema = z.object({
12
  pageViews: z.record(z.string(), z.number()),
13
  lastVisit: z.string(), // ISO date string
14
});
15

16
// Create the main schema object with all possible storage keys
17
export const ZLocalDataSchemas = z.object({
18
  ['contact-form']: ZContactFormSchema,
19
  ['analytics']: ZAnalyticsSchema,
20
  ['color-picker-history']: z.array(z.string()),
21
  // Add more schemas as needed
22
});
23

24
// Export the inferred TypeScript type
25
export type LocalDataSchemas = z.infer<typeof ZLocalDataSchemas>;

This schema creates a contract for your data. Now TypeScript knows exactly what structure to expect for each storage key.

Limited Time Launch Sale

Want to skip the setup? Our Astro starter template includes a ready-to-use typesafe local storage system with pre-built schemas!

GET 60% OFF!

Implementing a Type-Safe Storage Utility

Next, create a utility that enforces these types when reading from or writing to local storage:

1
import { CONFIG } from '../../constants';
2
import type { LocalDataSchemas } from '../../schemas/local-data';
3

4
// Prefix keys to avoid collisions with other apps
5
const dataKey = (key: string) => `${CONFIG.APP_NAME}:${key}`;
6

7
// JSON-safe type definitions
8
type JsonPrimitive = string | number | boolean | null;
9
type JsonArray = JsonValue[];
10
type JsonObject = { [key: string]: JsonValue };
11
type JsonValue = JsonPrimitive | JsonObject | JsonArray;
12

13
// Convert non-JSON-safe types to string
14
type JsonSafe<T> = {
15
  [P in keyof T]: T[P] extends JsonValue ? T[P] : T[P] extends Date ? string : T[P] extends object ? { [K in keyof T[P]]: JsonSafe<T[P][K]> } : string;
16
};
17

18
// Get data with type safety
19
export const getData = <T extends keyof LocalDataSchemas, R = LocalDataSchemas[T]>(location: T): Partial<JsonSafe<R>> | undefined => {
20
  let localData: Partial<JsonSafe<R>> | undefined;
21
  try {
22
    const temp = localStorage.getItem(dataKey(location));
23
    if (temp) localData = JSON.parse(temp) as JsonSafe<R>;
24
  } catch (e) {
25
    console.error(`Error loading data for ${location}:`, e);
26
  }
27
  return localData;
28
};
29

30
// Set data with type safety
31
export const setData = <T extends keyof LocalDataSchemas, R = LocalDataSchemas[T]>(location: T, data: Partial<JsonSafe<R> | R>): void => {
32
  try {
33
    localStorage.setItem(dataKey(location), JSON.stringify(data));
34
  } catch (e) {
35
    console.error(`Error saving data for ${location}:`, e);
36
  }
37
};
38

39
// Delete data
40
export const deleteData = <T extends keyof LocalDataSchemas>(location: T): void => {
41
  try {
42
    localStorage.removeItem(dataKey(location));
43
  } catch (e) {
44
    console.error(`Error deleting data for ${location}:`, e);
45
  }
46
};

How to Use Type-Safe Local Storage in Your Application

1
// Example usage
2
import { getData, setData, deleteData } from '../lib/client/storage';
3

4
// TypeScript knows exactly what shape this data should have
5
const contactForm = getData('contact-form');
6

7
// TypeScript will error if you try to access a property that doesn't exist
8
const email = contactForm?.email; // ✓ Valid
9
const phone = contactForm?.phone; // ✗ Error: Property 'phone' does not exist
10

11
// TypeScript will error if you try to save data with the wrong shape
12
setData('contact-form', {
13
  name: 'John Doe',
14
  email: '[email protected]',
15
  message: 'Hello world',
16
  // TypeScript would error if we tried to add an unexpected field
17
});
18

19
// Delete data when no longer needed
20
deleteData('contact-form');

Creating a Form Data Helper for Automatic Storage

For forms, we can create a helper function that automatically saves form data to local storage:

1
// Generic form data handler
2
export const genericSaveDataHandler = <T extends keyof LocalDataSchemas>(
3
  key: T,
4
  options?: {
5
    dontSave?: (keyof LocalDataSchemas[T])[];
6
  }
7
) => {
8
  return (formData: FormData) => {
9
    const data = getData<T>(key) || {};
10

11
    if (options?.dontSave) {
12
      options.dontSave.forEach((key) => formData.delete(String(key)));
13
    }
14

15
    const entries = Object.fromEntries(formData.entries());
16

17
    const newData = {
18
      ...data,
19
      ...entries,
20
    } as unknown as JsonSafe<LocalDataSchemas[T]>;
21

22
    setData(key, newData);
23
  };
24
};

Advanced Features for Enhanced Local Storage Management

Expiration dates: Add TTL (time-to-live) for stored data
Compression: Compress large data before storing
Migration: Handle schema changes with version tracking

By implementing typesafe local storage, you’ll catch errors at compile time rather than runtime, making your applications more reliable and easier to maintain.