跳到主要内容

Best Practices for Local Storage Handling in ReactJS

· 阅读需 11 分钟

Introduction​

Local storage is a powerful tool for persisting data in web applications. In ReactJS, local storage can be used to store user preferences, shopping cart items, and other data that needs to persist across sessions. This article will deep dive into best practices for handling local storage in ReactJS with TypeScript, focusing on functional components and the latest version of the tech stack. We will provide real production scenarios with TypeScript code samples, design diagrams, project folder structures, unit test cases, and commands to initialize and add dependencies using Yarn.

1. Local Storage Basics​

1.1 Project Setup​

To get started, we need to set up a React project with TypeScript and add the necessary dependencies using Yarn.

Yarn Commands​

# Create a React project with TypeScript template
yarn create react-app local-storage-app --template typescript

# Navigate into the project directory
cd local-storage-app

# Add any additional dependencies if needed (e.g., testing libraries)
yarn add @testing-library/react @testing-library/jest-dom

1.2 Project Folder Structure​

project-root/
├── src/
│ ├── components/
│ │ ├── UserPreferencesComponent.tsx
│ │ ├── ShoppingCartComponent.tsx
│ ├── hooks/
│ │ └── useLocalStorage.ts
│ ├── utils/
│ │ ├── localStorageUtils.ts
│ ├── App.tsx
│ ├── index.tsx
├── tests/
│ ├── components/
│ │ ├── UserPreferencesComponent.test.tsx
│ │ ├── ShoppingCartComponent.test.tsx
│ ├── utils/
│ │ ├── localStorageUtils.test.ts
├── package.json
├── tsconfig.json
├── yarn.lock

2.1 What is Local Storage?​

Local storage is a web storage API that allows you to store key-value pairs in a web browser. It is a synchronous, persistent storage that allows developers to store data client-side. The data stored in local storage persists even after the browser is closed and reopened. Leveraging local storage in React applications with TypeScript can help maintain user state, save preferences, and reduce API calls.

2.2 Local Storage vs Session Storage​

  • Local Storage: Data persists across browser sessions.
  • Session Storage: Data is cleared when the browser session ends (e.g., when the browser is closed).

3. Local Storage Basics​

3.1 Basic API​

Local storage provides a simple API: setItem(), getItem(), and removeItem(). Data stored in local storage is accessible across browser sessions.

// Setting an item
localStorage.setItem('key', 'value');

// Getting an item
const value = localStorage.getItem('key');

// Removing an item
localStorage.removeItem('key');

3.2 Type Safety​

Use TypeScript to ensure type safety when interacting with local storage. Create utility functions or custom hooks in TypeScript to handle type-safe operations.

interface UserPreferences {
theme: string;
notifications: boolean;
}

const setUserPreferences = (preferences: UserPreferences): void => {
setLocalStorageItem('userPreferences', preferences);
};

const getUserPreferences = (): UserPreferences | null => {
return getLocalStorageItem<UserPreferences>('userPreferences');
};

3.3 Error Handling​

Handle errors gracefully when interacting with local storage. Wrap local storage operations in try-catch blocks to handle any potential errors gracefully.

export const setLocalStorageItem = <T>(key: string, value: T): void => {
try {
localStorage.setItem(key, JSON.stringify(value));
} catch (error) {
console.error(`Error setting local storage item: ${error}`);
}
};

export const getLocalStorageItem = <T>(key: string): T | null => {
try {
const item = localStorage.getItem(key);
return item ? JSON.parse(item) : null;
} catch (error) {
console.error(`Error getting local storage item: ${error}`);
return null;
}
};

3.4 Data Serialization​

Ensure that data is properly serialized and deserialized when storing and retrieving from local storage. Always serialize complex data structures as strings using JSON.stringify().

export const setLocalStorageItem = <T>(key: string, value: T): void => {
localStorage.setItem(key, JSON.stringify(value));
};

export const getLocalStorageItem = <T>(key: string): T | null => {
const item = localStorage.getItem(key);
return item ? JSON.parse(item) : null;
};

3.5 Expiration Handling​

Implement expiration handling for local storage items to ensure that stale data is not used.

interface ExpirableItem<T> {
value: T;
expiration: number;
}

export const setExpirableLocalStorageItem = <T>(key: string, value: T, expirationInMinutes: number): void => {
const expiration = new Date().getTime() + expirationInMinutes * 60 * 1000;
const item: ExpirableItem<T> = { value, expiration };
setLocalStorageItem(key, item);
};

export const getExpirableLocalStorageItem = <T>(key: string): T | null => {
const item = getLocalStorageItem<ExpirableItem<T>>(key);
if (item && item.expiration > new Date().getTime()) {
return item.value;
}
removeLocalStorageItem(key);
return null;
};

4. Best Practices​

4.1 Encapsulating Local Storage Access​

Encapsulate local storage logic inside React hooks or service functions to keep components clean. Encapsulate local storage access within utility functions to avoid code duplication and improve maintainability.

export const setLocalStorageItem = <T>(key: string, value: T): void => {
localStorage.setItem(key, JSON.stringify(value));
};

export const getLocalStorageItem = <T>(key: string): T | null => {
const item = localStorage.getItem(key);
return item ? JSON.parse(item) : null;
};

export const removeLocalStorageItem = (key: string): void => {
localStorage.removeItem(key);
};

5 More Scenarios​

5.1 Scenario 1: User Preferences​

import React, { useState, useEffect } from 'react';
import { setUserPreferences, getUserPreferences } from './localStorageUtils';

interface UserPreferences {
theme: string;
notifications: boolean;
}

const UserPreferencesComponent: React.FC = () => {
const [preferences, setPreferences] = useState<UserPreferences | null>(null);

useEffect(() => {
const storedPreferences = getUserPreferences();
if (storedPreferences) {
setPreferences(storedPreferences);
}
}, []);

const handleThemeChange = (theme: string) => {
const updatedPreferences = { ...preferences, theme } as UserPreferences;
setUserPreferences(updatedPreferences);
setPreferences(updatedPreferences);
};

const handleNotificationsChange = (notifications: boolean) => {
const updatedPreferences = { ...preferences, notifications } as UserPreferences;
setUserPreferences(updatedPreferences);
setPreferences(updatedPreferences);
};

return (
<div>
<h1>User Preferences</h1>
<div>
<label>Theme:</label>
<select value={preferences?.theme} onChange={(e) => handleThemeChange(e.target.value)}>
<option value="light">Light</option>
<option value="dark">Dark</option>
</select>
</div>
<div>
<label>Notifications:</label>
<input
type="checkbox"
checked={preferences?.notifications}
onChange={(e) => handleNotificationsChange(e.target.checked)}
/>
</div>
</div>
);
};

export default UserPreferencesComponent;

5.2 Scenario 2: Shopping Cart​

import React, { useState, useEffect } from 'react';
import { setLocalStorageItem, getLocalStorageItem, removeLocalStorageItem } from './localStorageUtils';

interface CartItem {
id: number;
name: string;
price: number;
}

const ShoppingCartComponent: React.FC = () => {
const [cartItems, setCartItems] = useState<CartItem[]>([]);

useEffect(() => {
const storedCartItems = getLocalStorageItem<CartItem[]>('cartItems');
if (storedCartItems) {
setCartItems(storedCartItems);
}
}, []);

const addToCart = (item: CartItem) => {
const updatedCartItems = [...cartItems, item];
setLocalStorageItem('cartItems', updatedCartItems);
setCartItems(updatedCartItems);
};

const removeFromCart = (id: number) => {
const updatedCartItems = cartItems.filter((item) => item.id !== id);
setLocalStorageItem('cartItems', updatedCartItems);
setCartItems(updatedCartItems);
};

return (
<div>
<h1>Shopping Cart</h1>
<ul>
{cartItems.map((item) => (
<li key={item.id}>
{item.name} - ${item.price}
<button onClick={() => removeFromCart(item.id)}>Remove</button>
</li>
))}
</ul>
<button onClick={() => addToCart({ id: Date.now(), name: 'New Item', price: 10 })}>Add Item</button>
</div>
);
};

export default ShoppingCartComponent;

6-Design Diagrams​

6.1 Component Diagram​

+-------------------+ +-------------------+ +-------------------+
| App | | UserPreferences | | ShoppingCart |
+-------------------+ +-------------------+ +-------------------+
| | |
| (1) User Preferences | |
|-------------------------->| |
| | (2) Shopping Cart |
| |-------------------------->|
| | |
| (3) Local Storage | |
|<--------------------------| |
| | |
+-------------------+ +-------------------+ +-------------------+
| App | | UserPreferences | | ShoppingCart |
+-------------------+ +-------------------+ +-------------------+

6.2 Sequence Diagram​

+-------------------+ +-------------------+ +-------------------+
| User | | UserPreferences | | Local Storage |
+-------------------+ +-------------------+ +-------------------+
| | |
| (1) Change Theme | |
|-------------------------->| |
| | (2) Update Preferences |
| |-------------------------->|
| | |
| (3) Store Preferences | |
|<--------------------------| |
| | |
+-------------------+ +-------------------+ +-------------------+
| User | | UserPreferences | | Local Storage |
+-------------------+ +-------------------+ +-------------------+

7. Unit Test Cases​

7.1 UserPreferencesComponent.test.tsx​

import React from 'react';
import { render, fireEvent } from '@testing-library/react';
import UserPreferencesComponent from '../../src/components/UserPreferencesComponent';
import { setUserPreferences, getUserPreferences } from '../../src/utils/localStorageUtils';

jest.mock('../../src/utils/localStorageUtils', () => ({
setUserPreferences: jest.fn(),
getUserPreferences: jest.fn(),
}));

test('UserPreferencesComponent updates and retrieves preferences', () => {
(getUserPreferences as jest.Mock).mockReturnValue({ theme: 'light', notifications: true });

const { getByLabelText, getByText } = render(<UserPreferencesComponent />);

fireEvent.change(getByLabelText('Theme:'), { target: { value: 'dark' } });
expect(setUserPreferences).toHaveBeenCalledWith({ theme: 'dark', notifications: true });

fireEvent.click(getByLabelText('Notifications:'));
expect(setUserPreferences).toHaveBeenCalledWith({ theme: 'dark', notifications: false });
});

7.2 ShoppingCartComponent.test.tsx​

import React from 'react';
import { render, fireEvent } from '@testing-library/react';
import ShoppingCartComponent from '../../src/components/ShoppingCartComponent';
import { setLocalStorageItem, getLocalStorageItem, removeLocalStorageItem } from '../../src/utils/localStorageUtils';

jest.mock('../../src/utils/localStorageUtils', () => ({
setLocalStorageItem: jest.fn(),
getLocalStorageItem: jest.fn(),
removeLocalStorageItem: jest.fn(),
}));

test('ShoppingCartComponent adds and removes items', () => {
(getLocalStorageItem as jest.Mock).mockReturnValue([{ id: 1, name: 'Item 1', price: 10 }]);

const { getByText } = render(<ShoppingCartComponent />);

fireEvent.click(getByText('Add Item'));
expect(setLocalStorageItem).toHaveBeenCalled();

fireEvent.click(getByText('Remove'));
expect(removeLocalStorageItem).toHaveBeenCalled();
});

8. Commands to Init and Add Dependencies​

# Initialize a new React project with TypeScript
yarn create react-app my-app --template typescript

# Navigate to the project directory
cd my-app

# Add Testing Library
yarn add --dev @testing-library/react @testing-library/jest-dom

9. Conclusion​

Local storage is a powerful tool for persisting data in web applications. This article provided a deep dive into best practices for handling local storage in ReactJS with TypeScript, focusing on functional components and the latest version of the tech stack. We explored real production scenarios with TypeScript code samples, design diagrams, project folder structures, unit test cases, and commands to initialize and add dependencies using Yarn.

By understanding and applying these best practices, developers can effectively manage local storage in their ReactJS applications, ensuring they remain scalable, maintainable, and performant.

10. More Samples​

10.1 Project Setup​

To get started, we need to set up a React project with TypeScript and add the necessary dependencies using Yarn.

Yarn Commands

# Create a React project with TypeScript template
yarn create react-app local-storage-app --template typescript

# Navigate into the project directory
cd local-storage-app

# Add any additional dependencies if needed (e.g., testing libraries)
yarn add @testing-library/react @testing-library/jest-dom

Project Folder Structure

local-storage-app/
├── src/
│ ├── components/
│ │ ├── LocalStorageHandler.tsx
│ │ └── UserPreferences.tsx
│ ├── hooks/
│ │ └── useLocalStorage.ts
│ ├── tests/
│ │ └── LocalStorageHandler.test.tsx
│ ├── App.tsx
│ └── index.tsx
├── public/
└── package.json

useLocalStorage.ts

// src/hooks/useLocalStorage.ts
import { useState } from 'react';

/**
* Custom hook for local storage handling
* @param key - The key under which data is stored in local storage
* @param initialValue - The initial value to use if no value is stored
* @returns A tuple containing the stored value and a function to set the value
*/
function useLocalStorage<T>(key: string, initialValue: T) {
const [storedValue, setStoredValue] = useState<T>(() => {
try {
const item = localStorage.getItem(key);
return item ? (JSON.parse(item) as T) : initialValue;
} catch (error) {
console.error('Error reading from local storage', error);
return initialValue;
}
});

/**
* Sets a new value in local storage
* @param value - The new value to store
*/
const setValue = (value: T) => {
try {
setStoredValue(value);
localStorage.setItem(key, JSON.stringify(value));
} catch (error) {
console.error('Error saving to local storage', error);
}
};

return [storedValue, setValue] as const;
}

export default useLocalStorage;

UserPreferences: Detailed Code for Using useLocalStorage in a Component

// src/components/UserPreferences.tsx
import React from 'react';
import useLocalStorage from '../hooks/useLocalStorage';

const UserPreferences: React.FC = () => {
// Using the custom hook to manage theme preference
const [theme, setTheme] = useLocalStorage<string>('theme', 'light');

// Toggles between 'light' and 'dark' themes
const toggleTheme = () => {
setTheme(theme === 'light' ? 'dark' : 'light');
};

return (
<div>
<h1>User Preferences</h1>
<p>Current theme: {theme}</p>
<button onClick={toggleTheme}>
Toggle Theme
</button>
</div>
);
};

export default UserPreferences;

Type-Safe Local Storage Utility Functions For larger applications, you might prefer having utility functions to handle local storage logic:

// src/utils/localStorageUtils.ts
export const getLocalStorageItem = <T>(key: string, defaultValue: T): T => {
try {
const storedItem = localStorage.getItem(key);
return storedItem ? (JSON.parse(storedItem) as T) : defaultValue;
} catch (error) {
console.error(`Error reading key "${key}" from local storage`, error);
return defaultValue;
}
};

export const setLocalStorageItem = <T>(key: string, value: T): void => {
try {
localStorage.setItem(key, JSON.stringify(value));
} catch (error) {
console.error(`Error setting key "${key}" in local storage`, error);
}
};

Detailed Unit Test Cases

// src/tests/useLocalStorage.test.tsx
import { renderHook, act } from '@testing-library/react';
import useLocalStorage from '../hooks/useLocalStorage';

describe('useLocalStorage hook', () => {
beforeEach(() => {
localStorage.clear();
});

it('should return initial value if no value is stored', () => {
const { result } = renderHook(() => useLocalStorage('testKey', 'initialValue'));
expect(result.current[0]).toBe('initialValue');
});

it('should save and retrieve a value', () => {
const { result } = renderHook(() => useLocalStorage('testKey', 'initialValue'));

act(() => {
result.current[1]('newValue');
});

expect(result.current[0]).toBe('newValue');
expect(localStorage.getItem('testKey')).toBe(JSON.stringify('newValue'));
});

it('should handle JSON parsing errors gracefully', () => {
localStorage.setItem('testKey', '{invalid JSON');
const { result } = renderHook(() => useLocalStorage('testKey', 'defaultValue'));
expect(result.current[0]).toBe('defaultValue');
});
});

Commands to Run Unit Tests

# Run unit tests with Yarn
yarn test

References​


This article provides a comprehensive guide to best practices for local storage handling in ReactJS with TypeScript, including detailed code samples, design diagrams, project folder structures, unit test cases, and commands to initialize and add dependencies using Yarn. By understanding and applying these practices, developers can leverage the full potential of local storage in their ReactJS projects.