README.md

React Role

React Role is lightweight role based access management solution which provides components, hooks, and helper methods for controlling access checks and user permissions throughout your entire React application.

Installation

Use npm to install:

npm install @permify/react-role

Use yarn to install:

yarn add @permify/react-role

How to use

PermifyProvider

Wrap the part of your application where you want to perform access checks with PermifyProvider. You should pass some props to PermifyProvider in order to utilize from Permify components, hooks and helper methods.

import React from "react";
import { PermifyProvider } from "@permify/react-role";

const App = () => {
    return (
        <PermifyProvider>
            {/* Application layer, Routes, ThemeProviders etc. */}
        </PermifyProvider>;
    )
};

export default App;

User Identification

In order to check user roles or permissions, you should set logged in user with setUser function. Our advice is call this method in your login functions promise.

Set the user using the usePermify hook:

import { usePermify } from '@permify/react-role';

...

const { setUser } = usePermify();

const login = async (e) => {
    const response = await login(email, password);

    setUser({
       id: "2",
       roles: ["admin", "manager"],
       permissions: ["post-create", "user-delete", "content-show"]
    })

    //
    // Continue authentication flow
    //         
};

Or using PermifyContext:

import React from "react";
import { PermifyContext } from "@permify/react-role";

const AuthComponent = () => {
    const login = (setUser) => {
        return async (event) => {
            const response = await login(email, password);

            setUser({
                id: "2",
                roles: ["admin", "manager"], 
                permissions: ["post-create", "user-delete", "content-show"]
            })

            //
            // Continue authentication flow
            // 
        };
    };

    return (
        <PermifyContext.Consumer>
            {({ setUser }) => (
                <form onSubmit={login(setUser)}>
                    {/* form layer */}
                </form>
            )}
        </PermifyContext.Consumer>; 
    )
};

export default AuthComponent;

HasAccess

HasAccess is a wrapper component that you can wrap around components or UI Layers that should only be accessible to users have authorization.

You can check roles and permissions of the user with giving them as props.

import React from "react";
import { HasAccess } from "@permify/react-role";

const AnyComponent = () => {
    return (
        ..
        ..

        <HasAccess
            roles={["admin", "manager"]} 
            permissions="user-delete" 
            renderAuthFailed={<p>You are not authorized to access!</p>}
            isLoading={<Spinner/>}
        >
            <button type="button"> Delete </button>
        </HasAccess>

        ..
        ..
    )
};

export default App;

isAuthorized(roleNames, permissionNames)

isAuthorized is a helper function that returns a Promise which resolves with true if the user is authorized for action with the given parameters, if not it resolves with false.

You should call it inside a conditional logic structure; for ex. if check for fetching protected information.

Using isAuthorized through the usePermify hook:

import React, {useState, useEffect} from "react";
import { usePermify } from "@permify/react-role";

const AnyComponent = () => {
    const { isAuthorized, isLoading } = usePermify();

    useEffect(() => {
        const fetchData = async () => {
            // Pass roles and permissions accordingly
            // You can send empty array or null for first param to check permissions only
            if (await isAuthorized(["admin", "manager"], "user-delete")) {
                // request protected info from serverß
            }
        };

        fetchData();
    },[]);

    return (
        <>  
            {isLoading && <span>Loading...</span>}
            {dataFetched &&
                //render protected component, UI Layers etc.
            }
        </>;
    )
};

export default AnyComponent;

Stargazers

❤️ Let's get connected:

License

Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0