🚀 Revamping `graphql_flutter`: Roadmap, Community Involvement & Long-Term Maintenance

[Azzeccagarbugli]

Hi everyone 👋

Over the past weeks, we had a direct call with the current maintainer of graphql_flutter, and we want to openly share where we're heading and, most importantly, listen to the community before making decisions.

We (at Expatfile) rely heavily on graphql_flutter in production, and because of that we want to invest time, resources, and long-term commitment into keeping this project healthy, modern, and actively maintained.

Plus, did you know that we were actually the original creators of graphql_flutter, so this project is very close to our hearts. @HofmannZ back in the days made a stunning work!

This document is meant to be:

• a transparent starting point
• a place to collect feedback
• a shared discussion, not a unilateral roadmap

🎯 Our Intent

✅ Our goal is not to rewrite the library or break existing apps.

Our goal is to:

• Keep the package actively maintained
• Improve DX and reliability
• Modernize parts that are clearly showing age
• Do all of this with the community, not above it

⚠️ No major breaking changes are planned by default.

If breaking changes ever become unavoidable:

• They will be clearly announced
• Discussed beforehand
• Accompanied by migration tooling / codemods where possible

🔍 Focus Areas (Initial Proposal)

These are the areas we believe matter most today. Nothing here is final, feedback is explicitly requested.

1️⃣ BLoC Integration (First-class)

• Official patterns/examples for BLoC (Provider/Repositroy)
• Clear guidance for:
  • Query lifecycle
  • Mutations
  • Error handling
  • Cache updates
• No forced architecture, just solid primitives

Questions

• What state management approach do you use today with graphql_flutter?

2️⃣ Documentation Website

• Dedicated documentation site (not only README)
• Clear sections:
  • Getting started
  • Architecture overview
  • Cache & normalization
  • Error handling
  • Testing
  • Examples (real-world)
• Better onboarding for newcomers

Questions

• What documentation do you feel is missing or unclear today?

3️⃣ Performance Improvements

• Review of:
  • cache reads/writes
  • unnecessary rebuilds
  • stream / listener behavior
• Profiling real-world use cases
• Performance changes will be measured and documented

Questions

• Have you experienced performance issues? In which scenarios?

4️⃣ Code Generation Improvements

• Better alignment between:
  • schema
  • generated models
  • cache expectations
• Clearer customization points
• Improved DX around build_runner errors (lean_builder seems is another solution too)

Questions

• What frustrates you most about code generation today?

5️⃣ Increasing Test Coverage

• More unit tests
• More integration tests
• Regression tests for known issues
• Making it safer to contribute

Questions

• Are there areas you'd like to help test or validate?

6️⃣ Fixing Long-Standing Issues

• Triage of open issues
• Clear labeling:
  • bug
  • discussion
  • help wanted
  • good first issue
• Prioritization based on real usage

Questions

• Which open issues block you the most right now?

7️⃣ Developer Tooling

• Better logging
• Improved error messages
• Potential DevTools integration (exploratory)

Questions

• What tools would help you debug GraphQL issues faster?

🤝 How We Want to Work With the Community

• Open design discussions
• RFC-style issues for impactful changes
• Clear changelogs
• Explicit migration paths
• Welcoming contributors of all levels

If you:

• Use graphql_flutter in production
• Tried it and left
• Maintain a fork
• Or just have opinions

👉 Your input matters here.

🗣️ How You Can Participate

Please comment with:

• Pain points
• Missing features
• Architectural concerns
• Areas you've wanted to propose but never had space for

Even short comments help, even “this is fine, please don't change X” helps.

---

Let's make graphql_flutter something we're all confident building on for the next years.

And a special shoutout to @vincenzopalazzo that during those years kept the project active and running!

Expatfile Team🗽

[jorg1piano]

The biggest pain point is how slowly issues are addressed, labeled, or closed.

Other pain points:

• The package does not handle request cancellation.
• There is no ability to add a TTL to cached queries.
• The way observables interact with the cache and network is very slow.

[Azzeccagarbugli]

Hey @jorg1piano, thanks for sharing this, totally fair points.

The “issue velocity” concern is especially valid: slow labeling/triage creates uncertainty even when the project is actively maintained. That’s something we’re explicitly discussing, because clarity and responsiveness are a big part of DX, not just features.

On the technical side, you’re also pointing at real gaps. If you have concrete use cases, benchmarks, or ideas for how these could be addressed cleanly, they’d be super valuable to the conversation ✨

[jorg1piano]

It's been a month without any activity as far as I can tell. The same issues are still there and PRs like #1510 are not reviewed by any maintainers. It had obvious issues when it came in the door, still does, and rejecting it should not be that hard.

I appreciate all the work by everyone that has contributed to this repository, but at this point, the only way forward at least for usage in our company is to fork the repository, and fix the obvious issues ourselves. Waiting months for an initial review or feedback on issues does not inspire confidence and even if we were to contribute to the repository with PRs, the feedback cycle would simply be too slow.

[vincenzopalazzo]

It's been a month without any activity as far as I can tell. The same issues are still there and PRs like #1510 are not reviewed by any maintainers. It had obvious issues when it came in the door, still does, and rejecting it should not be that hard.

Hi, sorry to hear about your frustration here. The PR at #1510 doesn't quite follow our contribution guidelines (check out the commit styles in https://github.com/zino-hofmann/graphql-flutter/blob/main/CONTRIBUTING.md). Fixing that up is pretty straightforward these days with tools like Claude for code reviews. Unfortunately, that's one reason it's not getting attention right now. I get that I could just comment on it, but I'm squeezing in work on this package during my free time lately, so I have to be smart about where I spend it.

usage in our company is to fork the repository, and fix the obvious issues ourselves.

If you fork and open PRs for those obvious fixes, I'm confident I can get a release out quickly. The last release got delayed because of holidays (both personal and public ones), and I haven't had a chance to sort out the CI in #1511 yet. That CI automation is what keeps this package going strong with zero paid contributions, so I can't skip it. I plan to tackle it by the end of the month, so my suggestion is to polish up your PRs—they'll get merged and released on the same day.