Using Refine v4 in Existing Projects | Guide

Integrating Refine into an existing project is as simple as installing @refinedev/core package and importing Refine component into your application.

Once imported, Refine component provides necessary context to all children components for Refine hooks and components to work.

Only required prop for Refine component is dataProvider. You can read more about data provider here.

Quickstart

Only needed package for Refine to work is @refinedev/core. For demonstration purposes, we will also install @refinedev/simple-rest package to use as data provider. You can use one of our data providers or create your own.

import { Refine } from "@refinedev/core";
import dataProvider from "@refinedev/simple-rest";

const API_URL = "https://api.fake-rest.refine.dev";

function App() {
  return (
    <ExistingProvider>
      <Refine dataProvider={dataProvider(API_URL)}>
        <ComponentWithRefineHooks />
        <ExistingComponent1>
      </Refine>
    </ExistingProvider>
  );
}

Headless Examples

The following example shows how to use Refine's useShow hook with an existing application.

import { ViteHeadless } from './vite/headless';

As you can see in the example below, wrapping App.tsx file with Refine component is enough to use Refine hooks inside your application.

import { NextJSAppHeadless } from './nextjs/app/headless'

As you can see in the example below, wrapping layout.tsx file with Refine component is enough to use Refine hooks & components inside your application.

import { NextJSPagesHeadless } from './nextjs/pages/headless'

As you can see in the example below, wrapping _app.tsx file with Refine component is enough to use Refine hooks & components inside your application.

Router Examples

In the following examples below, we will integrate Refine into /refine route of an existing application.

See the Routing Guide for more information.

import { ViteRouter } from './vite/router';

First, we need to install necessary packages:

:::simple

• We start by creating RefineContext component in refine/refine-context.tsx file. This file will be used to wrap /refine routes of our application.

• And then in App.tsx file, we are adding a new Route component with path="/refine" and wrapping it with RefineContext component.

• Finally, we create refine/pages/products/list.tsx file, here we can use Refine features, since it's layout is wrapped with Refine component.

:::

import { NextJSAppRouter } from './nextjs/app/router';

First, we need to install necessary packages:

:::simple

• We start by creating app/refine/layout.tsx file, this layout will be used by all pages under /refine folder.
• Then we create app/refine/products/page.tsx file, here we can use Refine features, since it's layout is wrapped with Refine component.

:::

import { NextJSPagesRouter } from './nextjs/pages/router';

First, we need to install necessary packages:

:::simple

• We start by creating src/components/layout.tsx file, this component will be conditionally rendered by pages/_app.tsx file.
• Then we create pages/_app.tsx file, here we are checking if the current file has getLayout function, if it does, we are rendering it by wrapping it with getLayout function.
• Then we create pages/refine/products.tsx file, here we are adding Page.getLayout to our component, so it will be wrapped with Refine context. Then we can use Refine features, since it's layout is wrapped with Refine component.

:::

Adding UI to Router Examples

In the following examples below, as a follow-up from the previous router examples, we will add Ant Design layout from @refinedev/antd package.

See the UI Libraries guide for more information.

import { ViteAntdLayout } from './vite/layout/antd';

First, we need to install necessary packages:

:::simple

• We start by modifying refine-context.tsx file, adding necessary imports from @refinedev/antd package.

• And then in App.tsx file, we are updating our ErrorComponent import from @refinedev/core to @refinedev/antd.

• Finally, in refine/pages/products/list.tsx file, we are importing List component and useTable hook from @refinedev/antd package.

:::

import { NextJSAppAntdLayout } from './nextjs/app/layout/antd';

First, we need to install necessary packages:

:::simple

• We start by modifying app/refine/layout.tsx file, adding necessary imports from @refinedev/antd package.
• Then we modify app/refine/products/page.tsx file, here we are using List component and useTable hook from @refinedev/antd package.

:::

import { NextJSPagesAntdLayout } from './nextjs/pages/layout/antd';

First, we need to install necessary packages:

:::simple

• We start by updating src/components/layout.tsx file, adding necessary imports from @refinedev/antd package.
• Then we modify pages/refine/products.tsx file, here we are using List component and useTable hook from @refinedev/antd package.

:::

Authentication

If want to use Refine with your existing application, probably you already have authentication in-place. In this case, in order to enable Authentication features of Refine, only thing you need to do is to implement AuthProvider's check method.

:::simple

If you want to handle Authentication with Refine from scratch, check the Authentication Guide

:::

check Method

Once you provide the check method, you can use Authenticated component and/or useIsAuthenticated hook in your application. Refine will redirect user to given login page for unauthenticated users.

import { AuthProvider } from "@refinedev/core";

export const authProvider: AuthProvider = {
  check: async () => {
    const isAuthenticated = myCheckLogic();

    if (isAuthenticated) {
      return { authenticated: true };
    }

    return {
      authenticated: false,
      redirectTo: "/my-login-page",
      error: {
        name: "Authentication Failed.",
        message: "User not found.",
      },
    };
  },
  login: async () => {
    throw new Error("Method not implemented.");
  },
  logout: async () => {
    throw new Error("Method not implemented.");
  },
  onError: async () => {
    throw new Error("Method not implemented.");
  },
};

Optional Methods

Following methods are optional, but could be useful for various use-cases.

getIdentity Method

getIdentity method can be used to enable useGetIdentity hook.

This hook is also used to rendering current user information in the header of UI Integration layouts.

• Ant Design Header Docs Header Section
• Material UI Header Docs Header Section
• Chakra UI Header Docs Header Section
• Mantine Header Docs Header Section

onError

See Error Handling section in Authentication Guide and AuthProvider's onError documentation

logout

logout method can be used to enable useLogout hook

This hook is also used to render Logout button in the sider of UI Integration layouts.

• Ant Design Header Docs Sider Section
• Material UI Header Docs Sider Section
• Chakra UI Header Docs Sider Section
• Mantine Header Docs Sider Section