Skip to main content
Unlock powerful debugging and effortless query monitoring with Refine DevtoolsLearn More
RefineDocumentation
Version: 4.xx.xx

Usage with Existing Projects

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.

npm i @refinedev/core @refinedev/simple-rest
App.tsx
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)}>
        {/* You can use Refine hooks inside here */}
        <ComponentWithRefineHooks />
        <ExistingComponent1>
      </Refine>
    </ExistingProvider>
  );
}

Headless Examples​

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

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 { Refine } from "@refinedev/core";
import dataProvider from "@refinedev/simple-rest";

import { OtherComponent } from "./src/other-component";
import { RefineComponent } from "./src/refine-component";

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

export default function App() {
  return (
    <>
      <Refine dataProvider={dataProvider(API_URL)}>
        {/* You can use Refine hooks here */}
        <OtherComponent />
        <RefineComponent />
      </Refine>
    </>
  );
}
Open on CodeSandboxOpen Sandbox

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.

First, we need to install necessary packages:

npm i @refinedev/core @refinedev/react-router-v6 @refinedev/simple-rest

  • 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 { Refine } from "@refinedev/core";
import routerProvider from "@refinedev/react-router-v6";
import dataProvider from "@refinedev/simple-rest";

export function RefineContext({ children }) {
  return (
    <Refine
      routerProvider={routerProvider}
      dataProvider={dataProvider("https://api.fake-rest.refine.dev")}
      resources={[
        {
          name: "products",
          list: "/refine/products",
        },
      ]}
      options={{ syncWithLocation: true }}
    >
      {children}
    </Refine>
  );
}
Open on CodeSandboxOpen Sandbox

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.

First, we need to install necessary packages:

npm i @refinedev/core @refinedev/react-router-v6 @refinedev/antd @refinedev/simple-rest

  • 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 { Refine } from "@refinedev/core";
import dataProvider from "@refinedev/simple-rest";
import routerProvider from "@refinedev/react-router-v6";
import { RefineThemes, ThemedLayoutV2 } from "@refinedev/antd";

import { App as AntdApp, ConfigProvider } from "antd";

import "@refinedev/antd/dist/reset.css";

export function RefineContext({ children }) {
  return (
    <ConfigProvider theme={RefineThemes.Blue}>
      <AntdApp>
        <Refine
          routerProvider={routerProvider}
          dataProvider={dataProvider("https://api.fake-rest.refine.dev")}
          resources={[
            {
              name: "products",
              list: "/refine/products",
            },
          ]}
          options={{ syncWithLocation: true }}
        >
          <ThemedLayoutV2>{children}</ThemedLayoutV2>
        </Refine>
      </AntdApp>
    </ConfigProvider>
  );
}
Open on CodeSandboxOpen Sandbox

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.

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.

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.

Previous
Internationalization (i18n)
Next
Deployment