Skip to main content
Version: 2.x

Migrating to OpenAPI Qraft v2

This guide outlines the steps required to migrate your project from OpenAPI Qraft v1 to v2. The new version introduces several breaking changes designed to improve developer experience and enhance the library's functionality.

info

Speed up your migration process with our automated Codemod tool 🪄!

warning

This Migration Guide is currently a work in progress 🧪

Key Changes​

1. Removal of QraftContext​

  • Change: The QraftContext has been removed in favor of a more streamlined API design in createAPIClient.
  • Impact: You'll now need to provide baseUrl and queryClient directly to the createAPIClient function. This change ensures consistent API client configuration throughout your project.

2. Simplified QueryClient Usage​

  • Change: The ability to pass a QueryClient for individual hooks or methods has been removed.
  • Impact: A single QueryClient instance is now associated with createAPIClient, simplifying the API and preventing potential configuration conflicts.

3. Deprecation and Removal of mutationFn and queryFn Methods​

  • Change: The legacy mutationFn and queryFn methods have been removed.
  • Impact: You'll need to update your code to use the new API methods introduced in v2.

4. Error Handling Enhancements​

  • Change: The requestFn now returns a structured { data, error, response } object instead of using Promise rejection.
  • Impact: This change enables more robust error handling within your application. Update your error handling logic accordingly.

5. Updates to qraftAPIClient​

  • Change: The qraftAPIClient(...) now only returns services corresponding to methods with provided callbacks.
  • Impact: Review your service definitions to ensure compatibility with this behavior.

Migration Steps​

  1. Update QraftContext Usage: Replace all QraftContext implementations by passing configuration directly to createAPIClient.
  2. Consolidate QueryClient Usage: Remove any per-hook or per-method QueryClient configurations and use the instance provided to createAPIClient.
  3. Update Legacy Methods: Replace any mutationFn and queryFn usage with their v2 equivalents, referring to the core Query and Mutation documentation.
  4. Enhance Error Handling: Update your error handling to work with the new structured response format from requestFn.
  5. Review Service Definitions: Verify that your service definitions align with the new qraftAPIClient(...) behavior.
  6. Test Thoroughly: Perform comprehensive testing to ensure all changes work as expected and no regressions are introduced.

Automated Migration 🪄​

We provide a Codemod script powered by jscodeshift to automate most of the migration process.

Run this command in your project root to apply the migrations:

npx jscodeshift@latest --extensions=tsx,ts --parser=tsx -t https://raw.githubusercontent.com/OpenAPI-Qraft/openapi-qraft/main/packages/react-client/src/migrate-to-v2-codemod.ts ./src/

This command will transform all .tsx and .ts files in your src directory. After running the script, review the changes and make any necessary manual adjustments.

Following these steps and utilizing the automated migration tool will help you smoothly transition to OpenAPI Qraft v2 while taking advantage of its improved features and capabilities.