Context

Chakra is a React component library with a strong focus on accessibility.

I’ve been using it since 2022 for Acupio, my side project for managing patients for acupuncturists, which I already talked about here.

All patients followed by a practitioner were displayed on a single page, with the ability to filter by name. When no input was provided, all patients were shown.

I recently passed the 500-patient mark for one practitioner in the app… Performance was starting to become a real concern.

That’s when I discovered a Chakra pagination component, which was perfect for this use case.

Problem: it was only available in Chakra v3. It was definitely time to tackle this upgrade.

What does Chakra v3 bring?

The official migration guide is very comprehensive, a lot has changed.

  • Improved rendering performance thanks to a new styling system
  • Better TypeScript type inference
  • Polymorphism improvements with the asChild pattern

In this article, I’ll focus on what was the most challenging for me: adopting the Compound Pattern.

Paradigm shift – Compound Pattern

Chakra v3 generalizes the use of the Compound Pattern across many components, which forced me to rewrite most of my components.

In an application, some components are inherently tied together. For example, a <DialogContent> component is meant to be used inside a <Dialog>. These are separate components, but they are closely related. The Compound Pattern allows you to structure them as independent yet strongly connected pieces.

I was using components like Drawer, Modal, and tables - all of which were impacted by this shift. I had to refactor them accordingly.

Git Diff on a table Before / after on a table. A Td is becoming a Table.Cell, a Tr is becoming a Table.Row

It’s not that complex, but the impact is on every component of my app. I naturally thought about using AI to help with this boring task. Isn’t that exactly the kind of use case AI is supposed to help with?

Sweet summer child GIF

Using AI for refactoring

My relationship with AI is… cautious.

Back in 2023, I used ChatGPT like many people - I looked into how it worked, but didn’t go much further in integrating it into my daily workflow.

Refactoring with AI the wrong way: switching between IDE and LLMs

I first tried copy-pasting one of my templates into a Claude conversation and asked it to migrate the component to Chakra v3.

The suggestions didn’t compile, which makes sense since it didn’t have access to my full codebase.

I discussed this on the Ladies of Code Paris Slack, and one of our members (hi Sara!) suggested starting with smaller components instead of full pages.

Since I use an Atomic Design approach, this was easy to apply. It gave me more control over the changes.

It worked better, but constantly switching between my browser (Claude) and my IDE was frustrating. I often forgot to provide necessary files.

Using Cursor agents for refactoring

Agents make those back-and-forths obsolete.

They can directly apply changes within your IDE through a chat interface — even on the free plan.

For example, I had several views with date filters across different pages.

Period Picker Component

Instead of duplicating that logic, I decided to extract it into a reusable component using a Cursor agent with this prompt:

I want you to extract this date filter into a component called PeriodPicker. Place it in the components > organisms folder. The PeriodPicker component should allow selecting a given time period. It should be used in the StatsScreen and UrssafDeclaration components. Thanks.

The advantage of using an agent is that you can review the changes like a pull request from a teammate.

Being precise in your prompt is key. Taking an atomic approach helps avoid overly complex changes that are hard to debug later.

How long does a Chakra v2 to Chakra v3 migration take?

This migration went more smoothly than I expected.

It only took me a few days, whereas I initially thought it would take several weeks.

I even considered switching libraries altogether, given the expected effort.

I only started using AI agents towards the end. In hindsight, I think I could have saved time by using them earlier — starting with the smallest components.

From what I’ve seen on Reddit, many developers have stopped using Chakra because of this major upgrade.

Preparing your migration to Chakra v3

Structuring my project with Atomic Design principles was extremely helpful once again.

I was able to start with the smallest building blocks and gradually move up to larger components and screens.

In the end, the migration only took a few days.

If I had to give advice to someone considering this upgrade:

  • Review the migration guide to identify removed components and estimate the workload
  • If possible, don’t do it alone
  • Use AI agents to assist you : start small, then scale up progressively

Good luck :)