Refine Pixels: A Complete Guide to Full-Stack Apps

This guide is a comprehensive, seven-part tutorial that walks you through building two full-stack apps with Refine and Supabase. By the end, you'll have a fully functional CRUD app called "Pixels" and an admin dashboard called "Pixels Admin".

The live version of the app is available here.

The final apps source codes are available on GitHub:

Pixels Client​

Source Code on GitHub

To get completed client source code simply run:

 npm create refine-app@latest -- --example pixels

Pixels Admin​

Source Code on GitHub

To get completed admin source code simply run:

 npm create refine-app@latest -- --example pixels-admin

Table of Contents​

• Part 1: Pilot & Refine Architecture
• Part 2: Setting Up the Client App
• Part 3: Adding CRUD Actions and Authentication
• Part 4: Adding Realtime Collaboration
• Part 5: Creating an Admin Dashboard with Refine
• Part 6: Implementing Role Based Access Control
• Part 7: Audit Log With Refine

Part 1: Pilot & Refine Architecture​

What is Refine ?​

Refine is a highly customizable React based framework for building CRUD apps that comes with a headless core package and supplementary "pick-and-plug" modules for the UI, backend API clients and Internationalization support.

Refine's (intentionally decapitalized) core is strongly opinionated about RESTful conventions, HTTPS networking, state management, authentication and authorization. It is, however, unopinionated about the UI and render logic. This makes it customizable according to one's choice of UI library and frameworks.

In a nutshell, you can build rock-solid CRUD apps easily using Refine✨.

Refine Architecture​

Everything in Refine is centered around the <Refine /> component, which is configured via a set of provider props that each requires a provider object to be passed in. A typical application of providers on the <Refine /> component looks like this:

import { Refine } from "@refinedev/core";
import dataProvider from "@refinedev/simple-rest";
import routerProvider from "@refinedev/react-router";
import { liveProvider } from "@refinedev/supabase";
import authProvider from "./authProvider";

<Refine
    dataProvider={dataProvider("https://api.fake-rest.refine.dev")}
    routerProvider={routerProvider}
    liveProvider={liveProvider(supabaseClient)}
    authProvider={authProvider}
    resources={[]}
    ...
/>;

The above snippet lists a few of the props and their objects.

However, rather than precisely being a component, <Refine /> is largely a monolith of provider configurations backed by a context for each. Hence, inside dataProvider, we have a standard set of methods for making API requests; inside authProvider, we have methods for dealing with authentication and authorization; inside routerProvider, we have exact definitions of routes and the components to render for that route, etc. And each provider comes with its own set of conventions and type definitions.

For example, a dataProvider object has the following signature to which any definition of a data provider conform:

const dataProvider = {
  create: ({ resource, variables, meta }) => Promise,
  createMany: ({ resource, variables, meta }) => Promise,
  deleteOne: ({ resource, id, variables, meta }) => Promise,
  deleteMany: ({ resource, ids, variables, meta }) => Promise,
  getList: ({ resource, pagination, pagination, sort, filters, meta }) =>
    Promise,
  getMany: ({ resource, ids, meta }) => Promise,
  getOne: ({ resource, id, meta }) => Promise,
  update: ({ resource, id, variables, meta }) => Promise,
  updateMany: ({ resource, ids, variables, meta }) => Promise,
  custom: ({ url, method, sort, filters, payload, query, headers, meta }) =>
    Promise,
  getApiUrl: () => "",
};

The underlying architecture involves any presentational component passed to <Refine /> to be able to consume these configured methods via corresponding hooks. Each method in a provider has a corresponding hook via which a consumer component is able to fetch data from the backend, i.e. the useList() hook is the corresponding function accessing the dataProvider.getList() provider method.

An example hook usage looks like this:

const { result } = useList<Canvas>({
  resource: "canvases",
  pagination: {
    mode: "off",
  },
  sorters: {
    initial: [
      {
        field: "created_at",
        order: "desc",
      },
    ],
  },
});

The hooks, in turn, leverage React Query hooks in order to make API calls asked by the provider methods. Here's an early sneak peek into the action under the hood:

const queryResponse = useQuery<GetListResponse<TData>, TError>(
  queryKey.list(config),
  ({ queryKey, pagination, signal }) => {
    const { pagination, meta, ...restConfig } = config || {};
    return getList<TData>({
      resource,
      ...restConfig,
      pagination,
      meta: {
        ...meta,
        queryContext: {
          queryKey,
          pageParam,
          signal,
        },
      },
    });
  },
  {
    ...queryOptions,
    onSuccess: (data) => {
      queryOptions?.onSuccess?.(data);

      const notificationConfig =
        typeof successNotification === "function"
          ? successNotification(data, { meta, config }, resource)
          : successNotification;

      handleNotification(notificationConfig);
    },
    onError: (err: TError) => {
      checkError(err);
      queryOptions?.onError?.(err);

      const notificationConfig =
        typeof errorNotification === "function"
          ? errorNotification(err, { meta, config }, resource)
          : errorNotification;

      handleNotification(notificationConfig, {
        key: `${resource}-useList-notification`,
        message: translate(
          "common:notifications.error",
          { statusCode: err.statusCode },
          `Error (status code: ${err.statusCode})`,
        ),
        description: err.message,
        type: "error",
      });
    },
  },
);

We'll be visiting code like this often, but if you examine closely you can see that Refine uses React Query to handle caching, state management as well as errors out-of-the-box.

The following diagram illustrates the interactions:

Providers and Hooks​

Refine's power lies in the abstraction of various app component logic such as authentication, authorization, routing and data fetching - inside individual providers and their corresponding hooks.

Common providers include:

• authProvider - for authentication and authorization.
• dataProvider - for CRUD operations.
• routerProvider - for defining routes, RESTful and non-RESTful.
• liveProvider - for implementing real time features.
• accessControlProvider - for access control management.
• auditLogProvider - for logging appwide activities.

For an exhaustive list of providers, please visit the Refine providers documentation from here.

Each method in these providers comes with its corresponding hook to be used from inside UI components and pages. For more details, please refer to the Refine hooks documentation starting here.

Support Packages​

Refine is inherently headless in its core API and deliberately agnostic about the UI and backend layers. Being so, it is able to provide fantastic support for major UI libraries and frameworks as well as popular backend frameworks and services. To name a few, Refine's UI support packages include Ant Design, Material UI, Chakra UI and Mantine. Backend supplementary modules include Supabase, GraphQL, and NestJS

For a complete list of all these modules, check out this page.

What is Supabase?​

Supabase is an open source alternative to Firebase. It is a hosted backend that provides a realtime database, authentication, storage, and API services.

Refine has a built-in data provider support for Supabase. You can find the advanced tutorial here.

We'll be using Supabase to build our backend for Pixels app.

A week of Refine ft. Supabase​

In this tutorial series, we will be going through most of the core features of Refine by building two apps related to drawing pixels on a canvas. This section is intended to provide an overview.

The first one, the client app - Pixels, allows a logged in user to create a canvas and draw on it together with other users. It also displays a public gallery of all canvases and a "Featured Canvases" page.

The second app, Pixels Admin is an admin dashboard that allows authorized users like editors and admins to view the list of users registered with Pixels app and manage user drawn canvases, with actions like promoting, unpromoting and deleting a canvas.

We will be building these two apps day-by-day over a period of 7 days. And while doing so, we will dive deep into the details of related providers, hooks, UI components and how Refine works behind the scenes.

As far as our features and functionalities go, we will cover most of the providers and some of the related hooks. For the UI side, we will be using the optional Ant Design package supported by Refine. For the backend, we will use a PostgreSQL database hosted on the Supabase cloud.

Here are the detailed outlines split per day:

Day One - On RefineWeek​

This post. Hello! 👋 👋 Refine welcomes you! We are here 😄 😄

Day Two - Setting Up the Client App​

We start with setting up the Pixels client app using create refine-app. We choose Refine's optional Ant Design and Supabase modules as our support packages. After initialization, we explore the boilerplate code created by create refine-app and look into the details of the dataProvider and authProvider objects and briefly discuss their mechanisms.

Day Three - Adding CRUD Actions & Authentication​

On Day Three, we start adding features to our app. We activate the resources prop for <Refine /> and using the dataProvider prop, we implement how to create a canvas, show a canvas and draw pixels on a canvas. We add a public gallery to show all canvases in a page and featured canvases in another. We also implement user authentication so that only signed in users can create and draw on a canvas - and while doing so we delve into the authProvider object.

Here is a quick sum up of specifications we cover on Day Three:

1. The Pixels app has a public gallery.
2. The public gallery has a home page of featured canvases.
3. The public gallery contains a section for all the canvases.
4. All users can view the public gallery.
5. All users can view a canvas.
6. Only logged in users can create a canvas.
7. Only logged in users can draw pixels on a canvas.
8. A user can sign up to the app using email, Google and GitHub.
9. A user can log in to the app using email, Google and GitHub.

Day Four - Adding Realtime Collaboration​

On Day Four, we add real time features to our app using the liveProvider prop on <Refine />. Real time updates on a canvas will facilitate multiple users to collaborate on it at the same time.

We are going to use Supabase's Realtime PostgreSQL CDC in order to perform row level updates on the PostgreSQL database in real time.

Day Five - Initialize and Build Pixels Admin App​

Basing on the learning from the client app, we quickly implement an admin dashboard app and explore how Refine's Ant Design support module is geared to rapidly build CRUD pages for a Refine app.

Here are the requirements for Pixels Admin:

1. Allow a user to sign up to the app using email, Google and GitHub.
2. Allow a user to log in to the app using email, Google and GitHub.
3. Build a dashboard that lists users and canvases.
4. The dashboard shows a list of all users at /users endpoint.
5. The dashboard shows a list of all canvases at /canvases endpoint.

Day Six - Add Role Based Authorization​

On Day Six, we implement user role based authorization to our admin app. While doing so, we analyze the authProvider.getPermissions() method from the standpoint of implementing authorization and customize according to our needs. We use Casbin for implementing a Role Based Access Control model and use it to define the can method of the accessControlProvider provider.

Here are the features we implement on Day Six:

1. There are two authorized roles for admin dashboard: editor and admin.
2. An editor is able to promote a canvas to "featured" status and demote it back.
3. An admin is able to promote a canvas to "featured" status and demote it back.
4. An admin is able to delete a canvas.

Day Seven - Add Audit Log to Client App and Admin App​

On the last day, with the auditLogProvider prop, we implement a log of all pixel drawing activities.Mutations for drawing pixels will be logged and saved in a logs table in our Supabase database.

We will display these logs inside a modal for each canvas both in the client Pixels app and in the Pixels Admin dashboard app. So, we will implement audit logging on both our apps.

Summary​

In this post, we introduced the Refine framework and the RefineWeek series itself. We talked about Refine's underlying architecture which consists of providers, hooks and components that help rapidly build internal tools.

We laid out the plans for building a Pixels client app and an admin dashboard app in considerable depth.

Part 2: Setting Up the Client App​

In this episode, we initialize our Pixels app using Refine and get familiar with the boilerplate code to be created with the create refine-app CLI tool.

This is Day 2 of the RefineWeek series. RefineWeek is a seven-part tutorial that aims to help developers learn the ins-and-outs of Refine's powerful capabilities and get going with Refine within a week.

Overview​

In the previous post, we got a preview of Refine's underlying architecture, especially on how Refine's core modules abstract and divide an app's logic inside individual providers and allow their methods to be easily accessed and executed with hooks from inside consumer components. This abstraction at the providers layer is where Refine shines and require extensive configuration to begin with.

In this part, we will get into the details of two important providers: namely, the dataProvider and authProvider props of our <Refine /> component. We will be building on this knowledge in the coming episodes.

The providers will be generated by the create refine-app CLI tool based on our choice, so we'll start off with setting up the Pixels app right away.

Project Setup​

For this project, we are using a PostgreSQL database hosted in the Supabase cloud. Refine comes with an optional package for Supabase that gives us dataProvider and authProviders out-of-the-box for handling requests for CRUD actions, authentication and authorization against models hosted in a Supabase server.

We are going to include Refine's Ant Design package for the UI side.

Let's go ahead and use the create refine-app CLI tool to interactively initialize the project. Navigate to a folder of your choice and run:

npm create refine-app@latest pixels

create refine-app presents us with a set of questions for choosing the libraries and frameworks we want to work with.

So, I chose the following options:

✔ Choose a project template · Refine(Vite)
✔ What would you like to name your project?: · pixels
✔ Choose your backend service to connect: · Supabase
✔ Do you want to use a UI Framework?: · Ant Design
✔ Do you want to add example pages?: · no
✔ Do you need i18n (Internationalization) support?: · no
✔ Choose a package manager: · npm

This should create a rudimentary Refine app that supports Ant Design in the UI and Supabase in the backend. If we open the app in our code editor, we can see that Refine's optional packages for Ant Design and Supabase are added to package.json:

"dependencies": {
  "@refinedev/antd": "^5.7.0",
  "@refinedev/core": "^4.5.8",
  "@refinedev/react-router-v6": "^4.1.0",
  "@refinedev/supabase": "^5.0.0",
}

We are going to use Ant Design components for our UI thanks to the @refinedev/antd module. @refinedev/supabase module allows us to use Refine's Supabase auth and data providers.

We'll cover these Supabase related providers as we add features to our app in the upcoming episodes. However, let's try building the app for now, and check what we have in the browser after running the development server. In the terminal, run the following command:

npm run dev

After that, navigate to http://localhost:5173, and lo and behold! we have a Refine app:

Exploring the App​

Let's now see what Refine scaffolded for us during initialization.

Our main point of focus is the src folder. And for now, especially the <App /> component.

If we look inside the App.tsx file, we can see a <Refine /> component crowded with passed in props:

import { GitHubBanner, Refine, WelcomePage } from "@refinedev/core";
import { RefineKbar, RefineKbarProvider } from "@refinedev/kbar";

import { useNotificationProvider } from "@refinedev/antd";
import "@refinedev/antd/dist/reset.css";

import routerProvider, {
  DocumentTitleHandler,
  UnsavedChangesNotifier,
} from "@refinedev/react-router";
import { dataProvider, liveProvider } from "@refinedev/supabase";
import { BrowserRouter, Route, Routes } from "react-router-dom";
import authProvider from "./authProvider";
import { ColorModeContextProvider } from "./contexts/color-mode";
import { supabaseClient } from "./utility";

function App() {
  return (
    <BrowserRouter>
      <GitHubBanner />
      <RefineKbarProvider>
        <ColorModeContextProvider>
          <Refine
            dataProvider={dataProvider(supabaseClient)}
            liveProvider={liveProvider(supabaseClient)}
            authProvider={authProvider}
            routerProvider={routerProvider}
            notificationProvider={useNotificationProvider}
            options={{
              syncWithLocation: true,
              warnWhenUnsavedChanges: true,
            }}
          >
            <Routes>
              <Route index element={<WelcomePage />} />
            </Routes>
            <RefineKbar />
            <UnsavedChangesNotifier />
            <DocumentTitleHandler />
          </Refine>
        </ColorModeContextProvider>
      </RefineKbarProvider>
    </BrowserRouter>
  );
}

export default App;

Today, we'll examine a few of these props so that we are ready to move to the next episode.

The <Refine /> Component​

The <Refine /> component is the entry point of a Refine app. In order to leverage the power of Refine's abstraction layers, we need to have the <Refine /> component.

Then we have to configure the <Refine /> component with the provider objects we want to use in our app. We can see that create refine-app already added the props for us inside <Refine /> out-of-the-box.

We will be using them in our Pixels app. Some provider objects like the routerProvider or the dataProvider are defined for us by Refine's core or support modules and some like the accessControlProvider have to be defined by ourselves.

// ...
- import { ColorModeContextProvider } from "./contexts/color-mode";
+ import { ConfigProvider } from "antd";

function App() {
    return (
            // ...
-                <ColorModeContextProvider>
+                <ConfigProvider>
                    <Refine
                    // ...
                    >
                        {/* ... */}
                    </Refine>
-                </ColorModeContextProvider>
+                </ConfigProvider>
         // ...
    );
}

<Refine />'s dataProvider Prop​

Refine's data provider is the context which allows the app to communicate with a backend API via a HTTP client. It subsequently makes response data returned from HTTP requests available to consumer components via a set of Refine data hooks.

If we look closely, our dataProvider prop derives a value from a call to dataProvider(supabaseClient):

import { Refine } from "@refinedev/core";
import { dataProvider } from "@refinedev/supabase";

import { supabaseClient } from "./utility";

function App() {
  return <Refine dataProvider={dataProvider(supabaseClient)} />;
}

The returned object, also called the dataProvider object, has the following signature:

const dataProvider = {
  create: ({ resource, variables, meta }) => Promise,
  createMany: ({ resource, variables, meta }) => Promise,
  deleteOne: ({ resource, id, variables, meta }) => Promise,
  deleteMany: ({ resource, ids, variables, meta }) => Promise,
  getList: ({ resource, pagination, hasPagination, sort, filters, meta }) =>
    Promise,
  getMany: ({ resource, ids, meta }) => Promise,
  getOne: ({ resource, id, meta }) => Promise,
  update: ({ resource, id, variables, meta }) => Promise,
  updateMany: ({ resource, ids, variables, meta }) => Promise,
  custom: ({ url, method, sort, filters, payload, query, headers, meta }) =>
    Promise,
  getApiUrl: () => "",
};

Each item in this object is a method that has to be defined by us or Refine's packages.

Refine supports 15+ backend dataProvider integrations as optional packages that come with distinct definitions of these methods that handle CRUD operations according to their underlying architectures. The full list can be found here.

Normally, for our own backend API, we have to define each method we need for sending http requests inside a dataProvider object as above. But since we are using the @refinedev/supabase package, dataProvider={dataProvider(supabaseClient)} makes the following object available to us:

import { DataProvider } from "@refinedev/core";
import { SupabaseClient } from "@supabase/supabase-js";
import { generateFilter, handleError } from "../utils";

export const dataProvider = (
  supabaseClient: SupabaseClient,
): Required<DataProvider> => {
  return {
    getList: async ({ resource, pagination, filters, sorters, meta }) => {
      const { current = 1, pageSize = 10, mode = "server" } = pagination ?? {};

      const query = supabaseClient.from(resource).select(meta?.select ?? "*", {
        count: "exact",
      });

      if (mode === "server") {
        query.range((current - 1) * pageSize, current * pageSize - 1);
      }

      sorters?.map((item) => {
        const [foreignTable, field] = item.field.split(/\.(.*)/);

        if (foreignTable && field) {
          query
            .select(meta?.select ?? `*, ${foreignTable}(${field})`)
            .order(field, {
              ascending: item.order === "asc",
              foreignTable: foreignTable,
            });
        } else {
          query.order(item.field, {
            ascending: item.order === "asc",
          });
        }
      });

      filters?.map((item) => {
        generateFilter(item, query);
      });

      const { data, count, error } = await query;

      if (error) {
        return handleError(error);
      }

      return {
        data: data || [],
        total: count || 0,
      } as any;
    },

    getMany: async ({ resource, ids, meta }) => {
      const query = supabaseClient.from(resource).select(meta?.select ?? "*");

      if (meta?.idColumnName) {
        query.in(meta.idColumnName, ids);
      } else {
        query.in("id", ids);
      }

      const { data, error } = await query;

      if (error) {
        return handleError(error);
      }

      return {
        data: data || [],
      } as any;
    },

    create: async ({ resource, variables, meta }) => {
      const query = supabaseClient.from(resource).insert(variables);

      if (meta?.select) {
        query.select(meta.select);
      }

      const { data, error } = await query;

      if (error) {
        return handleError(error);
      }

      return {
        data: (data || [])[0] as any,
      };
    },

    createMany: async ({ resource, variables, meta }) => {
      const query = supabaseClient.from(resource).insert(variables);

      if (meta?.select) {
        query.select(meta.select);
      }

      const { data, error } = await query;

      if (error) {
        return handleError(error);
      }

      return {
        data: data as any,
      };
    },

    update: async ({ resource, id, variables, meta }) => {
      const query = supabaseClient.from(resource).update(variables);

      if (meta?.idColumnName) {
        query.eq(meta.idColumnName, id);
      } else {
        query.match({ id });
      }

      if (meta?.select) {
        query.select(meta.select);
      }

      const { data, error } = await query;
      if (error) {
        return handleError(error);
      }

      return {
        data: (data || [])[0] as any,
      };
    },

    updateMany: async ({ resource, ids, variables, meta }) => {
      const response = await Promise.all(
        ids.map(async (id) => {
          const query = supabaseClient.from(resource).update(variables);

          if (meta?.idColumnName) {
            query.eq(meta.idColumnName, id);
          } else {
            query.match({ id });
          }

          if (meta?.select) {
            query.select(meta.select);
          }

          const { data, error } = await query;
          if (error) {
            return handleError(error);
          }

          return (data || [])[0] as any;
        }),
      );

      return {
        data: response,
      };
    },

    getOne: async ({ resource, id, meta }) => {
      const query = supabaseClient.from(resource).select(meta?.select ?? "*");

      if (meta?.idColumnName) {
        query.eq(meta.idColumnName, id);
      } else {
        query.match({ id });
      }

      const { data, error } = await query;
      if (error) {
        return handleError(error);
      }

      return {
        data: (data || [])[0] as any,
      };
    },

    deleteOne: async ({ resource, id, meta }) => {
      const query = supabaseClient.from(resource).delete();

      if (meta?.idColumnName) {
        query.eq(meta.idColumnName, id);
      } else {
        query.match({ id });
      }

      const { data, error } = await query;
      if (error) {
        return handleError(error);
      }

      return {
        data: (data || [])[0] as any,
      };
    },

    deleteMany: async ({ resource, ids, meta }) => {
      const response = await Promise.all(
        ids.map(async (id) => {
          const query = supabaseClient.from(resource).delete();

          if (meta?.idColumnName) {
            query.eq(meta.idColumnName, id);
          } else {
            query.match({ id });
          }

          const { data, error } = await query;
          if (error) {
            return handleError(error);
          }

          return (data || [])[0] as any;
        }),
      );

      return {
        data: response,
      };
    },

    getApiUrl: () => {
      throw Error("Not implemented on refine-supabase data provider.");
    },

    custom: () => {
      throw Error("Not implemented on refine-supabase data provider.");
    },
  };
};

We don't have to get into the mind of the people at Refine yet, but if we skim over closely, the dataProvider object above has pretty much every method we need to perform all CRUD operations against a Supabase database. Notable methods we are going to use in our app are: create(), getOne(), getList() and update().

For the details of how these methods work, please take your time to scan through the dataProvider API reference.

In order to get the Supabase dataProvider object to deliver, first a supabaseClient has to be set up.

Refine's supabaseClient​

If we look inside src/utility/, we have a supabaseClient.ts file containing the credentials of a client that provides us access to a Supabase backend:

import { createClient } from "@refinedev/supabase";

const SUPABASE_URL = "https://ifbdnkfqbypnkmwcfdes.supabase.co";
const SUPABASE_KEY =
  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImlmYmRua2ZxYnlwbmttd2NmZGVzIiwicm9sZSI6ImFub24iLCJpYXQiOjE2NzA5MTgzOTEsImV4cCI6MTk4NjQ5NDM5MX0.ThQ40H-xay-Hi5cf7H9mKccMCvAX3iCvYVJDe0KiHtw";

export const supabaseClient = createClient(SUPABASE_URL, SUPABASE_KEY, {
  db: {
    schema: "public",
  },
  auth: {
    persistSession: true,
  },
});

This file was also generated for us by create refine-app using Refine's Supabase package.

Inside <Refine /> component, we are getting the value of the dataProvider prop by passing in supabaseClient to the dataProvider() function imported from this package:

import { Refine } from "@refinedev/core";
import { dataProvider } from "@refinedev/supabase";

import { supabaseClient } from "./utility";

function App() {
  return <Refine dataProvider={dataProvider(supabaseClient)} />;
}

We need to tweak the supabaseClient.ts file with our own credentials, which we will do when we add resources to our app.

If we inspect further, setting up Supabase with Refine helps us enable not only the dataProvider prop, but also the authProvider and liveProvider props inside <Refine />. This is because they all depend on supabaseClient to send http requests. We'll explore the liveProvider prop on Day 4, but let's also look at the authProvider here to enhance our understanding.

<Refine />'s authProvider Prop​

We can clearly see in our <Refine /> component that create refine-app already enabled the authProvider prop by passing in the corresponding object for us:

authProvider = { authProvider };

Earlier on, the authProvider object was already created by create refine-app inside the authProvider.ts file:

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

import { supabaseClient } from "../utility";

export const authProvider: AuthProvider = {
  login: async ({ email, password, providerName }) => {
    try {
      // sign in with oauth
      if (providerName) {
        const { data, error } = await supabaseClient.auth.signInWithOAuth({
          provider: providerName,
        });

        if (error) {
          return {
            success: false,
            error,
          };
        }

        if (data?.url) {
          return {
            success: true,
          };
        }
      }

      // sign in with email and password
      const { data, error } = await supabaseClient.auth.signInWithPassword({
        email,
        password,
      });

      if (error) {
        return {
          success: false,
          error,
        };
      }

      if (data?.user) {
        return {
          success: true,
        };
      }
    } catch (error: any) {
      return {
        success: false,
        error,
      };
    }

    return {
      success: false,
      error: {
        message: "Login failed",
        name: "Invalid email or password",
      },
    };
  },
  register: async ({ email, password }) => {
    try {
      const { data, error } = await supabaseClient.auth.signUp({
        email,
        password,
      });

      if (error) {
        return {
          success: false,
          error,
        };
      }

      if (data) {
        return {
          success: true,
        };
      }
    } catch (error: any) {
      return {
        success: false,
        error,
      };
    }

    return {
      success: false,
      error: {
        message: "Register failed",
        name: "Invalid email or password",
      },
    };
  },
  forgotPassword: async ({ email }) => {
    try {
      const { data, error } = await supabaseClient.auth.resetPasswordForEmail(
        email,
        {
          redirectTo: `${window.location.origin}/update-password`,
        },
      );

      if (error) {
        return {
          success: false,
          error,
        };
      }

      if (data) {
        return {
          success: true,
        };
      }
    } catch (error: any) {
      return {
        success: false,
        error,
      };
    }

    return {
      success: false,
      error: {
        message: "Forgot password failed",
        name: "Invalid email",
      },
    };
  },
  updatePassword: async ({ password }) => {
    try {
      const { data, error } = await supabaseClient.auth.updateUser({
        password,
      });

      if (error) {
        return {
          success: false,
          error,
        };
      }

      if (data) {
        return {
          success: true,
          redirectTo: "/",
        };
      }
    } catch (error: any) {
      return {
        success: false,
        error,
      };
    }

    return {
      success: false,
      error: {
        message: "Update password failed",
        name: "Invalid password",
      },
    };
  },
  logout: async () => {
    const { error } = await supabaseClient.auth.signOut();

    if (error) {
      return {
        success: false,
        error,
      };
    }

    return {
      success: true,
      redirectTo: "/",
    };
  },
  onError: async (_error: any) => ({}),
  check: async () => {
    try {
      const { data } = await supabaseClient.auth.getSession();
      const { session } = data;

      if (!session) {
        return {
          authenticated: false,
          error: {
            message: "Check failed",
            name: "Session not found",
          },
          logout: true,
        };
      }
    } catch (error: any) {
      return {
        authenticated: false,
        error: error,
        logout: true,
      };
    }

    return {
      authenticated: true,
    };
  },
  getPermissions: async () => {
    try {
      const user = await supabaseClient.auth.getUser();

      if (user) {
        return user.data.user?.role;
      }
    } catch (error) {
      console.error(error);
      return;
    }
  },
  getIdentity: async () => {
    try {
      const { data } = await supabaseClient.auth.getUser();

      if (data?.user) {
        return {
          ...data.user,
          name: data.user.email,
        };
      }

      return null;
    } catch (error: any) {
      console.error(error);

      return null;
    }
  },
};

This object has all the methods we need to implement an email / password based authentication and authorization system in our app.

Notice, as mentioned before, that authProvider relies on supabaseClient to connect to our Supabase database. So, in this case, our authProvider was generated as part of the Supabase package.

As we can infer by now, although we have stated that Refine performs and manages a lot of heavylifting and simplifies the app logic by dividing concerns into separate contexts, providers and hooks, configuring all these providers is a heavy task itself.

It, fortunately, makes configuration easier by composing individual providers inside a single object.

These are pretty much the essentials we should get familiar with in order to accept the invitation to add resources to the <Refine /> component.

Summary​

In this post, we went through the process of initializing our Pixels app with a Supabase hosted PostgreSQL database and Ant Design UI framework.

We then explored the boilerplate code created by create refine-app using Refine's Supabase support package, especially the files related to dataProvider and authProvider props of the <Refine /> component. We touched on setting supabaseClient which is used by these providers to send HTTP requests to the Supabase backend.

In the next article, we will use these providers to implement RESTful CRUD actions for creating a canvas, showing a canvas, drawing pixels on it and showing a public gallery that lists canvases. We will also add authentication to our app.

Part 3: Adding CRUD Actions and Authentication​

In this post, we build on our existing understanding of dataProvider and authProvider props of <Refine /> to implement CRUD operations in our Pixels app that we initialized in the previous post. While doing so, we discuss the roles of <Refine /> component's resources and routerProvider props as well.

CRUD actions are supported by the Supabase data provider we chose for our project and in this post we use them to build a public gallery of canvases. We implement creation and displaying of individual canvases as well as drawing on them. We also add authentication features supported by the supabaseClient we discussed on Day Two of the RefineWeek series.

This is Day Three and RefineWeek is a seven-part tutorial that aims to help developers learn the ins-and-outs of Refine's powerful capabilities and get going with Refine within a week.

Overview​

In the last episode, we explored Refine's auth and data providers in significant detail. We saw that <Refine />'s dataProvider and authProvider props were set to support Supabase thanks to the @refinedev/supabase package.

We mentioned that dataProvider methods allow us to communicate with API endpoints and authProvider methods help us with authentication and authorization. We are able to access and invoke these methods from consumer components via their corresponding hooks.

In this post, we will be leveraging Supabase dataProvider methods to implement CRUD operations for a canvases resource. We are going to start by adding canvases as a resource on which we will be able to perform create, show and list actions. We will first work on a public gallery that lists all canvases and a dashboard page that shows a selection of featured canvases by implementing the list action. We will allow users to perform the canvas create action from a modal. Then we will also implement the show action for a canvas.

We will then apply Supabase auth provider to allow only logged in users to carry out create actions on canvases and pixels. On the way, we will explore how Refine does the heavylifting under the hood for us with React Query, and its own set of providers and hooks - making CRUD operations implementation a breeze.

But before we start, we have to set up Supabase with our database tables and get the access credentials.

Setting Up Supabase for Refine​

For this app, we are using a PostgreSQL database for our backend. Our database will be hosted in the Supabase cloud. In order to set up a PostgreSQL server, we need to sign up with Supabase first.

After signing up and logging in to a developer account, we have to complete the following steps:

1. Create a PostgreSQL server with an appropriate name.
2. Create necessary tables in the database and add relationships.
3. Get API keys provided by Supabase for the server and set up supabaseClient inside our Refine project.

Below, we go over these steps one by one.

1. Creating a PostgreSQL Server with Supabase​

Creating a database server is quite intuitive in Supabase. Just go over to your organization's dashboard and start doing something. For me, I have initialized a server with the name refine-pixels under a free tier. If you need a quick hand, please follow this quickstart guide.

2. Adding Tables to a Supabase Database​

For our app, we have four tables: auth.users, public.users, canvases and pixels. The entity relational diagram for our database looks like this:

We have a fifth, logs table which we are going to use for audit logging with the auditLogProvider on Day Seven. However, as we are progressing step by step, we are not concerned with that at the moment. We will be adding the logs table on its day.

In order to add the above tables to your Supabase database, please follow the below instructions:

2.1 auth.users Table

The auth.users table is concerned with authentication in our app. It is created by Supabase as part of its authentication module, so we don't need to do anything about it.

Supabase supports a myriad of third party authentication providers as well as user input based email / password authentication. In our app, we'll implement GitHub authentication besides the email / password based option.

2.2 public.users Table

Supabase doesn't allow a client to query the auth.users table for security reasons. So, we need to create a shadow of the auth.users table in public.users with additional columns. We need this shadow table to be able to query user information, such as avatar_url and roles from this table.

So, in order to create the public.users table, go ahead and run this SQL script in the SQL Editor of your Supabase project dashboard:

-- Create a table for public users
create table users (
  id uuid references auth.users not null primary key,
  updated_at timestamp with time zone,
  username text unique,
  full_name text,
  avatar_url text
);

-- This trigger automatically creates a public.users entry when a new user signs up via Supabase Auth.
-- See https://supabase.com/docs/guides/auth/managing-user-data#using-triggers for more details.
create or replace function public.handle_new_public_user()
returns trigger as $$
begin
  insert into public.users (id, full_name, avatar_url)
  values (new.id, new.raw_user_meta_data->>'full_name', new.raw_user_meta_data->>'avatar_url');
  return new;
end;
$$ language plpgsql security definer;
create trigger on_auth_user_created
  after insert on auth.users
  for each row execute procedure public.handle_new_public_user();

-- Set up Storage!
insert into storage.buckets (id, name)
  values ('avatars', 'avatars');

-- Set up access controls for storage.
-- See https://supabase.com/docs/guides/storage#policy-examples for more details.
create policy "Avatar images are publicly accessible." on storage.objects
  for select using (bucket_id = 'avatars');

create policy "Anyone can upload an avatar." on storage.objects
  for insert with check (bucket_id = 'avatars');

2.3 canvases Table

For the canvases table, run this SQL script inside the Supabase SQL Editor:

create table canvases (
  id text unique primary key not null,
  user_id uuid references users on delete cascade not null,
  name text not null,
  width int8 not null,
  height int8 not null,
  is_featured boolean default false not null,

  created_at timestamp with time zone default timezone('utc'::text, now()) not null,
  updated_at timestamp with time zone default timezone('utc'::text, now()) not null
);

2.4 pixels Table

For the pixels table run the following SQL script:

create table pixels (
  id int8 generated by default as identity primary key not null,
  user_id uuid references users on delete cascade not null,
  canvas_id text references canvases on delete cascade not null,
  x int8 not null,
  y int8 not null,
  color text not null,

  created_at timestamp with time zone default timezone('utc'::text, now()) not null
);

If you want to create the tables using Table Editor from the dashboard, feel free to use the Supabase docs.

2.5 Relationship Between Tables

If we look closely, public.users table has a one-to-many relationship with canvases and a canvas must belong to a user.

Similarly canvases also has a one-to-many relationship with pixels. A canvas has many pixels and a pixel must belong to a canvas.

Also, public.users has a one-to-many relationship with pixels.

2.5 Disable RLS

For simplicity, we'll disable Row Level Security:

3. Set Up supabaseClient for <Refine /> Providers​

Now it's time to use the Supabase hosted database server inside our Refine app.

First, we need to get the access credentials for our server from the Supabase dashboard. We can avail them by following this section in the Supabase quickstart guide.

I recommend storing these credentials in a .env file:

VITE_SUPABASE_URL=YOUR_SUPABASE_URL
VITE_SUPABASE_KEY=YOUR_SUPABASE_KEY

Doing so will let us use these credentials to update the supabaseClient.ts file created by refine at initialization:

import { createClient } from "@refinedev/supabase";

const SUPABASE_URL = import.meta.env.VITE_SUPABASE_URL ?? "";
const SUPABASE_KEY = import.meta.env.VITE_SUPABASE_KEY ?? "";

export const supabaseClient = createClient(SUPABASE_URL, SUPABASE_KEY);

<Refine /> component's dataProvider, authProvider and liveProvider objects utilize this supabaseClient to connect to the PostgreSQL server hosted on Supabase.

With this set up, now we can introduce canvases resource and start implementing CRUD operations for our app so that we can perform queries on the canvases table.

<Refine />'s resources Prop​

If we look at our initial App.tsx component, it looks like this:

import { GitHubBanner, Refine, WelcomePage } from "@refinedev/core";
import { RefineKbar, RefineKbarProvider } from "@refinedev/kbar";

import { useNotificationProvider } from "@refinedev/antd";
import "@refinedev/antd/dist/reset.css";

import routerProvider, {
  DocumentTitleHandler,
  UnsavedChangesNotifier,
} from "@refinedev/react-router";
import { dataProvider, liveProvider } from "@refinedev/supabase";
import { BrowserRouter, Route, Routes } from "react-router-dom";
import authProvider from "./authProvider";
import { supabaseClient } from "./utility";

function App() {
  return (
    <BrowserRouter>
      <GitHubBanner />
      <RefineKbarProvider>
        <Refine
          dataProvider={dataProvider(supabaseClient)}
          liveProvider={liveProvider(supabaseClient)}
          authProvider={authProvider}
          routerProvider={routerProvider}
          notificationProvider={useNotificationProvider}
          options={{
            syncWithLocation: true,
            warnWhenUnsavedChanges: true,
          }}
        >
          <Routes>
            <Route index element={<WelcomePage />} />
          </Routes>
          <RefineKbar />
          <UnsavedChangesNotifier />
          <DocumentTitleHandler />
        </Refine>
      </RefineKbarProvider>
    </BrowserRouter>
  );
}

export default App;