Copilot Instructions Available
Download this instruction file to enhance AI agent assistance for Actions patterns in your codebase.
Actions
- Plain objects describing “what happened”
- Only source of information for the store
- Enables complete audit trail of state changes
Key Insight
Actions are the “events” in your application’s event-driven architecture—they don’t tell the state how to change, they simply announce “user clicked login button” or “API returned product list.” This declarative approach creates a complete audit trail of everything that happened in your app, powering time-travel debugging, analytics, and even replaying user sessions for bug reproduction. Think of actions as your app’s historical record: every action is a timestamped event that, when replayed in sequence, reconstructs the exact state at any point in time.
Detailed Description
Actions in frontend state management are plain JavaScript objects that describe changes to be made to the application’s state. They are the primary way to interact with the store and trigger state updates. Unlike imperative approaches where you directly modify state (“set user to X”), actions are descriptive commands (“user logged in with credentials X”).
The Redux architecture mandates that actions are the only way to change state. This constraint seems restrictive but is incredibly powerful: it means every state change is logged, trackable, and reproducible. Actions flow from UI events, API responses, timers, or any other source, through middleware, to reducers that update state.
Key characteristics:
- Plain objects - Serializable JavaScript objects (no functions, classes, or Promises)
- Type property - String constant identifying the action (convention: ‘domain/eventName’)
- Payload - Additional data needed for state update (optional but common)
- FSA compliance - Follow Flux Standard Action format for consistency
- Immutable - Action objects shouldn’t be modified after creation
Code Examples
Basic Example: Simple Action Creators
// actionTypes.js - Constants prevent typos
export const ADD_TODO = 'todos/add';
export const TOGGLE_TODO = 'todos/toggle';
export const DELETE_TODO = 'todos/delete';
// actions.js - Action creators
let nextTodoId = 0;
// Basic action creator
export function addTodo(text) {
return {
type: ADD_TODO,
payload: {
id: nextTodoId++,
text,
completed: false
}
};
}
export function toggleTodo(id) {
return {
type: TOGGLE_TODO,
payload: id
};
}
export function deleteTodo(id) {
return {
type: DELETE_TODO,
payload: id
};
}
// Usage in components
import { useDispatch } from 'react-redux';
import { addTodo, toggleTodo } from './actions';
function TodoForm() {
const dispatch = useDispatch();
const [text, setText] = useState('');
const handleSubmit = (e) => {
e.preventDefault();
dispatch(addTodo(text)); // Dispatch action
setText('');
};
return (
<form onSubmit={handleSubmit}>
<input value={text} onChange={e => setText(e.target.value)} />
<button type="submit">Add Todo</button>
</form>
);
}
Practical Example: Async Action Creators (Thunks)
// Synchronous action creators
export const fetchUsersStart = () => ({ type: 'users/fetchStart' });
export const fetchUsersSuccess = (users) => ({
type: 'users/fetchSuccess',
payload: users
});
export const fetchUsersFailure = (error) => ({
type: 'users/fetchFailure',
payload: error,
error: true // FSA standard for errors
});
// Async action creator (thunk)
export const fetchUsers = () => async (dispatch, getState) => {
// Check if already loaded
const { users } = getState();
if (users.items.length > 0 && !users.stale) {
return; // Skip fetch if cached
}
dispatch(fetchUsersStart());
try {
const response = await fetch('/api/users');
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const data = await response.json();
dispatch(fetchUsersSuccess(data));
} catch (error) {
dispatch(fetchUsersFailure(error.message));
}
};
// Usage
function UsersList() {
const dispatch = useDispatch();
const { items, loading, error } = useSelector(state => state.users);
useEffect(() => {
dispatch(fetchUsers()); // Dispatch async thunk
}, [dispatch]);
if (loading) return <Spinner />;
if (error) return <Error message={error} />;
return (
<ul>
{items.map(user => <li key={user.id}>{user.name}</li>)}
</ul>
);
}
Advanced Example: Flux Standard Actions with Redux Toolkit
import { createAction, createAsyncThunk } from '@reduxjs/toolkit';
// Simple actions with createAction
export const incrementBy = createAction('counter/incrementBy');
// Automatically generates type and payload
// With payload preparation
export const addTodo = createAction('todos/add', (text) => {
return {
payload: {
id: nanoid(),
text,
completed: false,
createdAt: new Date().toISOString()
}
};
});
// Usage
dispatch(incrementBy(5)); // { type: 'counter/incrementBy', payload: 5 }
dispatch(addTodo('Buy milk')); // Full payload auto-generated
// Async actions with createAsyncThunk
export const fetchUserById = createAsyncThunk(
'users/fetchById',
async (userId, { rejectWithValue }) => {
try {
const response = await fetch(`/api/users/${userId}`);
if (!response.ok) {
throw new Error('Failed to fetch user');
}
return await response.json();
} catch (error) {
return rejectWithValue(error.message);
}
},
{
condition: (userId, { getState }) => {
// Cancel if already loading
const { users } = getState();
if (users.loading === 'pending') {
return false;
}
}
}
);
// Auto-generates three action types:
// - 'users/fetchById/pending'
// - 'users/fetchById/fulfilled'
// - 'users/fetchById/rejected'
// Handle in slice
import { createSlice } from '@reduxjs/toolkit';
const usersSlice = createSlice({
name: 'users',
initialState: { entities: {}, loading: 'idle', error: null },
reducers: {
// Sync reducers
},
extraReducers: (builder) => {
builder
.addCase(fetchUserById.pending, (state) => {
state.loading = 'pending';
})
.addCase(fetchUserById.fulfilled, (state, action) => {
state.entities[action.payload.id] = action.payload;
state.loading = 'idle';
})
.addCase(fetchUserById.rejected, (state, action) => {
state.error = action.payload;
state.loading = 'idle';
});
}
});
// Advanced: Action batching for performance
import { batch } from 'react-redux';
export const loadDashboard = () => (dispatch) => {
batch(() => {
// Multiple dispatches batched into single render
dispatch(fetchUsers());
dispatch(fetchPosts());
dispatch(fetchComments());
});
};
// Conditional actions
export const likePost = (postId) => (dispatch, getState) => {
const state = getState();
const post = state.posts.items.find(p => p.id === postId);
if (post.likedBy.includes(state.auth.userId)) {
dispatch({ type: 'posts/unlike', payload: postId });
} else {
dispatch({ type: 'posts/like', payload: postId });
}
};
Common Mistakes
1. Including Non-Serializable Data in Actions
Mistake: Putting functions, Promises, or class instances in action payload.
// ❌ BAD: Non-serializable data
dispatch({
type: 'users/set',
payload: new User({ id: 1, name: 'Alice' }) // Class instance
});
dispatch({
type: 'data/fetch',
payload: fetch('/api/data') // Promise
});
dispatch({
type: 'callback/set',
payload: () => console.log('done') // Function
});
// Breaks Redux DevTools, persistence, time-travel debugging
// ✅ GOOD: Plain serializable objects
dispatch({
type: 'users/set',
payload: { id: 1, name: 'Alice' } // Plain object
});
// Handle async in thunks
const fetchData = () => async (dispatch) => {
const data = await fetch('/api/data');
dispatch({ type: 'data/set', payload: data }); // Only plain data
};
// Store callback IDs, not functions
dispatch({
type: 'callback/register',
payload: { callbackId: 'onComplete' } // Reference, not function
});
Why it matters: Redux requires serializable actions for DevTools, persistence, and debugging. Non-serializable data breaks these features.
2. Putting Logic in Action Creators
Mistake: Complex business logic in action creators instead of reducers/middleware.
// ❌ BAD: Logic in action creator
function updateUserAge(userId, newAge) {
const users = store.getState().users; // Accessing store directly!
const user = users.find(u => u.id === userId);
if (user.age === newAge) {
return { type: 'NO_OP' }; // Conditional logic
}
const canUpdate = newAge > 0 && newAge < 150; // Validation
if (!canUpdate) {
return {
type: 'users/updateFailed',
payload: 'Invalid age'
};
}
return {
type: 'users/updateAge',
payload: { userId, newAge, updatedAt: Date.now() }
};
}
// ✅ GOOD: Simple action creator, logic in reducer/middleware
function updateUserAge(userId, newAge) {
return {
type: 'users/updateAge',
payload: { userId, newAge }
};
}
// Validation in reducer
function usersReducer(state, action) {
if (action.type === 'users/updateAge') {
const { userId, newAge } = action.payload;
// Validation logic here
if (newAge <= 0 || newAge >= 150) {
return state; // Ignore invalid updates
}
return {
...state,
items: state.items.map(u =>
u.id === userId ? { ...u, age: newAge } : u
)
};
}
return state;
}
Why it matters: Action creators should create actions, not contain business logic. Logic belongs in reducers (sync) or middleware (async).
3. Inconsistent Action Naming
Mistake: No naming convention for action types.
// ❌ BAD: Inconsistent naming
const actions = {
addUser: { type: 'ADD_USER' }, // SCREAMING_SNAKE_CASE
deleteUser: { type: 'user-delete' }, // kebab-case
UpdateUser: { type: 'updateUser' }, // camelCase
user_fetch: { type: 'FETCH' } // snake_case, ambiguous type
};
// Hard to track, error-prone
// ✅ GOOD: Consistent naming (domain/event)
const actions = {
addUser: { type: 'users/add' },
deleteUser: { type: 'users/delete' },
updateUser: { type: 'users/update' },
fetchUser: { type: 'users/fetch' }
};
// Or Redux Toolkit approach
const usersSlice = createSlice({
name: 'users',
initialState,
reducers: {
add: (state, action) => { /* ... */ }, // Auto-generates 'users/add'
delete: (state, action) => { /* ... */ }, // Auto-generates 'users/delete'
update: (state, action) => { /* ... */ } // Auto-generates 'users/update'
}
});
Why it matters: Consistent naming improves debugging, reduces typos, and makes action logs readable. Convention: domain/event (e.g., users/add, cart/checkout).