0
# Strapi Helper Plugin
1

2
@strapi/helper-plugin is a comprehensive development toolkit for building Strapi plugins, offering a rich collection of React components, hooks, utilities, and TypeScript types specifically designed for the Strapi ecosystem. It provides essential UI components, powerful hooks for API interactions, content management utilities, and specialized tools for plugin development including translation helpers, error handling, and RBAC integration.
3

4
## Package Information
5

6
- **Package Name**: @strapi/helper-plugin
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @strapi/helper-plugin`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  useFetchClient, 
16
  useNotification, 
17
  CheckPermissions,
18
  Form,
19
  DynamicTable 
20
} from "@strapi/helper-plugin";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { 
27
  useFetchClient, 
28
  useNotification, 
29
  CheckPermissions,
30
  Form,
31
  DynamicTable 
32
} = require("@strapi/helper-plugin");
33
```
34

35
## Basic Usage
36

37
```typescript
38
import { 
39
  useFetchClient, 
40
  useNotification, 
41
  CheckPermissions,
42
  Form 
43
} from "@strapi/helper-plugin";
44

45
function MyPluginComponent() {
46
  const { get, post } = useFetchClient();
47
  const toggleNotification = useNotification();
48
  
49
  const handleSubmit = async (data) => {
50
    try {
51
      await post('/api/my-endpoint', data);
52
      toggleNotification({
53
        type: 'success',
54
        message: 'Data saved successfully'
55
      });
56
    } catch (error) {
57
      toggleNotification({
58
        type: 'warning',
59
        message: 'Failed to save data'
60
      });
61
    }
62
  };
63

64
  return (
65
    <CheckPermissions permissions={[{ action: 'create', subject: 'plugin::my-plugin.entity' }]}>
66
      <Form onSubmit={handleSubmit}>
67
        {/* Form content */}
68
      </Form>
69
    </CheckPermissions>
70
  );
71
}
72
```
73

74
## Architecture
75

76
The @strapi/helper-plugin is organized around several key architectural patterns:
77

78
- **Component Library**: Pre-built React components for common UI patterns (forms, tables, dialogs, permission gates)
79
- **Hook System**: React hooks for common operations (API calls, notifications, permissions, state management)
80
- **Utility Functions**: Pure functions for data transformation, validation, error handling, and URL manipulation
81
- **Context Providers**: React contexts for app-level state management (authentication, permissions, content management)
82
- **Type System**: Comprehensive TypeScript types for Strapi-specific data structures and API patterns
83
- **URL State Management**: Components and hooks that synchronize state with URL parameters for deep linking
84

85
## Capabilities
86

87
### UI Components
88

89
Core React components for building consistent plugin interfaces including forms, tables, dialogs, navigation, and permission-based rendering.
90

91
```typescript { .api }
92
// Form components (deprecated - use Formik directly)
93
type FormProps = Omit<FormikFormProps, 'noValidate'>;
94
function Form(props: FormProps): JSX.Element;
95

96
// Permission components  
97
interface CheckPermissionsProps {
98
  permissions?: PermissionToCheckAgainst[];
99
  children: React.ReactNode;
100
}
101

102
type PermissionToCheckAgainst = Pick<Permission, 'action' | 'subject'> &
103
  Partial<Pick<Permission, 'actionParameters' | 'conditions' | 'properties'>>;
104
function CheckPermissions(props: CheckPermissionsProps): JSX.Element;
105

106
// Table components
107
interface DynamicTableProps<
108
  TRows extends { id: Entity.ID } = { id: Entity.ID },
109
  THeader extends TableHeader = TableHeader
110
> extends Pick<EmptyBodyTableProps, 'action'>,
111
    Pick<DSTableProps, 'footer'> {
112
  children?: React.ReactNode;
113
  contentType: string;
114
  components?: {
115
    ConfirmDialogDeleteAll?: React.ElementType;
116
    ConfirmDialogDelete?: React.ElementType;
117
  };
118
  headers?: TableHeadProps<THeader>['headers'];
119
  isLoading?: boolean;
120
  onConfirmDeleteAll?: (ids: Array<TRows['id']>) => Promise<void>;
121
  onConfirmDelete?: (id: TRows['id']) => Promise<void>;
122
  rows?: Array<TRows>;
123
  withBulkActions?: boolean;
124
  withMainAction?: boolean;
125
  renderBulkActionsBar?: (props: {
126
    selectedEntries: Array<string | number>;
127
    clearSelectedEntries: () => void;
128
  }) => React.ReactNode;
129
}
130
function DynamicTable<TRows extends { id: Entity.ID }>(props: DynamicTableProps<TRows>): JSX.Element;
131
```
132

133
[UI Components](./ui-components.md)
134

135
### Hooks
136

137
React hooks for common plugin functionality including API communication, state management, permissions, and user interactions.
138

139
```typescript { .api }
140
// HTTP client hook
141
type FetchClient = {
142
  get: <TData = any, R = AxiosResponse<TData>, TSend = any>(
143
    url: string,
144
    config?: AxiosRequestConfig<TSend>
145
  ) => Promise<R>;
146
  put: <TData = any, R = AxiosResponse<TData>, TSend = any>(
147
    url: string,
148
    data?: TSend,
149
    config?: AxiosRequestConfig<TSend>
150
  ) => Promise<R>;
151
  post: <TData = any, R = AxiosResponse<TData>, TSend = any>(
152
    url: string,
153
    data?: TSend,
154
    config?: AxiosRequestConfig<TSend>
155
  ) => Promise<R>;
156
  del: <TData = any, R = AxiosResponse<TData>, TSend = any>(
157
    url: string,
158
    config?: AxiosRequestConfig<TSend>
159
  ) => Promise<R>;
160
};
161
function useFetchClient(): FetchClient;
162

163
// Notification hook
164
interface NotificationConfig {
165
  blockTransition?: boolean;
166
  link?: NotificationLink;
167
  message?: string | TranslationMessage;
168
  onClose?: () => void;
169
  timeout?: number;
170
  title?: string | TranslationMessage;
171
  type?: 'info' | 'warning' | 'softWarning' | 'success';
172
}
173

174
interface NotificationLink {
175
  label: string | MessageDescriptor;
176
  target?: string;
177
  url: string;
178
}
179
function useNotification(): (config: NotificationConfig) => void;
180

181
// Permission hook
182
interface RBACReturn {
183
  isLoading: boolean;
184
  allowedActions: AllowedActions;
185
  setIsLoading: () => void;
186
}
187
function useRBAC(
188
  permissionsToCheck: Record<string, Permission[]>, 
189
  passedPermissions?: Permission[]
190
): RBACReturn;
191

192
type AllowedActions = Record<string, boolean>;
193
```
194

195
[Hooks](./hooks.md)
196

197
### Content Manager
198

199
Context providers and utilities for managing content types, relations, and CRUD operations within the Strapi admin interface.
200

201
```typescript { .api }
202
interface CMEditViewDataManagerContextValue {
203
  initialData: ContentType;
204
  modifiedData: ContentType;
205
  formErrors: Record<string, TranslationMessage>;
206
  layout?: Schema.CollectionType | Schema.SingleType;
207
  isCreatingEntry: boolean;
208
  hasDraftAndPublish: boolean;
209
  onChange?: (payload: { target: { name: string; type: string; value: any } }) => void;
210
  onPublish?: () => Promise<unknown>;
211
  onUnpublish?: () => Promise<unknown>;
212
}
213
function useCMEditViewDataManager(): CMEditViewDataManagerContextValue;
214

215
interface ContentType {
216
  id?: number | string;
217
  createdAt?: string;
218
  updatedAt?: string;
219
  publishedAt?: string;
220
  [key: string]: any;
221
}
222
```
223

224
[Content Manager](./content-manager.md)
225

226
### Features
227

228
Context providers for core application features including app information, notifications, permissions, tracking, and plugin extensibility.
229

230
```typescript { .api }
231
// App context
232
interface AppInfoContextValue {
233
  shouldUpdateStrapi: boolean;
234
  latestStrapiReleaseTag: string;
235
  setUserDisplayName: (name: string) => void;
236
}
237
function useAppInfo(): AppInfoContextValue;
238

239
// Notification context
240
function useNotification(): (config: NotificationConfig) => void;
241

242
// RBAC context  
243
function useRBAC(permissions: Array<{ action: string; subject: string }>): RBACReturn;
244

245
// Tracking context
246
interface TrackingEvent {
247
  name: string;
248
  properties?: Record<string, any>;
249
}
250
function useTracking(): { trackUsage: (event: TrackingEvent) => void };
251
```
252

253
[Features](./features.md)
254

255
### Utilities
256

257
Utility functions for common operations including API error handling, data transformation, file operations, internationalization, and authentication.
258

259
```typescript { .api }
260
// Error handling
261
function getAPIInnerErrors(error: any): Array<{ id: string; defaultMessage: string }>;
262
function normalizeAPIError(error: any, formatMessage: (descriptor: any) => string): any;
263

264
// HTTP utilities  
265
function getFetchClient(baseURL?: string): Promise<any>;
266
function request(url: string, options?: any): Promise<any>;
267

268
// Data transformation
269
function formatContentTypeData(data: any, contentType: any): any;
270
function contentManagementUtilRemoveFieldsFromData(data: any, fieldsToRemove: string[]): any;
271

272
// UI utilities
273
function pxToRem(value: number): string;
274
function setHexOpacity(hex: string, opacity: number): string;
275
function getFileExtension(filename: string): string;
276
```
277

278
[Utilities](./utilities.md)
279

280
## Types
281

282
Core TypeScript interfaces and types for Strapi-specific data structures, API responses, and component props.
283

284
```typescript { .api }
285
interface TranslationMessage {
286
  id: string;
287
  defaultMessage: string;
288
  values?: Record<string, any>;
289
}
290

291
interface FilterData {
292
  name: string;
293
  metadatas: {
294
    label: string;
295
    customOperators?: Array<{ intlLabel: { id: string; defaultMessage: string }; value: string }>;
296
    customInput?: React.ComponentType;
297
    options?: Array<{ label?: string; customValue: string }>;
298
    uid?: string;
299
  };
300
  fieldSchema: {
301
    type: string;
302
    options?: string[];
303
    mainField?: { name: string; type?: string };
304
  };
305
  trackedEvent?: TrackingEvent;
306
}
307

308
type ApiError = 
309
  | ApplicationError
310
  | ForbiddenError  
311
  | NotFoundError
312
  | ValidationError
313
  | UnauthorizedError;
314
```
315

316
[Types](./types.md)