• About The Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Usage
• Roadmap
• Contributing
  • Thanks to all lovely contributers
• License

About The Project

react-permmissions can be used to easily manage permissions globally. The package supports the basic permissions view, create, update and delete. The indication of these permissions is done via an object. The configuration and use, as well as retrieving the permissions for the developer should be simplified. This happens via a component which is responsible for rendering embedded components. Furthermore, the package contains a use-hook, through which one gets access to all permissions.

*The readme will be extended in future

Built With

• VisualStudioCode
• JavaScript
• TypeScript
• ReactJS
• NPM
• ESLint

Getting Started

The package can be downloaded via npm and yarn. After download and added to your project you have access to all compnents, hooks and types.

Prerequisites

This package is only for use in ReactJS version 18.2.0 or higher.

Functionality in lower versions is not guaranteed and will not be supported in the future.

We also recommend using TypeScript version 4.9.4 or higher. All types are integrated.

Installation

1. Install NPM packages

• npm

npm install @derhackt/react-permissions@latest

• yarn

yarn add @derhackt/react-permissions@latest

2. Wrap your project into the PermissionProvider

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

import { PermissionProvider } from "@derhackt/react-permissions";
import { permissionConfig } from "./permissionconfig"

const root = ReactDOM.createRoot(
    document.getElementById("root") as HTMLElement
);
root.render(
    <React.StrictMode>
        <PermissionProvider config={permissionConfig}>
            <App />
        </PermissionProvider>
    </React.StrictMode>
);

3. Add your config-file (example: permissionConfig.ts)

import type { TypePermissionContext } from "@derhackt/react-permissions/dist/esm/types/components/provider/PermissionProvider.types";

export const config: TypePermissionContext["config"] = {
    current: {
        permissions: {
            admin: {
                view: true,
                create: true,
                delete: true,
                update: true,
            },
            user: {
                view: true,
                create: false,
                delete: false,
                update: false,
            },
            // You can even include restriction which have no permissions as a default permission.
            // The handlers set not given permissions to false by default without to declare it.
            guest: {
                view: false,
                create: false,
                delete: false,
                update: false,
            }
        },
    },
    no_permissions_needed: true,
    // ...other optional settings
};

Optional:

• You can import types from the @derhackt/react-permissions/dist/esm/types folder.
• You can add more settings to your config:

fallback_component component to fallback when view permission is restricted. Type: JSX.Element

Example:

    fallback_component: <div>You don´t have permissions to view this page</div>

If you use react-router-dom you can add the navigation component from there to redirect

own_permission_name Object to change the default naming of the permissions. Type: Record<string, string>

Example:

    own_permission_name: {
        view: "i_can_see";
        create: "i_can_add";
        update: "i_can_change";
        delete: "i_can_remove";
    }

Usage

• Permission component

The permission component can be used to restrict view permissions. It will automatic render the fallback component from the config if the view permission is restricted.

To use the component with the noPermissionsNeeded property the setting no_permissions_needed in the config have to set to true

Example:

import { Permission } from "@derhackt/react-permissions";

// ...

<Permission noPermissionsNeeded>
    <p>no permission needed. even 'guest' can see this text.</p>
</Permission>
<Permission permissions={["admin"]}>
    <p>only 'admin' have view permission</p>
</Permission>
<Permission permissions={["user"]}>
    <p>only 'user' have view permission</p>
</Permission>
<Permission permissions={["admin", "user"]}>
    <p>'admin' and 'user' have view permission</p>
</Permission>

• usePermission hook

The hook can be used to restrict serveral handlings and functions. It also return a disable state for easy embbing into disabled-props of components like <button>

Example: usePermission-hook example

Roadmap

• [x] Adding provider
• [x] Adding component
• [x] Adding hook
• [x] Adding types
• [x] Adding README.md
• [ ] Adding DocJS
• [ ] Adding more usefull components
• [ ] Adding logged in restriction
• [ ] Adding native support for react-redux
• [ ] Adding native support for react-router-dom
• [ ] Adding native support for component-libraries like MUI
• [ ] Getting inspired by the community

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Thanks to all lovely contributers

Made with contributors-img.

License

Distributed under the MIT License. See LICENSE.txt for more information.

ReactJS and ReactJS-logo are under Creative Common Attribution 4.0 International license ReactJS-License

Logo modified by AnnoDomine