Project Description
The project aims to develop a restapi client written in TypeScript and built on the top of Tanstack Query to query Plone 6 backend. It is possible to use this client in React/Vue/Solid/Svelte projects.
Community Benefits
This project will benefit the community by discontinuing the use of the deprecated AsyncConnect library and migrating the Server State handling to TanStack Query. This will improve data fetching capabilities and streamline the development process.
Example usage
Here's an example of how the new approach can be implemented using the @plone/client library:
import ploneClient from '@plone/client';
const client = ploneClient.initialize({
apiPath: 'http://localhost:8080/Plone',
});
const { useGetContent } = client;
const { data, isLoading } = useGetContent({ path: pathname });
This code demonstrates the utilization of the useGetContent action hook in Volto. For more details, refer to the quick-start guide.
Key Features
- The usage of
@tanstack/react-queryprovides powerful state management capabilities and brings caching benefits. - Thorough TypeScript integration ensures strong typing throughout the project.
- The incorporation of
Zodoffers runtime validation for JavaScript projects, extending its utility beyond TypeScript. - Compatibility extends not only to React-based frameworks but also to various JavaScript frameworks.
- Adoption is straightforward and effortless.
- A comprehensive collection of actions provides extensive functionality.
- Detailed documentation ensures ease of understanding and implementation.
Framework-Agnostic Approach
The inclusion of hooks supports frameworks like react and nextjs, and the library can be utilized by other frameworks by using query and mutation objects with tanstack query directly.
Modes of Usage
This package offers two distinct usage methods:
- React-based frameworks can directly utilize the actions via custom hooks.
- Other frameworks can employ the query creator function in conjunction with the suitable version of TanStack Query.
Possible future improvements:
Separate out the react-query part from @plone/client into a separate package
This would make the integration of @plone/client into other projects like volto cleaner. We could create a wrapper over @tanstack/react-query that provides our enhanced ploneClient (just like queryClient in @tanstack/react-query) to the entire package via react-context.
SSR support in @plone/client
For implementing SSR with TanStack Query, the challenge is to figure out the data dependencies for a component that is rendered on the server.
We can consider the following approaches to implement SSR:
-
Manual approach: In this approach, Server-Side Rendering (SSR) is achieved by explicitly controlling the prefetching and caching of queries using the TanStack Query library in conjunction with the @plone/client library.
Refer to official docs for more information: SSR | TanStack Query Docs -
Automatic caching approach: In this approach we detect @plone/client use in components and cache automatically on the server. It involves rendering the component twice on the server.
POC using the approach described below: GitHub - hemant-hc/tanstack-query-ssr-example: Example React React Server-Side Rendering (SSR) application using react-grid-system and react-i18nify
The inspiration for this approach came from useSSE.
For a more comprehensive view of potential enhancements, follow this link
Issues faced and their resolution:
-
Initially, I started developing this package from a react based approach. But, since this package is supposed to work with different frameworks. I decide to take a framework agnostic approach first and build the react-specific parts on top of it
-
In the Proof of Concept (PoC) phase, the initial API fetch layer relied on legacy Volto code and utilized
superagent. However, this posed issues due to incompatibility with frameworks like Next.js. After evaluating alternatives, I switched to usingaxios, a widely supported library with robust features. With guidance from Mr. Victor, the blueprint for refactoring was established. Leading to the seamless integration of axios. -
When implementing actions, testing brought challenges. Test execution order impacted outcomes, causing test flakiness. To address this, I introduced a new test configuration, ensuring ordered and isolated test runs for stable testing.
-
As the project neared completion, I focused on implementing custom hooks for actions. I realized that most of the work had already been done and I could simply create a utility function that would receive the existing query or mutation functions and return a custom hook based on them. This made the process of implementing custom hooks a lot easier and faster.
Accessing Project Contributions
For access to project contributions, kindly follow this link.
Words of Thanks to Mr. Victor and the Plone Foundation
I extend my heartfelt gratitude to my assigned mentor, Mr. Victor, and the Plone Foundation for granting me the invaluable opportunity to engage in this project. Mr. Victor's unwavering guidance and support facilitated each step of my contribution journey, making the entire process significantly smoother. The Plone Foundation's extensive documentation proved to be an invaluable resource, offering me indispensable assistance throughout the project duration.