Three Months with Capa-BFF: Can This Zero-Cost BFF Really Fix Your Frontend Pain Points?

Honestly, I didn't have high expectations for another "zero-config" BFF framework before I tried Capa-BFF.

I've been through enough pain with frontend-backend integration on separated projects, and I know a lot of you have too. The story is always the same: frontend waits for backend to finish APIs, backend says they're busy changing database schemas, then you wait for documentation, then you wait for CORS configuration — by the end of the day, you've spent more time waiting than actually writing code.

I'd tried a bunch of popular BFF solutions before. Some were so complex it took half a day just to set up the environment. Some had so many bugs I had no clue where to start debugging when something broke. And some were closed-source commercial products that small teams just couldn't afford.

Honestly, before I found Capa-BFF, I was already planning to just hand-roll a simple version myself. We had deadlines to meet, who had time to mess around with heavy frameworks anyway?

What Even Is Capa-BFF, Anyway?

Capa-BFF is an open-source zero-cost BFF solution from the capa-cloud project. Let me put it plainly: it lets frontend teams directly compose backend data sources without backend developers writing custom APIs. You can find it on GitHub here: https://github.com/capa-cloud/capa-bff. It's completely free and open-source.

After using it for three months in production, what strikes me most is how lightweight it is. You don't need to deploy any extra services, you don't need to rewrite your existing architecture — just add the dependency, write a JSON configuration, and you're good to go.

I think the design philosophy here is actually pretty clever. It doesn't try to replace your existing backend architecture. It just adds a dynamic composition layer on top. Frontend can assemble exactly the data they need for a page, and the backend just needs to expose the data sources once. That's it.

Let me give you a concrete example so you see how it works. Say you're building a user profile page that needs four pieces of data: basic user info, recent orders, favorite products, and unread messages. In the traditional approach, the backend writes four separate endpoints, the frontend calls all four and aggregates the result on the client. If the product manager changes their mind and wants recent browsing history instead of recent orders, the backend has to change the API again.

With Capa-BFF? The backend just exposes each data source once. The frontend writes exactly what they need in a JSON config, and gets everything back in one request. Product changes their mind? The frontend just tweaks the config and deploys — no backend involvement required at all.

Let Me Show You Real Working Code

I'm going to drop an actual configuration we use in production right here. You'll see how simple it is:

{
  "namespace": "user-homepage",
  "description": "User homepage data aggregation",
  "calls": [
    {
      "id": "baseInfo",
      "type": "database",
      "source": "user-db",
      "query": "SELECT id, username, avatar, email FROM users WHERE id = ${userId}",
      "params": {
        "userId": "$context.userId"
      }
    },
    {
      "id": "recentOrders",
      "type": "database",
      "source": "order-db",
      "query": "SELECT id, orderNo, amount, status, createTime FROM orders WHERE userId = ${userId} ORDER BY createTime DESC LIMIT 5",
      "params": {
        "userId": "$baseInfo.id"
      },
      "depends": ["baseInfo"]
    },
    {
      "id": "unreadCount",
      "type": "rpc",
      "service": "message-service",
      "method": "getUnreadCount",
      "params": {
        "userId": "$baseInfo.id"
      },
      "depends": ["baseInfo"]
    }
  ],
  "result": {
    "user": "$baseInfo",
    "recentOrders": "$recentOrders",
    "unreadCount": "$unreadCount.count"
  }
}

That's literally all there is. Let's break down what's happening here:

1. First, we query the database for the user's basic information
2. Then we get the user's 5 most recent orders, which depends on the user ID from the first call
3. Then we call an RPC service to get the unread message count, also using the user ID
4. Finally, we aggregate everything into a clean response and send it back to the frontend

All the backend needs to do is pre-register the user-db data source and the message-service RPC service. After that, frontend can rearrange things however they want.

How do you register a data source on the Java side? It's just as simple:

import cloud.capa.bff.core.annotation.BffDataSource;
import cloud.capa.bff.core.datasource.JdbcDataSource;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class BffConfig {

    @Bean
    @BffDataSource("user-db")
    public JdbcDataSource userJdbcDataSource(JdbcTemplate jdbcTemplate) {
        return new JdbcDataSource(jdbcTemplate);
    }
}

That's it. Just those few lines, and the data source is registered and ready to go. The frontend can start using it immediately.

Calling it from the frontend is straightforward too:

async function getUserHomeData(userId) {
  const response = await fetch('/bff/call/user-homepage', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId })
  });
  return await response.json();
}

One request, all the data you need. Clean as a whistle.

Let's Talk About the Dark Side: Pitfalls I Ran Into

Okay, I've talked about the good stuff. Now let's be real — no open-source project is perfect. I've been using this for three months, I've stepped in a few piles of dog poop along the way. Let me save you some trouble.

First pitfall: You have to implement your own permission control. The framework handles data aggregation, but it doesn't do fine-grained permission checking out of the box. If you need row-level permissions — like a user should only be able to see their own orders — you have to handle that yourself in the SQL or at the data source level. The framework doesn't do it for you.

I learned this the hard way. When I first set it up, I just dropped the query in there and called it a day. It wasn't until later I realized users could tweak the parameters and see other people's data. Yeah, that scared the crap out of me too. Fixed it immediately with proper filtering. So heads up — with great power comes great responsibility.

Second pitfall: Complex queries might not perform as well as handwritten SQL. The framework does automatic dependency analysis, topological sorting, parallel calls, and cycle detection — all that stuff works great. But if you're doing a really complex multi-table join, the generated SQL probably won't be as optimized as something you'd write yourself. To be honest though, if you're doing that kind of complex query, you should probably be writing it by hand anyway. BFF isn't meant for that use case in my opinion.

Third pitfall: Documentation is incomplete. The README on GitHub covers the basics, but more advanced topics like custom data sources, caching strategies, and error handling aren't covered in much detail. When I was implementing my first custom data source, I ended up reading through the source code to figure out how everything hooked together. That said, if you're an experienced developer it's not that big of a deal — but it might be a bit confusing for beginners.

Fourth pitfall: It only works with Java/SpringBoot right now. If you're running a Go or Python stack, you can't use it today. I heard the team is planning multi-language support, but it's not here yet. So that's something to keep in mind if you're not in the Java ecosystem.

How Does It Stack Up Against Other BFF Options?

I've used a few different BFF approaches, so let me give you a quick comparison to help you decide if this is right for you:

vs. API Gateway Pattern

API Gateway is definitely mature, but it's heavy to deploy and maintain. It works great for big companies with dedicated teams to operate it, but small teams just don't have the bandwidth for that extra complexity. Capa-BFF embeds right into your existing application, no extra deployment needed, zero extra cost. That's a game-changer for small teams.

vs. GraphQL

GraphQL is technically great, but the problem is you have to change how both frontend and backend work, and there's a non-trivial learning curve. Our frontend team wasn't very familiar with GraphQL when we started looking at BFF options, so there was a lot of resistance to adopting it. With Capa-BFF, it's just JSON configuration. Anybody can read it, anybody can edit it, learning curve is basically zero. You can be up and running in minutes.

vs. Writing Your Own Custom BFF

Writing it yourself gives you full control, of course. But building something stable takes time. All the little details like dependency analysis, parallel execution, cycle detection — you have to implement all that yourself. Capa-BFF gives you all that out of the box. It saves you a ton of time, and you can always add custom stuff where you need it.

So Who Should Actually Use This?

After three months of production use, here's my honest take on who this fits and who it doesn't:

✅ Go for it if:

• You're doing frontend-backend separation and deal with frequent API changes
• You're a small team or startup with limited resources and don't want to mess with heavy architecture
• Your frontend team wants more autonomy to compose data themselves and cut down on waiting for backend
• You don't want to rewrite your existing system, you just want to add dynamic aggregation on top

❌ Skip it if:

• You're working on a huge complex project that already has a mature BFF setup
• You need extreme performance optimization and every millisecond counts
• Your whole stack isn't Java/SpringBoot (it doesn't support other languages yet)
• You need complex fine-grained permission control out of the box and don't want to write it yourself

Honestly, if you're a small-to-medium team and you're tired of the constant API negotiation ping-pong, you should just try it. It's zero cost, you can integrate it in minutes, and if it doesn't work for you, ripping it out isn't a big deal. No harm done.

What I Actually Learned After Three Months

The biggest takeaway for me wasn't even the framework itself — it changed how I think about frontend-backend division of labor.

Before, we did it the traditional way: frontend tells backend what APIs they need, backend writes them. Product changes requirements, APIs change. When backend is busy, frontend just waits. Development flow gets stuck all the time.

With Capa-BFF, the dynamic changes. Backend exposes the data sources, frontend composes what they need. Product changes their mind? Frontend tweaks the config and deploys. No waiting on backend. Our development speed actually picked up quite a bit.

I was worried at first that this would push too much backend logic to the frontend and make everything messy. But after using it for a while, it's actually fine. Capa-BFF only handles data aggregation. The real business logic still lives on the backend. The separation of concerns is still pretty clear.

This approach isn't a silver bullet, of course. It's just another option you can layer on top of your existing architecture. Some scenarios fit perfectly, some don't. There's no such thing as a one-size-fits-all architecture — just what fits your team and your project.

Let's Talk — What Do You Use for BFF?

I'm curious — have you ever dealt with that constant "change the API" pain in frontend-backend separation? Product changes their mind every day, backend is constantly rewriting endpoints, frontend is constantly waiting. What solution do you use these days? Do you write a custom BFF, use GraphQL, or just deal with it like we used to?

Drop a comment below and share your experience. I'd love to hear what's working for you.