Introduction
Switching state management libraries in a running Vue 3 app is not something you do on a random afternoon. I was already using Pinia, the go-to state library in the Vue ecosystem, and it was doing its job well enough. The app worked, my stores were reasonably organized, and nothing was on fire.
But as the project grew, the state layer started to feel heavy around the edges. Little bits of friction appeared more often: boilerplate patterns repeated across stores, devtools traces that were a bit harder to follow than I liked, and a growing need for more advanced behavior like transactions, snapshots, and smarter persistence. That’s when I started looking at Harlem as an alternative and wondered if it could give me a cleaner way to manage global state.
This post is a real-world style take on what it felt like to move from Pinia to Harlem: why I considered the switch, how I approached the migration, and what daily development feels like after the change.
Why I Looked Beyond Pinia
Pinia is a solid library. It’s lightweight, it fits nicely with the Composition API, and it’s designed to feel natural to Vue developers. You get clearly defined stores, state, getters, and actions, and you can organize your logic in a way that makes sense for most apps. For many teams, that’s all you’ll ever need.
In my case, the pain wasn’t a single dramatic issue. It was a series of small irritations that kept coming back: similar plugin setups repeated across multiple stores, patterns for persistence and error handling duplicated in different places, and a desire for a more plugin-centric approach that treated advanced behaviors as first-class rather than afterthoughts.
Over time, this made me curious. I wanted something just as capable as Pinia but maybe a bit more focused on extensibility, where features like tracing, transactions, and undo/redo were part of the ecosystem from the start. That curiosity is what led me to Harlem.
What Harlem Is
Harlem is a global state management library designed specifically for Vue 3. Its core ideas can be summed up simply:
-
Keep the library lightweight and tree-shakeable, so unused parts of your state logic don’t bloat the final bundle.
-
Keep the core unopinionated, so you can shape your architecture without fighting the library.
-
Build a plugin and extension system that makes advanced behaviors easy to plug in when you need them.
Instead of trying to do everything inside a single “store definition” pattern, Harlem leans into composables, modular stores, and a clear separation between core state and extra capabilities. You define your store, decide which extensions it needs, and then rely on plugins to wire up things like devtools, server-side rendering support, storage, transactions, and more.
Another important point is that Harlem is implemented with TypeScript in mind. The typing is strong and explicit, which helps catch mistakes early and makes refactoring much less scary.
The Project I Migrated
The app I decided to experiment on wasn’t a simple todo list. It was an internal data dashboard used daily, with real users depending on it. A few details about it:
-
Around a dozen main views, plus several nested areas.
-
Global state for authentication, user profiles, feature flags, filters, and various UI components like sidebars, dialogs, and notifications.
-
Multiple API integrations, each with its own loading and error states.
With Pinia, the structure looked familiar: useAuthStore, useUserStore, useFiltersStore, and a generic useUiStore for anything related to layout and interface state. It worked, but as the app grew, I kept running into situations where I wanted more powerful tools:
-
Cleaner and more consistent tracing of mutations and actions.
-
A reliable pattern for persistent state across sessions, especially for filters and user preferences.
-
Optional support for transactions and undo/redo in places where the user might perform complex sequences of actions.
Those requirements lined up nicely with what Harlem offered, so this project became the test bed.
Planning the Switch
Replacing a state library in a live project is risky, so I approached it carefully. The plan was simple:
-
Start with a small, isolated part of the state layer.
-
Get comfortable with Harlem in a separate sandbox project.
-
Migrate one store at a time and verify behavior thoroughly.
The filter state for the dashboard was the ideal candidate. It had clear inputs and outputs, minimal cross-store dependencies, and a visible impact on the user interface. That made it perfect for testing whether Harlem could handle real interactions without disrupting the entire app.
Before touching production code, I wired Harlem into a minimal Vue 3 demo, created a simple store, and played with plugins such as devtools and storage. Once I understood the basic patterns and confirmed they fit my mental model, I moved on to the actual migration.
Migrating a Real Store
When you look at a typical Pinia store, you see a familiar structure: state as a function that returns an object, getters for derived values, and actions for business logic and async tasks. Migrating to Harlem doesn’t mean throwing all of that away; it means re-expressing the same ideas in a slightly different pattern.
The migration of the filters store followed roughly these steps:
-
State first: I lifted the state structure from the Pinia store almost unchanged and recreated it in Harlem. The shape of the data stayed the same. That made it easy to compare old and new behavior.
-
Actions to functions: Where I previously had actions in Pinia, I now wrote dedicated functions that interacted with Harlem’s state and mutation tools. Async logic stayed the same; only the way it touched global state changed.
-
Component wiring: In components, I replaced Pinia’s
useFiltersStorewith the relevant Harlem composable. Most adjustments were around imports and how I accessed state and methods, not around the logic itself. -
Edge cases: A few minor differences around reactivity and timing appeared, especially in spots where I had previously relied on specific store initialization behavior. These were small and easy to fix once I saw them.
Overall, this first migration felt far less dramatic than it looked on paper. The concepts—state, derived values, actions—remained familiar. What changed was the way they were packaged and extended.
Plugins and Tooling
One of Harlem’s strongest ideas is the way it divides plugins and extensions.
-
Plugins act at the library level. They are registered once and can cover all stores: devtools integration, server-side rendering support, and other global behaviors.
-
Extensions act at the store level. They wrap or enrich specific stores with features like snapshots, undo/redo, or automatic persistence.
For the migrated project, this separation turned out to be very handy. I could:
-
Enable devtools integration globally and see a clear timeline of store events, mutations, and state changes across the app.
-
Add storage behavior only to the filters store and a couple of other areas that really needed persistence, instead of carrying a generic “save everything to localStorage” pattern everywhere.
-
Experiment with transactions and snapshots on a small part of the app, giving users the feeling of a safer, more controlled editing flow.
Pinia also supports plugins and has a healthy ecosystem around things like persistence and extras. The difference, for me, was how naturally Harlem’s plugin and extension model fit into my mental picture of the app. It was obvious where each concern belonged—global vs store-specific—without bending the library’s design.
Performance and Bundle Size
From a user’s point of view, the switch from Pinia to Harlem didn’t create any dramatic performance shift. Both libraries are designed to be light and efficient, and both are more than capable of handling global state in a typical Vue 3 app without becoming a bottleneck.
Where I did see a meaningful improvement was in how I thought about the bundle:
-
Because Harlem is designed to be highly tree-shakeable, it encouraged me to keep stores modular and load only what I actually needed.
-
The plugin and extension approach meant I could opt in to heavier features only in places where they made sense, rather than dragging that behavior across all stores.
This isn’t the sort of change that halves your JavaScript size overnight, but it does contribute to a sense of control. The state layer feels slimmer and more deliberate, which is exactly what you want in a growing project.
Everyday Developer Experience
After the migration of the first store and then a few more, the real question became: how does Harlem feel during everyday development?
The short answer is that it feels predictable and calm. Once you internalize the basic concepts—stores, state, mutations, actions, and extensions—working with Harlem is straightforward. You always know where to look when something goes wrong: either in the store definition, in a plugin, or in the extension that wraps that store.
TypeScript support is a big plus here. Strong typing around state and actions gives confidence during refactors. When you rename a field or adjust a type, the compiler points out what needs to change in a direct, understandable way.
The devtools experience is also solid. Being able to step through state changes, inspect payloads, and see how actions affect the store over time makes debugging much less stressful. It’s easier to reason about complex flows because you can literally watch them happen.
When Harlem Is a Good Fit
Based on this experience, Harlem shines in a few specific scenarios:
-
You prefer a plugin-centric mindset, where advanced behavior is clearly separated from core state and can be mixed in only where necessary.
-
Your app is firmly rooted in Vue 3, and you don’t need backward compatibility with older versions of Vue.
-
You like libraries that are light on opinions, giving you a simple core plus hooks where you can attach exactly the behavior you want.
-
You want features like transactions, snapshots, undo/redo, and storage to feel native to your state layer instead of bolted on with unrelated utilities.
In other words, Harlem feels at home in projects where custom architecture, clear separation of concerns, and flexible behavior are more important than following the most popular or official path.
When Pinia Still Wins
It’s important to be honest: there are plenty of cases where sticking with Pinia makes more sense.
Pinia is deeply embedded in the Vue ecosystem. Many tutorials, starter templates, and learning resources assume you are using it. If you care about matching the wider community, or you’re onboarding a lot of developers who already know Pinia, that’s a big advantage.
Pinia also shines when you have a mixed Vue 2 and Vue 3 landscape or when you want to follow the most officially recognized path without introducing additional libraries. Its API is straightforward, and it fits naturally into many existing patterns.
If your project is already heavily invested in Pinia stores, plugins, and patterns—and everything is working well—then introducing Harlem purely out of curiosity is probably not worth the churn. In that context, Pinia remains a reliable and pragmatic choice.
Was the Migration Worth It?
For the project I migrated, the answer is yes. The move from Pinia to Harlem gave the state layer a feeling of clarity and intentional design that I had been missing. Stores became easier to reason about, advanced behaviors felt better organized, and the line between “core state” and “extras” was sharper.
The migration wasn’t free, of course. It required careful planning, store-by-store refactoring, and thorough testing to ensure behavior stayed consistent. It also meant relying on a smaller ecosystem and spending more time reading documentation instead of just copying existing snippets.
But the result was a state management setup that fits how I think about the app: a lean core extended by carefully chosen plugins and extensions, each doing one clear job.
Final Thoughts
Switching from Pinia to Harlem is not about declaring a winner. It’s about matching the library to the way you and your team like to build applications.
If you value official backing, a huge community, and the comfort of using what almost everyone else is using, Pinia remains a fantastic tool. It is stable, well-understood, and more than capable of handling complex state in modern Vue projects.
If, on the other hand, you are drawn to a lighter, more extensible, plugin-driven approach, Harlem is worth a serious look. Start small. Pick one store, migrate it, wire up a couple of plugins, and live with it for a while. That small experiment will tell you more than any benchmark or comparison chart ever could.
