local-storage-patterns

Local Storage Implementation Patterns

Overview

Shipkit uses browser local storage as a fallback when no database is configured. This provides a zero-config development experience while maintaining feature parity with database mode.

Core Principles

1. API Consistency

Local storage services mirror database service APIs exactly:

// Database service method
async createProject(teamId: string, name: string, userId: string): Promise<Project>

// Local storage service method
createProject(teamId: string, name: string, userId: string): LocalProject

2. Data Validation

All local storage operations include validation:

if (!projectName?.trim()) {
  throw new Error("Project name is required");
}

3. Referential Integrity

Local storage maintains relationships between entities:

// When deleting a team, remove all associated projects
const teamProjects = this.getTeamProjects(teamId);
teamProjects.forEach(project => this.deleteProject(project.id));

Storage Keys

Use consistent, namespaced keys for local storage:

const STORAGE_KEYS = {
  projects: "shipkit-projects",
  projectMembers: "shipkit-project-members",
  teams: "shipkit-teams",
  teamMembers: "shipkit-team-members",
  users: "shipkit-users"
} as const;

Utility Functions

Safe Storage Access

Always check if we're in a browser environment:

function isClient(): boolean {
  return typeof window !== "undefined";
}

function getFromStorage<T>(key: string): T[] {
  if (!isClient()) return [];

  try {
    const item = localStorage.getItem(key);
    return item ? JSON.parse(item) : [];
  } catch (error) {
    console.warn(`Failed to parse ${key} from localStorage:`, error);
    return [];
  }
}

Date Handling

Convert date strings back to Date objects:

function parseStoredData<T>(data: any[]): T[] {
  return data.map(item => ({
    ...item,
    createdAt: new Date(item.createdAt),
    updatedAt: new Date(item.updatedAt),
    deletedAt: item.deletedAt ? new Date(item.deletedAt) : null
  }));
}