react-confetch
Configurable Fetch exposed as a React Hook
I have written a blog post to shed some light on how you might use this and I have also included an example included in the description below. Feel free to create an issue on GitHub repository if you encounter any issues or have some doubts about this package.
This package is a wrapper around Fetch API so it will not catch CORS exceptions as it behaves just like Fetch.
What it looks like
const { result } = useConfetch({ url, ...otherConfigurationOptions })
or
const { data, error, loading, send } = useConfetch({ url, ...otherConfigurationOptions })
Install
npm install --save react-confetch
Usage
- Create a
globalConfigurationObject
for all of your fetch requests. - Wrap your components around
ConfetchContext
initialized with yourglobalConfigurationObject
. - Import the
useConfetch
hook where ever you need to fetch something. Since it's a hook it wont work outside React.
This hook accepts a configration object which can be used to override the globalConfigurationObject
.
Here is a list of configuration options (both global and local/specific) accessible to you. I'll add an explanation wherever necessary.
States of hook
state | values |
---|---|
ready |
data: null , error: null , loading: null |
fetching |
data: null , error: null , loading: true |
fetch-complete, resetting |
data: - , error: - , loading: false |
error |
data: - , error: - , loading: false |
The hook resets (reinitialized the AbortController) on completion of a fetch request. The data
and error
do not change during reset.
The data
and error
do change to null
when a new fetch request is initialized.
The hook exposes a send
function which can be used to send a fetch request as per configuration.
Global Configuration options
key | values/type/description | required | default |
---|---|---|---|
method |
Uppercase string containing an http method supported by fetch |
false |
GET ' |
headers |
object containing key-value pairs, acceptable by fetch, for example { 'Content-Type': 'application/json' } |
false |
{} |
onResponse |
function , should return a promise, accepts fetch response as argument, resolved value is what you get as the data |
false |
res => res.json |
onError |
function or null , accepts error as argument, return value is what you get as error . |
Local/Specific configuration options (hook customization)
Everything specified above as global configration and ...
key | values/type/description | required | default |
---|---|---|---|
url |
A valid url as a string |
true |
undefined |
method |
Uppercase string containing an http method supported by fetch |
false |
GET ' |
body |
object which does not throw in JSON.stringify . |
false |
null |
endpoint |
string , not required if passed in url |
false |
'' |
query |
string , not required if passed in url |
false |
'' , the error here can be a fetch exception or any unhandled exception thrown during a custom onResponse |
Local configuration takes precedence.
Example
Wrap your container with ConfetchContext
initilializing it with globalConfigurationObject
. The default value for configuration is {}.
import './index.css' import ConfetchContext from 'react-confetch'import React from 'react'import ReactDOM from 'react-dom'import App from './App' const globalFetchConfig = timeoutDuration: 3000 ReactDOM
Use the hook like this in child/wrapped components
import React from 'react'import useConfetch from 'react-confetch' const App = const convertResponseToImageData = res res const config = url: 'https://avatars.githubusercontent.com' endpoint: '/akshay-nm' body: null method: 'GET' timeoutDuration: 10 onResponse: convertResponseToImageData // this is where you add logic to handle the response, any return value will be set as data // onError: err => {}, // you can pass an error handler too, any return values will be assigned to error // any error thrown is returned as error be default const data loading error send = return <div> <div>data && <img = ='Image' /></div> <div>loading: loading ? 'yes' : 'no'</div> <div>error: error ? errormessage : '-'</div> <div> <button = => Send a fetch request </button> </div> </div>
Future
- Expose a method to
abort
fetch - Add option to enforce deduping strategies for managing requests
- Improve branching strategies currently being used (I don't have seperate branches for development and releases at the moment)
- Add contributors section in readme
- Document versioning strategy
Contributing
This is an open source project maintained as a GitHub repository. All contributions are welcome subject to they fit nicely with the direction the project is moving in. So if you
- have a new idea for a feature
- want to suggest some improvements in the current implementation
- are experiencing some issues
- have some doubts about how everything works then, just open an issue on the GitHub repository. You can jump start the process using this link.
I am also accepting any relevant Pull Requests but there is a way to how they are supposed to be crafted (This will most likely change overtime).
- Checkout the
master
branch with a name relevant to your contributions (I am not a huge fan of/
in the name, and I'd like if you use-
instead). - Commits should be signed. Checkout the documentation on how to Sign your commit for this. Don't forget to use prettier.
- Open a PR
- describe what you did
- Link an issue so that I know why you did what you did... haha
- Help me as I review what you did
- If all goes well, react with a rocket, confetti or something when I merge your changes, yay!
Alright, that's it for now...
Further reading
- Managing Fetch requests in React.js
- Using Fetch
- Fetch Basic Concepts
- Cross-Origin Resource Sharing (CORS)
- React Hooks API reference
- Testing Advanced hooks
License
MIT © akshay-nm