Apollo Elements 4 updates to Apollo Client 4 and includes one breaking change to subscriptions. This guide will help you migrate your app from Apollo Elements 3 to 4.
Apollo Elements Breaking Changes
Subscription Error Handling
This is the main breaking change in Apollo Elements 4. Subscription controllers no longer maintain an errors (plural) array. Subscriptions now only use the error (singular) field, matching Apollo Client’s useSubscription behavior.
Before (Apollo Elements 3):
class MyElement extends LitElement {
subscription = new ApolloSubscriptionController(this, MessageSubscription);
render() {
// ❌ No longer available
if (this.subscription.errors?.length) {
return html`<p>Errors: ${this.subscription.errors.map(e => e.message).join(', ')}</p>`;
}
return html`<p>${this.subscription.data?.message}</p>`;
}
}
After (Apollo Elements 4):
class MyElement extends LitElement {
subscription = new ApolloSubscriptionController(this, MessageSubscription);
render() {
// ✅ Use singular error instead
if (this.subscription.error) {
return html`<p>Error: ${this.subscription.error.message}</p>`;
}
return html`<p>${this.subscription.data?.message}</p>`;
}
}
Migration: If you’re reading subscription.errors, replace it with subscription.error.
Environment Requirements
Node.js 24
Apollo Elements 4 requires Node.js 24 or higher (previously 18.x):
node --version # Should be 24.x or higher
TypeScript 4.7
If you use TypeScript, you’ll need version 4.7 or higher:
npm install --save-dev typescript@^4.7.0
Apollo Client 4 Dependency
Apollo Elements 4 depends on Apollo Client 4. Update your dependency:
npm install @apollo/client@^4.0.6
Most Apollo Client 4 changes are internal and won’t affect Apollo Elements users. However, if you use the cache API directly, note these changes:
Removed InMemoryCache.writeData
The deprecated writeData method has been removed. Use writeQuery, writeFragment, or cache.modify instead:
Before:
cache.writeData({
data: { user: { id: "1", name: "Alice" } },
});
After:
cache.writeQuery({
query: gql`
query GetUser {
user {
id
name
}
}
`,
data: { user: { id: "1", name: "Alice" } },
});
Migration Checklist
- ✅ Update Node.js to version 24.x or higher
- ✅ Update TypeScript (if used) to version 4.7 or higher
- ✅ Install Apollo Client 4:
npm install @apollo/client@^4.0.6 - ✅ Update Apollo Elements packages to version 4.x
- ✅ Search for
subscription.errorsin your codebase and replace withsubscription.error - ✅ If using
cache.writeData, replace withwriteQuery,writeFragment, orcache.modify - ✅ Run your tests to verify everything works
Need Help?
If you encounter issues migrating:
- Check the Apollo Client 4 migration guide
- Open an issue on GitHub