[miksuv]

I get this concern and I used to have a very similar feeling about it. Uber had an older React component library that was more locked down in a way you pretty much described. Number one complain was "not easy to customize" and that probably applies for every component library out there.

You describe render props as a "middle ground". For us, it is the last resort / nuclear option (as described here https://baseweb.design/theming/understanding-overrides/#over...). You give the consumer all the freedom to completely replace the guts of your component. Sure, nothing provides more flexibility but at the same time, consumer has to do a lot of heavy lifting - creating a whole new component.

However, developers usually want to tweak some small things. Maybe changing some color or padding. Forcing them to swap the whole subcomponent through render prop is an overkill and once they "opt-out" that way, they will never get any updates from us since that part of component is completely replaced.

Of course, ideally we want them to always use the defaults but that's not how real organizations with thousand of engineers and hundreds of apps work so we rather let them customize but on our terms. We don't want to see them hacking the styles through CSS selectors or "render prop" everything which equals not using our visual components at all. It's a compromise we had to make to make everyone reasonably happy.

Surprisingly, it's not a nightmare to maintain. We don't consider changed styles as a breaking change and in last 6 months I haven't seen complains about that. Although, it makes the Base Web codebase more complex and all changes need to be thoughtful. But that's a cost that Base Web pays so other teams don't have to.

[btown]

Do you use any sort of visual comparison tools or snapshotting in CI to catch regressions caused by changes to Base? Seems like this would remove any (technical) objections to having overrides.

[miksuv]

We currently use https://screener.io/ for Base Web itself and working on an app that should automatically crawl all our web apps, analyze them and provide insights into how exactly our components are being used. It should be open sourced eventually.

[ohadpr]

The folks behind Storybook created a product for that: https://hichroma.com/

[lewisl9029]

I can appreciate that you guys weighed the tradeoffs and decided that giving users freedom to override arbitrary styles is worth the cost of whatever breakage might result from that decision as you upgrade the library. We're all engineers who build things to solve real world problems at the end of the day, and I don't have any of the context that led up to your decision, so I can't say for certain that I'd have weighed those tradeoffs any differently if I were in your shoes and have to cater to the whims of thousands of engineers with differing opinions on how things should be done.

However, I have to disagree with your characterization of render props as "the freedom to completely replace the guts of your component". Offering a render prop API should be an explicit decision to fundamentally stop treating that branch of the render tree as part of the "guts of your component". It's a decision to delegate to users on how to best render that part of the component.

Of course, you're right that in a vacuum, that would equate to throwing up our arms and asking users to figure it all out on their own as to how to implement the styling and functionality of that part of the tree.

However, when we're the maintainer of a component _library_, we're in the unique position where we can provide additional, complementary components that provide styling and functionality for users to use to implement that part of the tree, composed with their own custom components when appropriate, without having to build everything from scratch.

These components usually start out as the same components that used to reside in that part of the tree in the original parent component. By decoupling them from the parent, they're then immediately able to start providing their own explicit interfaces that can be evolved independently from the parent without risk of breaking usages on implementation detail changes.

Of course, users are free to simply not use those components because they might not address whatever problem they need to solve. Rather than taking that as a failure of the approach, I'd take that as a triumph because it demonstrates that this approach gives users the flexibility to experiment with how best to solve their particular problems within the confines of the isolated subsection of the original component without affecting the maintainability of the component itself. And we as library maintainers are then able to examine the various custom components created for those use cases to see if any particular implementation is suitable for extracting directly into the library, or at least learn from them when building new reusable components to support those use cases officially (and users are free to choose to adopt those new components at their own pace, without any fear of things breaking under their feet).

This is why I point to this approach as the middle ground. Component composition is a much more sustainable mechanism to provide to users for customization, in my opinion, compared to arbitrary overrides. In fact, if anything, I'd consider arbitrary overrides to be the nuclear option here, because once we start offering that option, people are going to start using our components ways that we can't possibly ever fully anticipate, so we end up having to _really_ throw up our arms as maintainers and start saying things like "We don't consider changed styles as a breaking change".

[miksuv]

Right. We do exactly that as well. You can import all our styled subcomponents separately and then plug them back into render props. We just call it a bit differently - it's the "overrides" object prop and not a top level renderFoo prop. Example: https://baseweb.design/theming/understanding-overrides/#over...

The ability to extend the styles is just a shortcut. If I want to change a border for some specific subcomponent, I could import it, change the color (in our case through a css-in-js API) and plug it back through a overrides.FooComponent.component (which is nothing else then a render prop).

But that's a lot of steps to just tweak a border, isn't it? Why not to just have "overrides.FooComponent.style" and let the library do the rest. This doesn't open more surface, just a quality of life API. Arguably you can run into the same type of style breakages when devs are restyling our subcomponents. They will not look inside of them every single time we release a new version.

To be honest, the only really unique thing about Base Web is that you can replace every single subcomponent (1 subcomponent always renders 1 styled DOM Element) through render prop pattern and you can even do it in a layered fashion (passing children through). "overrides.Foo.props" and "overrides.Foo.style" are just shortcuts for render props. Other than that, it's just an another React component library.

"people are going to start using our components ways that we can't possibly ever fully anticipate" - That always happens no matter what you do! Unless you make your API super strict and then nobody will want to use your library. It's a delicate balance - keeping other teams moving fast and happy while not introducing breakages often.

[lewisl9029]

> But that's a lot of steps to just tweak a border, isn't it? Why not to just have "overrides.FooComponent.style" and let the library do the rest. This doesn't open more surface, just a quality of life API. Arguably you can run into the same type of style breakages when devs are restyling our subcomponents. They will not look inside of them every single time we release a new version.

The ability to arbitrarily override styles in every single component exposed through the library is exactly the crux of my concern outlined in my original post and later reply.

> "people are going to start using our components ways that we can't possibly ever fully anticipate" - That always happens no matter what you do! Unless you make your API super strict and then nobody will want to use your library. It's a delicate balance - keeping other teams moving fast and happy while not introducing breakages often.

Yes, there's definitely a balance to be struck here.

Opening up the API to arbitrary style overrides is sitting at one end of that spectrum, optimizing for short term user freedom/productivity and quick adoption of the component library over the long term maintainability of the library (every change becomes a potential breaking change), and with it, the ability of users to upgrade with confidence to take advantage of new changes and features.

However, the alternative to the wild west approach of arbitrary styling overrides isn't only to make an API so strict that it will never fit anybody's use cases outside of the ones it was originally designed for.

There exists a middle ground of providing an explicit API designed for specific use cases and then deliberately growing that explicit API to cover more use cases, informed by real world usage patterns, while taking care to make sure that those use cases are actually ones that make sense for the library to support long term (rather than built as one-off usage specific components), and that the resulting changes aligns with whatever styling consistency standards the library wants to enforce.

This approach affords maintainers an API surface to reason about and communicate breaking vs non-breaking styling changes to users, in exchange for short term speed of adoption because we're deliberately limiting the initial breadth of use cases the library can cover.

The former approach could definitely be the right tradeoff to make at this time given Uber's current circumstances.

Personally, I still have my doubts, after seeing how quickly this kind of API can break down even at a much smaller scale, but ruling that out without any context would be pure hubris on my part.

However, one caveat I'd like to add is moving from an explicit API to one that allows arbitrary overrides is easy, because adding an arbitrary overrides system is a non-breaking change, but going the other way is another story, because doing so would break everybody that relied on the overrides system to cover whatever use case the base API ever bothered to grow to cover, so it's not a decision to be made lightly. This is definitely not meant to imply that the team at Uber made the decision lightly, as I can tell from your thoughtful responses that you certainly did not, but rather as a word of caution to anyone else who's thinking about going this route.