Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/alan2207/react-query-auth
⚛️ Authenticate your react applications easily with react-query.
https://github.com/alan2207/react-query-auth
auth authentication context-api hooks react react-query
Last synced: 4 days ago
JSON representation
⚛️ Authenticate your react applications easily with react-query.
- Host: GitHub
- URL: https://github.com/alan2207/react-query-auth
- Owner: alan2207
- License: mit
- Created: 2021-02-13T19:51:19.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-12-08T13:08:11.000Z (about 2 months ago)
- Last Synced: 2025-01-22T01:06:49.332Z (11 days ago)
- Topics: auth, authentication, context-api, hooks, react, react-query
- Language: TypeScript
- Homepage:
- Size: 967 KB
- Stars: 376
- Watchers: 6
- Forks: 45
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# react-query-auth
[](https://www.npmjs.com/package/react-query-auth)
Authenticate your react applications easily with [React Query](https://tanstack.com/query/v4/docs/react).
## Introduction
Using React Query has allowed us to significantly reduce the size of our codebase by caching server state. However, we still need to consider where to store user data, which is a type of global application state that we need to access from many parts of the app, but is also a server state since it is obtained from a server. This library makes it easy to manage user authentication, and can be adapted to work with any API or authentication method.
## Installation
```
$ npm install @tanstack/react-query react-query-auth
```
Or if you use Yarn:
```
$ yarn add @tanstack/react-query react-query-auth
```
## Usage
To use this library, you will need to provide it with functions for fetching the current user, logging in, registering, and logging out. You can do this using the `configureAuth` function:
```ts
import { configureAuth } from 'react-query-auth';
const { useUser, useLogin, useRegister, useLogout } = configureAuth({
userFn: () => api.get('/me'),
loginFn: (credentials) => api.post('/login', credentials),
registerFn: (credentials) => api.post('/register', credentials),
logoutFn: () => api.post('/logout'),
});
```
With these hooks, you can then add authentication functionality to your app. For example, you could use the `useUser` hook to access the authenticated user in a component.
You can also use the `useLogin`, `useRegister`, and `useLogout` hooks to allow users to authenticate and log out.
```tsx
function UserInfo() {
const user = useUser();
const logout = useLogout();
if (user.isLoading) {
return
Loading ...;
}
if (user.error) {
return
{JSON.stringify(user.error, null, 2)};
}
if (!user.data) {
return
Not logged in;
}
return (
Logged in as {user.data.email}
Log out
);
}
```
The library also provides the `AuthLoader` component that can be used to handle loading states when fetching the authenticated user. You can use it like this:
```tsx
function MyApp() {
return (
Loading ...}
renderUnauthenticated={() => }
>
);
}
```
**NOTE: All hooks and components must be used within `QueryClientProvider`.**
## API Reference:
### `configureAuth`:
The `configureAuth` function takes in a configuration object and returns a set of custom hooks for handling authentication.
#### The `configureAuth` configuration object:
A configuration object that specifies the functions and keys to be used for various authentication actions. It accepts the following properties:
- **`userFn`:**
A function that is used to retrieve the authenticated user. It should return a Promise that resolves to the user object, or null if the user is not authenticated.
- **`loginFn`:**
A function that is used to log the user in. It should accept login credentials as its argument and return a Promise that resolves to the user object.
- **`registerFn`:**
A function that is used to register a new user. It should accept registration credentials as its argument and return a Promise that resolves to the new user object.
- **`logoutFn`:**
A function that is used to log the user out. It should return a Promise that resolves when the logout action is complete.
- **`userKey`:**
An optional key that is used to store the authenticated user in the react-query cache. The default value is `['authenticated-user']`.
#### The `configureAuth` returned object:
`configureAuth` returns an object with the following properties:
- **`useUser`:**
A custom hook that retrieves the authenticated user. It is a wrapper around [useQuery](https://tanstack.com/query/v4/docs/react/reference/useQuery) that uses the `userFn` and `userKey` specified in the `configAuth` configuration. The hook accepts the same options as [useQuery](https://tanstack.com/query/v4/docs/react/reference/useQuery), except for `queryKey` and `queryFn`, which are predefined by the configuration.
- **`useLogin`:**
A custom hook that logs the user in. It is a wrapper around [useMutation](https://tanstack.com/query/v4/docs/react/reference/useMutation) that uses the `loginFn` specified in the configuration. The hook accepts the same options as [useMutation](https://tanstack.com/query/v4/docs/react/reference/useMutation), except for `mutationFn`, which is set by the configuration. On success, the hook updates the authenticated user in the React Query cache using the `userKey` specified in the configuration.
- **`useRegister`:**
A custom hook that registers a new user. It is a wrapper around [useMutation](https://tanstack.com/query/v4/docs/react/reference/useMutation) that uses the `registerFn` specified in the configuration. The hook accepts the same options as [useMutation](https://tanstack.com/query/v4/docs/react/reference/useMutation), except for `mutationFn`, which is set by the configuration. On success, the hook updates the authenticated user in the React Query cache using the `userKey` specified in the configuration.
- **`useLogout`:**
A custom hook that logs the user out. It is a wrapper around [useMutation](https://tanstack.com/query/v4/docs/react/reference/useMutation) that uses the `logoutFn` specified in the configuration. The hook accepts the same options as [useMutation](https://tanstack.com/query/v4/docs/react/reference/useMutation), except for `mutationFn`, which is set by the configuration. On success, the hook removes the authenticated user from the React Query cache using the `userKey` specified in the configuration.
- **`AuthLoader`:**
A component that can be used to handle loading states when fetching the authenticated user. It accepts the following props:
- **`renderLoading`**:
A function that is called when the authenticated user is being fetched. It should return a React node that is rendered while the user is being fetched.
- **`renderUnauthenticated`**:
A function that is called when the authenticated user is not authenticated. It should return a React node that is rendered when the user is not authenticated.
- **`renderError`**:
A function that is called when an error is thrown during the authentication request. It should return a React node that is rendered when the error occurs. It receives the `Error` object which can be used during rendering. Defaults to `(error: Error) => <>{JSON.stringify(error)}>`.
- **`children`**:
A React node that is rendered when the authenticated user is successfully fetched.
If you need a more custom loading implementation, you can create your own `AuthLoader` component and use the `useUser` hook to fetch the authenticated user and handle the loading and error states yourself.
If none of the provided hooks or components meet your needs, feel free to copy the source code into your project and modify it to your liking.
## Examples:
To try out the library, check out the `examples` folder.
## Contributing
1. Clone this repo
2. Create a branch: `git checkout -b your-feature`
3. Make some changes
4. Test your changes
5. Push your branch and open a Pull Request
## LICENSE
[MIT](/LICENSE)