# Vue Apollo v5: the Composition API layer for GraphQL in Vue 3

> Vue Apollo is the official Apollo Client integration for Vue, split into a composables package and a components package. The v5 branch is alpha-only, so production users should stay on v4 until the API settles.

**vuejs/apollo** — 🚀 Apollo/GraphQL integration for VueJS

- Repository: https://github.com/vuejs/apollo
- Website: http://apollo.vuejs.org
- Stars: 6,029 · Forks: 516
- Language: TypeScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/vuejs-apollo

## What Vue Apollo actually removes from a Vue 3 codebase

Apollo Client handles GraphQL transport, caching and cache normalization. It does not know anything about Vue reactivity. Without an integration layer, every component that reads a query result has to subscribe to the client's observable, copy the value into a ref, and unsubscribe on unmount. Vue Apollo exists to make that plumbing disappear.

The audience is Vue 3 developers, and the repository's topics still list vue2 and vuejs2, which reflects how long the project has spanned both major Vue versions. In the v5 monorepo the split is explicit: @vue/apollo-composable provides the Composition API surface, and @vue/apollo-components provides a components API that is built on the composables. If you write setup() functions, you only need the first package.

## How the composables and components packages divide the work

The repository is a pnpm monorepo. The root package.json is named vue-apollo-monorepo, is marked private, and pins the package manager to pnpm@10.6.2. The build script filters on the vue-apollo* and @vue/apollo* package names, so the two published packages are built together, and the typecheck script uses the same filter. A separate private-vue-apollo-docs package holds the documentation site.

That layout tells you where to file a bug. A problem with useQuery belongs in the composable package. A problem with a rendered component wrapper belongs in the components package, and the README states plainly that the components package is built on the composables, so the underlying query logic lives in one place. There is also an api-extractor.json at the root, and an api:extract script that runs the build first and then api-extractor. That is a signal the public TypeScript surface is treated as something to track, not something that drifts release to release.

## Installing @vue/apollo-composable and running a first query

The README does not contain a step-by-step install walkthrough. It points to the v5 documentation site at v5.apollo.vuejs.org, and the package name published on npm is @vue/apollo-composable, as shown by the npm badge at the top of the README. The badges also mark the package as apollo3 and vue3, so the v5 line targets Apollo Client 3.x and Vue 3 rather than Vue 2.

The repository does not show an install command for the package, so the only command that can be quoted from the repository files is the one the root package.json defines for installing dependencies across the workspace. It uses pnpm, which the root package.json pins as the package manager:

```bash
pnpm install
```

What you should see is the workspace's dependencies resolved from pnpm-lock.yaml, with the two published packages under packages/ linked together. Adding @vue/apollo-composable to your own project follows your package manager's normal add flow, using the exact package name from the README badge.

The README does not print a usage example for the composables. What it does give is the package name, which is also the import path, and the documentation link. The composable pattern is the point of the package: call a composable inside setup, and let it return reactive state you can bind in the template. The exact field names on the returned object, and the shape of the GraphQL document you pass it, are documented on the v5 docs site rather than in the README, so check there before wiring templates. If you prefer render-based components over composables, the README lists @vue/apollo-components as the components API, built on the composables.

## The v5 branch is not the stable line, and the README says so

The first thing the README tells you is that you are browsing the code for the next version, v5, and that the current stable version is v4, linked from the v4 branch. The badge for branch check runs also points at v4. The release list backs this up: the newest entries are v5.0.0-alpha.3 and v5.0.0-alpha.4, both published on 2026-08-06, while the most recent non-alpha release in that list is v4.2.3 from 2026-07-06. An alpha is an alpha. If you pin to v5 today you are accepting that composable signatures and returned fields can change between alpha releases, and the release script in the root package.json tags releases as next, which is the npm dist-tag convention for prereleases rather than latest.

There is a second, quieter constraint. The README advertises continuous releases: you can install builds from any commit on the main branch, or from any pull request, through nightly.akryum.dev. That is useful for testing a fix before it lands, and it is also a way to end up running unreviewed code in a lockfile. Teams that use it need a policy for when a nightly build is allowed to stay in a branch.

## Where Vue Apollo is the wrong layer to reach for

If your app talks to a REST API, or you use a GraphQL client other than Apollo Client, this project is not the integration you want: it is specifically Apollo Client for Vue, and the README badges name Apollo 3.x. Likewise, if you are on Vue 2 and cannot move, the v5 monorepo is not aimed at you even though the repository topics still mention vue2. The v4 line is where the stable code lives, and that is the branch the README links for current users.

A more common mismatch is scale of need. A single query in a single view does not justify pulling in Apollo Client's cache and the composable layer on top of it. A thin fetch wrapper plus a ref will be smaller and easier to reason about. The value of Vue Apollo appears when several components read overlapping data and you want the cache to deduplicate and normalize those reads, which is a behaviour of Apollo Client itself rather than of the Vue binding.

## Comparing against @vue/apollo-components and hand-rolled fetching

The honest alternative inside this same repository is @vue/apollo-components. It exposes a components API, and the README describes it as built on the composables. The difference is not capability but style: components suit templates that prefer declarative wrappers, while composables suit setup() code where you want to compose query state with other reactive logic. Choosing one over the other does not change the underlying Apollo Client behaviour.

The alternative outside the repository is writing your own client integration. Apollo Client is a standalone library, and you can subscribe to a query observable yourself, assign to a shallowRef, and clean up in onUnmounted. That keeps your dependency tree smaller and your types under your control. What you give up is the maintained mapping between Apollo's state and Vue's reactivity, including the edge cases around cache updates and refetching that the composable package has already worked through. For a one-off query, that trade is fine. For an application where query state is read in many places, the hand-rolled version tends to grow into a worse copy of this package.

## Maintenance, licensing and what an upgrade costs

Vue Apollo is MIT licensed, so you can use, modify and redistribute it, including in commercial and closed-source products, provided the licence and copyright notice are preserved. That is the extent of what the repository states; this is not legal advice, and if your organisation has specific obligations around attribution, read the LICENSE file in the repository rather than a summary.

The last push to the repository was on 2026-08-06, the same day as the v5.0.0-alpha.4 release. The v4.2.3 release landed on 2026-07-06. Neither the README nor the release list gives a date for a stable v5, and the README does not document a migration path from v4 to v5. That absence is the main upgrade cost to plan for: until the v5 docs cover the differences, moving from v4 means reading the changelog and the API extractor output rather than following a guide. The root CHANGELOG.md is the file to watch, and the api:extract script exists precisely to make the public type surface diffable between versions.

## Conclusion

Adopt Vue Apollo if you are building a Vue 3 app that already uses Apollo Client and you want useQuery and useMutation instead of hand-written fetch wrappers. Do not adopt the v5 branch for production: the README itself directs you to the v4 branch for the current stable version, and the only v5 releases so far are v5.0.0-alpha.3 and v5.0.0-alpha.4. Before committing, check the v5 documentation site, confirm which @vue/apollo-composable version your app resolves to, and decide whether you need the components package at all, since it is built on top of the composables.

## FAQ

### What is Vue Apollo used for?

It integrates Apollo Client with Vue, exposing GraphQL queries and mutations through the Composition API in @vue/apollo-composable and through a components API in @vue/apollo-components. The README describes the components package as built on the composables.

### How do I install Vue Apollo?

The README does not include install steps; it links to the v5 documentation site. The published package name shown in the README badge is @vue/apollo-composable, and the badges mark it for Apollo 3.x and Vue 3.

### Is Vue Apollo v5 stable?

No. The README states you are browsing the code for the next version, v5, and that the current stable version is v4 on the v4 branch. The v5 releases listed are v5.0.0-alpha.3 and v5.0.0-alpha.4.

### Can I install a build from a specific commit or pull request?

Yes. The README has a Continuous Releases section pointing to nightly.akryum.dev/vuejs/vue-apollo, where builds from any commit on the main branch or from any pull request are available.

### What licence does Vue Apollo use?

The repository is MIT licensed, according to the licence field and the LICENSE file in the repository root.

## Sources

- [License: MIT](https://github.com/vuejs/apollo/blob/v5/LICENSE)
- [Project website](http://apollo.vuejs.org)
- [README](https://github.com/vuejs/apollo/blob/v5/README.md)
- [Releases](https://github.com/vuejs/apollo/releases)
- [vuejs/apollo on GitHub](https://github.com/vuejs/apollo)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/vuejs-apollo