4.0 marks the end of the migration to the new useCache() and useResource() implementations first introduced in 2.2. It also comes with a few other exciting features like a rewritten fetch based on the actual browser fetch API. Read below for more details and a migration guide.
Drop legacy
This marks the final stage of the rewritten selector hooks with useCacheLegacy() and useResourceLegacy() both being completely removed. These legacy versions removed in #170 are wrappers around the new versions. Because of this if you want to continue using those selectors you can simply copy the code removed in #170 into your own application.
Using fetch() out of the box
Superagent has a nice API using the Builder Pattern, as well as working server-side out of the box which made it a great default fetch implementation. However, it has not received much love recently and over time more functionality has been added to the fetch standard. Furthermore, developers have become increasingly familiar and used to it over other solutions.
For these reasons, we the default fetch implementation in Resource now uses fetch. As such, if you are targetting old (read: IE) browsers or want to run your code in node (for unit tests or server side rendering), you'll need to add a fetch polyfill. whatwg-ftech is a great choice as it works both in node and in old browsers.
For those looking to continue using superagent, the old implementation is provided as an example custom fetch function.
Along with this redesign comes some useful new ways of extending fetch for custom hooks.
Instead of fetchPlugin, there is a now a fetchOptionsPlugin which can be used to set
the fetch options like adding headers.
fetchResponse() is exposed which does the bulk of the fetching besides reading the data itself. This can be useful when building custom fetch shapes that need access to things like headers. to build their response.
New supplemental libraries
Two new libraries were introduced in the last two months. These are both compatible with v3 and v4 of Rest Hooks.
@rest-hooks/test
Previously, testing utilities had been included in rest-hooks package directly. These were pulled out into their own library and are no longer included in v4 of Rest Hooks.
@rest-hooks/legacy
Legacy is a new package that included a hook similar to useResource(), but that doesn't use Suspense. In practice this can be useful even when Suspense is used, as certain scenarios having stateful indicators for loading and error states can actually be more ergonomic. This is also essential to integrate currently with any Server Side Rendering.
Previously useStatefulResource() had been provided as example code in the docs. However, since it was not tested it would often grow incompatible as underlying changes were made to Rest Hooks itself.
Now it's just an install and import away.
Drop IE support in ES6 module
Supporting Internet Explorer can be annoying. For many it is not even a requirement for their apps, and so including library code with compatibility adapters can make the code bloated and even slower.
For this reason, those using a bundler that recognizes ES6 modules like webpack or parcel will load a somewhat modern target.
If you plan on supporting IE, you'll need to include transpiling Rest Hooks as part of your build process. Note that Create React App already does this, so no work is needed in that case.
Migration Guide
- Transpile Rest Hooks if IE is to be supported
- Remove useCacheLegacy() and useResourceLegacy()
- rest-hooks/test -> @rest-hooks/test
- fetchPlugin -> fetchOptionsPlugin, which builds on fetch options
- No more SuperagentResource export
- url() and listUrl() params are no longer optional (TypeScript)
- Remove generic signatures to any Resource.fetch() overrides
Final notes
Please try out the new release and give feedback if there are any issues or if things are working great! We've got a lot of great new features coming down the pipeline and we hope to see your contributions as well. 😊