Access control hooks and components for React. TypeScript-friendly.
MIT License
react-aclify is a highly useful package that provides a set of tools for Access Control List (ACL) in React applications. It supports TypeScript and presents an intuitive API for managing user roles and permissions.
CanAccess
component, control visibility of parts of your application based on user roles and permissions.useAclify
hook provides convenient methods (setUser
and isAuthorized
) for interacting with the user's roles and permissions in your context.# npm
npm install react-aclify
# yarn
yarn add react-aclify
# pnpm
pnpm add react-aclify
Use the createAclify
function to create the components and hook for your application:
import { createAclify } from 'react-aclify'
export const { CanAccess, useAclify, AclifyProvider } = createAclify()
For better TypeScript support, you can also pass the Roles, Permissions, and User types to the createAclify
function, so that way the components and hook will be typed accordingly:
import { createAclify } from 'react-aclify'
type Role = 'admin' | 'user'
type Permission = 'posts:read' | 'posts:create' | 'posts:delete'
type User = {
id: string
/* ... */
roles: Role[]
permissions: Permission[]
}
export const { CanAccess, useAclify, AclifyProvider } = createAclify<
Role,
Permission,
User
>()
<AclifyProvider />
The AclifyProvider
is a context provider that you use to wrap your application, or any part of it where you want to perform role or permission-based actions. The AclifyProvider
accepts the following props:
getUserRoles
: A function to get the user's roles. This function will be used internally when checking permissions.
getUserPermissions
: A function to get the user's permissions. This function will be used internally when checking permissions.
storageKey
(optional): The key to use for storing the user in local storage. The default value is '__REACT_ACLIFY_USER__'
.
Here's an example of how you can use the AclifyProvider
:
import { AclifyProvider } from '@/lib/aclify'
const App = () => (
<AclifyProvider
getUserRoles={(user) => user?.roles || []}
getUserPermissions={(user) => user?.permissions || []}
storageKey="__MY_APP_USER__" // optional (default: '__REACT_ACLIFY_USER__')
>
{/* Your application goes here */}
</AclifyProvider>
)
useAclify
The useAclify
hook is used to interact with the AclifyProvider
context. It returns an object with the following properties:
setUser
: This function is used to set the current user. It's especially useful for updating the user's information in your application, such as after the user logs in or updates their profile.
isAuthorized
: This function checks whether the user is authorized to access a certain part of the application based on their roles and permissions. It takes two parameters: an array of roles and an array of permissions, and it returns a boolean indicating whether the user is authorized.
Here's an example of how to use the useAclify
hook:
import { useAclify } from '@/lib/aclify'
const Component = () => {
const { isAuthorized, setUser } = useAclify()
const handleLogin = () => {
// After successfully logging in, you can set the user's data using setUser.
setUser({
id: '123',
name: 'John Doe',
roles: ['user'],
permissions: ['posts:read'],
})
}
return (
<div>
<button onClick={handleLogin}>Login</button>
{isAuthorized(['user'], ['posts:read']) && (
<div>Authorized to read posts</div>
)}
</div>
)
}
<CanAccess />
The CanAccess
component is a convenient way of restricting certain parts of your UI based on the user's roles and permissions.
It accepts the following props:
roles
: An array of roles. The user must have at least one of these roles to access the children of the CanAccess
component.
permissions
: An optional array of permissions. If specified, the user must also have these permissions to access the children.
children
: The content that should be rendered if the user has the required roles and permissions.
fallback
: An optional component or element to be rendered if the user does not have the required roles or permissions.
Here's an example of how to use the CanAccess
component:
import { CanAccess } from '@/lib/aclify'
const Component = () => {
return (
<div>
<CanAccess
roles={['user']}
permissions={['posts:read']}
fallback={<div>Not authorized</div>}
>
<div>Authorized to read posts</div>
</CanAccess>
</div>
)
}
Contributions to react-aclify are always welcome! If you find a bug or have an idea for a new feature, feel free to open an issue or submit a pull request. Every contribution helps make react-aclify a better tool for everyone.