0
# Application Setup & Core Components
1

2
Core components for setting up Refine applications with providers and resource configuration.
3

4
## Capabilities
5

6
### Refine Component
7

8
Main application wrapper that provides all Refine contexts and orchestrates the framework's functionality.
9

10
```typescript { .api }
11
/**
12
 * Main application wrapper component that provides all Refine contexts
13
 * @param props - Configuration props for Refine application
14
 * @returns JSX.Element - Refine application wrapper
15
 */
16
function Refine<TAuthProvider, TDataProvider, TRouterProvider, TNotificationProvider, TAccessControlProvider, TI18nProvider, TLiveProvider, TAuditLogProvider>(
17
  props: RefineProps<TAuthProvider, TDataProvider, TRouterProvider, TNotificationProvider, TAccessControlProvider, TI18nProvider, TLiveProvider, TAuditLogProvider>
18
): JSX.Element;
19

20
interface RefineProps<TAuthProvider, TDataProvider, TRouterProvider, TNotificationProvider, TAccessControlProvider, TI18nProvider, TLiveProvider, TAuditLogProvider> {
21
  /** Data provider for CRUD operations - can be single provider or provider map */
22
  dataProvider: TDataProvider | Record<string, TDataProvider>;
23
  /** Authentication provider for user management */
24
  authProvider?: TAuthProvider;
25
  /** Router provider for navigation and routing */
26
  routerProvider?: TRouterProvider;
27
  /** Notification provider for showing messages */
28
  notificationProvider?: TNotificationProvider;
29
  /** Access control provider for permissions */
30
  accessControlProvider?: TAccessControlProvider;
31
  /** Internationalization provider */
32
  i18nProvider?: TI18nProvider;
33
  /** Live/realtime provider for subscriptions */
34
  liveProvider?: TLiveProvider;
35
  /** Audit log provider for tracking changes */
36
  auditLogProvider?: TAuditLogProvider;
37
  /** Resource definitions for the application */
38
  resources?: ResourceProps[];
39
  /** Global options for Refine behavior */
40
  options?: RefineOptions;
41
  /** Child components to render */
42
  children?: React.ReactNode;
43
}
44

45
interface RefineOptions {
46
  /** Mutation mode for optimistic updates */
47
  mutationMode?: MutationMode;
48
  /** Timeout for undoable mutations */
49
  undoableTimeout?: number;
50
  /** Sync with location for table states */
51
  syncWithLocation?: boolean;
52
  /** Warning when leaving unsaved forms */
53
  warnWhenUnsavedChanges?: boolean;
54
  /** Project ID for telemetry */
55
  projectId?: string;
56
  /** Redirect action after mutations */
57
  redirect?: {
58
    afterCreate?: RedirectAction;
59
    afterClone?: RedirectAction;
60
    afterEdit?: RedirectAction;
61
  };
62
  /** Live mode configuration */
63
  liveMode?: LiveModeProps;
64
  /** Disable telemetry */
65
  disableTelemetry?: boolean;
66
  /** Show title in browser tab */
67
  title?: TitleProps;
68
  /** Override browser document title */
69
  documentTitleHandler?: DocumentTitleHandler;
70
  /** React Query devtools configuration */
71
  reactQuery?: {
72
    devtoolConfig?: DevToolsConfig | false | DevToolsOptions;
73
    clientConfig?: QueryClientConfig;
74
  };
75
}
76
```
77

78
**Usage Example:**
79

80
```typescript
81
import React from "react";
82
import { Refine } from "@refinedev/core";
83
import dataProvider from "@refinedev/simple-rest";
84
import authProvider from "./authProvider";
85

86
function App() {
87
  return (
88
    <Refine
89
      dataProvider={dataProvider("https://api.fake-rest.refine.dev")}
90
      authProvider={authProvider}
91
      resources={[
92
        {
93
          name: "posts",
94
          list: "/posts",
95
          create: "/posts/create",
96
          edit: "/posts/edit/:id",
97
          show: "/posts/show/:id",
98
        },
99
        {
100
          name: "categories",
101
          list: "/categories",
102
          create: "/categories/create",
103
        },
104
      ]}
105
      options={{
106
        syncWithLocation: true,
107
        warnWhenUnsavedChanges: true,
108
        mutationMode: "optimistic",
109
      }}
110
    >
111
      {/* Your app components */}
112
    </Refine>
113
  );
114
}
115
```
116

117
### Authenticated Component
118

119
Component wrapper that conditionally renders content based on authentication status.
120

121
```typescript { .api }
122
/**
123
 * Component form of useAuthenticated hook that conditionally renders content
124
 * @param props - Authentication check configuration
125
 * @returns JSX.Element - Conditionally rendered content
126
 */
127
function Authenticated(props: AuthenticatedProps): JSX.Element;
128

129
interface AuthenticatedProps {
130
  /** Required key for React reconciliation when multiple instances exist */
131
  key: React.Key;
132
  /** Where to redirect on authentication failure - true for default login page */
133
  redirectOnFail?: string | true;
134
  /** Whether to append current path as return URL in query params */
135
  appendCurrentPathToQuery?: boolean;
136
  /** Fallback content to show when not authenticated */
137
  fallback?: React.ReactNode;
138
  /** Loading content to show while checking authentication */
139
  loading?: React.ReactNode;
140
  /** Content to render when authenticated */
141
  children?: React.ReactNode;
142
  /** Additional parameters for authentication check */
143
  params?: AuthCheckParams;
144
}
145

146
interface AuthCheckParams {
147
  [key: string]: any;
148
}
149
```
150

151
**Usage Example:**
152

153
```typescript
154
import React from "react";
155
import { Authenticated } from "@refinedev/core";
156
import { LoginPage } from "./LoginPage";
157

158
function ProtectedRoute() {
159
  return (
160
    <Authenticated
161
      key="authenticated-app"
162
      fallback={<LoginPage />}
163
      loading={<div>Checking authentication...</div>}
164
    >
165
      {/* Protected app content */}
166
      <Dashboard />
167
    </Authenticated>
168
  );
169
}
170
```
171

172
### CanAccess Component
173

174
Provides access control based on user permissions for specific resources and actions.
175

176
```typescript { .api }
177
/**
178
 * Component wrapper for usecan hook that provides access control
179
 * @param props - Access control configuration
180
 * @returns JSX.Element - Conditionally rendered content based on permissions
181
 */
182
function CanAccess(props: CanAccessProps): JSX.Element;
183

184
interface CanAccessProps {
185
  /** Resource name to check permissions for */
186
  resource?: string;
187
  /** Action to check permissions for */
188
  action: string;
189
  /** Additional parameters for permission check */
190
  params?: CanParams;
191
  /** Fallback content when access is denied */
192
  fallback?: React.ReactNode;
193
  /** Callback when access is unauthorized */
194
  onUnauthorized?: (props: OnUnauthorizedProps) => void;
195
  /** Content to render when access is granted */
196
  children: React.ReactNode;
197
  /** React Query options for the permission check */
198
  queryOptions?: UseQueryOptions<CanReturnType>;
199
}
200

201
interface CanParams {
202
  /** Resource name for permission check */
203
  resource?: string;
204
  /** Action name for permission check */
205
  action?: string;
206
  /** Additional context data */
207
  [key: string]: any;
208
}
209

210
interface OnUnauthorizedProps {
211
  /** Reason for unauthorized access */
212
  reason?: string;
213
}
214

215
interface CanReturnType {
216
  /** Whether access is granted */
217
  can: boolean;
218
  /** Reason for denial if access is not granted */
219
  reason?: string;
220
}
221
```
222

223
**Usage Example:**
224

225
```typescript
226
import React from "react";
227
import { CanAccess } from "@refinedev/core";
228

229
function PostActions({ postId }: { postId: string }) {
230
  return (
231
    <div>
232
      <CanAccess
233
        resource="posts"
234
        action="edit"
235
        params={{ id: postId }}
236
        fallback={<div>No edit permission</div>}
237
      >
238
        <button>Edit Post</button>
239
      </CanAccess>
240
      
241
      <CanAccess
242
        resource="posts"
243
        action="delete"
244
        params={{ id: postId }}
245
        onUnauthorized={() => console.log("Delete not allowed")}
246
      >
247
        <button>Delete Post</button>
248
      </CanAccess>
249
    </div>
250
  );
251
}
252
```
253

254
### Error Component
255

256
Default error page component for handling application errors.
257

258
```typescript { .api }
259
/**
260
 * Default error page component for handling application errors
261
 * @param props - Error component configuration
262
 * @returns JSX.Element - Error page display
263
 */
264
function ErrorComponent(props?: ErrorComponentProps): JSX.Element;
265

266
interface ErrorComponentProps {
267
  /** Custom error message to display */
268
  message?: string;
269
  /** Additional error details */
270
  details?: string;
271
}
272
```
273

274
### Auth Page
275

276
Pre-built authentication page with login, register, forgot password, and update password forms.
277

278
```typescript { .api }
279
/**
280
 * Pre-built authentication page with multiple auth forms
281
 * @param props - Authentication page configuration
282
 * @returns JSX.Element - Authentication page with forms
283
 */
284
function AuthPage(props?: AuthPageProps): JSX.Element;
285

286
interface AuthPageProps {
287
  /** Type of authentication form to display */
288
  type?: "login" | "register" | "forgotPassword" | "updatePassword";
289
  /** Custom form fields configuration */
290
  formProps?: Record<string, any>;
291
  /** Custom rendering props */
292
  renderContent?: (content: React.ReactNode, title: React.ReactNode) => React.ReactNode;
293
}
294
```
295

296
## Types
297

298
```typescript { .api }
299
interface ResourceProps {
300
  /** Unique name identifier for the resource */
301
  name: string;
302
  /** Optional display label - defaults to name */
303
  label?: string;
304
  /** Route path for list page */
305
  list?: string | React.ComponentType;
306
  /** Route path for create page */
307
  create?: string | React.ComponentType;
308
  /** Route path for edit page */
309
  edit?: string | React.ComponentType;
310
  /** Route path for show/detail page */
311
  show?: string | React.ComponentType;
312
  /** Route path for clone page */
313
  clone?: string | React.ComponentType;
314
  /** Custom icon for the resource */
315
  icon?: React.ReactNode;
316
  /** Whether to show in navigation menu */
317
  canDelete?: boolean;
318
  /** Additional metadata */
319
  meta?: Record<string, any>;
320
  /** Parent resource for nested resources */
321
  parentName?: string;
322
}
323

324
type MutationMode = "pessimistic" | "optimistic" | "undoable";
325

326
type RedirectAction = "list" | "edit" | "show" | "create" | "clone" | false;
327

328
interface TitleProps {
329
  /** Default title */
330
  text?: string;
331
  /** Custom icon */
332
  icon?: React.ReactNode;
333
}
334

335
type DocumentTitleHandler = (params: {
336
  resource?: string;
337
  action?: string;
338
  params?: Record<string, string | number>;
339
}) => string;
340

341
interface LiveModeProps {
342
  /** Whether to enable live mode */
343
  enabled?: boolean;
344
  /** Custom live provider */
345
  provider?: LiveProvider;
346
}
347
```