Wondering what’s next for npm?Check out our public roadmap! »

    react-access

    2.0.0 • Public • Published

    react-access

    React Context driven role-access for conditional rendering of components.

    React Access Travis Builds Coverage Status

    Quick Start

    npm i react-access or yarn add react-access

    import RequireForAccess, {ReactAccessProvider} from 'react-access';
    import {MyApp, AdminMenuBar} from './my-app';
     
    // you can hydrate these to your app however you'd like on initial page load
    // or in your bundle, etc
    const userPermissions = ['APPUSER', 'CREATE', 'EDIT', 'ETC'];
     
    React.render(<ReactAccessProvider permissions={userPermissions}>
      <RequireForAccess
        permissions={['ADMIN']}
        invalidAccessComponent={<span>You do not have admin access!</span>}
      >
        {/* This will not render for our userPermissions we've provided */}
        <AdminMenuBar/>
      </RequireForAccess>
      <MyApp>
    </ReactAccessProvider>, document.getElementById('react-app'));

    Why could I use this?

    This library is intended to help with permission based rendering of UI elements. This should really always be enforced on your service layers, and through other secure measures as well - however often it can be useful to re-use certain pages & components for varying levels of permission. For example, perhaps an admin is given CAN_DELETE_ANYTHING permissions, but users are only given CAN_VIEW and CAN_CREATE. Your menu may render an option for deleting, but only for someone with the right permission set.

    Why should I not use this?

    This library utilizes the React context API. This can add a few considerations for use in your project:

    1. React folks like to say you shouldn't use context because it can/will change and is experimental. If it breaks, updating your app to newer versions may have more things to fix than you expected.
    2. Sometimes context is not the ideal solution, you're adding in extra <JSX/> which is not just a function call and may cause performance issues in really large / high performing apps. It might be easier to do something more like:
    const Component = (props) => {
      return <div>
        {hasAccess(props.userPermissions) && <SecretElement/>}
      </div>;
    };

    This library is more concerned with solving how you pass hasAccess and userPermissions all the way down your application tree to leaf nodes.

    API

    The components used in tandem to accomplish what we're aiming for are:

    1. <ReactAccessProvider>, which is a context provider designed to be the single point of entry for your user data for all (or a section) of your application.
    2. <RequireForAccess>, which is a component that leverages that context and determines if the contents should render.
    3. <ReactAccessConsumer>, which is a context consumer that provides authorizeAccess in a render callback, like so:
    <ReactAccessConsumer>
      {authorizeAccess => {
        // you can invoke `authorizeAccess` here and use the result of the
        // parent call however you'd like
      }}
    </ReactAccessConsumer>
    
    1. useAccess context hook.
    const Component = (props) => {
      const hasAccess = useAccess();
      return <div>
        {hasAccess(props.userPermissions) && <SecretElement/>}
      </div>;
    };

    Props

    Name Required Description
    children Yes Any valid-to-render React Children (usually your app, or a section of it)
    permissions Yes An array of permission strings the current user has (usually from session/server data)
    validator No You may override the default validation with your own by passing a function which will be invoked with the signature validator(userPermissions, requiredPermissions, requireAll)

    Props

    Name Required Description
    children Yes Any valid-to-render React Children you wish to be rendered if access is granted
    permissions Yes An array of permission strings this component requires in order to grant access
    invalidAccessComponent No Any valid-to-render React Children you wish to be rendered if access is not granted
    requireAll No A boolean value passed to validator that indicates all permissions passed in are required to update component

    Contributors

    (Emoji key)

    (removed briefly as the display was broken and needs fixed)

    This project (mostly) follows the all-contributors specification. Contributions of any kind are welcome!

    Install

    npm i react-access

    DownloadsWeekly Downloads

    1

    Version

    2.0.0

    License

    ISC

    Unpacked Size

    44.9 kB

    Total Files

    13

    Last publish

    Collaborators

    • avatar