Migration path and breaking changes in v4

[jeremenichelli]

This is not really an issue itself, but a statement that I want to pass to the kind authors and contributors to styled-components. First of all, I want to thank you for all your hard work and changing the way we style our web projects ❤️

I was really excited when v4 was announce, not only because of its improvement in performance, but also because of as attribute which will let as improve accessibility and a better global injection paradigm, at least in my opinion.

I was though surprised that there wasn't a graceful path of migration for the new global injection API in the package. As a library maintainer, this is a must when trying to drive adoption and allow people to move to a newer version of a project which I maintain and have put time on.

In my opinion, styled-components should have a release which warn about the deprecated use of injectGlobal in favor of v4 new form.

Right now in my company we have internal dependencies, as most big companies with cross functional teams. This means that we have a design system, an app header and various product screens that are using styled-components. The problem is that the migration is quite impossible for us, or involves eternal work hours and lots of produciton and cache checks since the release of one of them using v4 will break the others.

How could this be avoided?

Supporting both APIs at some point of the releases. Why? Because then we could safely bump the version of our vendor bundle and deppendencies in our services. Then progressively migrate each part of our product, and when all were migrated we can actually bump styled-components to v4 without any worries.

Right now, it's really hard to explain to business departments the benefit of moving to a new version given the value it really goes to the product, no matter how much we think about it it doesn't makes sense to us and we are thinking on staying on v3 or directly move away to another css-in-js solution.

React is a good example to look at regarding developer experience, and it's never stopped us form moving to newer versions.

I hope the team can take the feedback in a constructive way for future changes.

Cheers,
Jeremias.

I'm immediatelly closing the issue to avoid noise in the repository.

[quantizor]

I was though surprised that there wasn't a graceful path of migration for the new global injection API in the package. As a library maintainer, this is a must when trying to drive adoption and allow people to move to a newer version of a project which I maintain and have put time on.

Pardon? We posted a very easy to follow migration guide AND codemods for this.

[quantizor]

https://www.styled-components.com/docs/faqs#what-do-i-need-to-do-to-migrate-to-v4
https://github.com/styled-components/styled-components-codemods

[jeremenichelli]

Hi @probablyup, thanks for joining the conversation. I'm not saying that migrating is hard, not at all actually and the documentation is on point 👍

I'm saying that not having a version of the package where both the old and new API exist together doesn't allow us with interoperational dependencies to migrate since updating one will break the other.

[mxstbr]

I hear what you are saying @jeremenichelli, but also we did make it as easy as possible (a single command to run codemods) to migrate to v4. It should be a two minute process, and publishing a version with all APIs would have 1. massively increased your bundle size and 2. not made migration any easier, so we did not do it.

[jeremenichelli]

Hi @mxstbr, I want to clarify this again in case it wasn't clear before: the team did a great job by first, releasing a better version of the library, then by documenting it and later to provide straightforward mechanisms to migrate a single project to the new version. That's settled up 👍

I was talking about having at some point both global style APIs to allow cross functional teams to gradually migrate to v4. Right now, we have an app shell, multiple screens, and a design system consuming styled components from a vendor bundle (because you don't want to bundle the same dependency multiple times). That said, coordinating this migration across all projects and teams is really hard, without ignoring that a user can have one of these bundles cached but download the new version of the vendor for example (because cache is complicated 🤷‍♂️) and our product will crash.

So, to give the team an update, we will need to bundle styled components on each bundle, until they are all on v4, and then switch back to rely on our vendor version of the package.

So, we will make the user download styled components three times in some parts of the product, which is still affecting bundle size and probably with a bigger impact.

Sorry for the long message, but I wanted to explain better the reasoning around this, and again it's coming from a good place 🙏 I am an open source, library and internal tooling maintainer too and I work around migrations and DX a lot. I'm happy to jump in a call to explain this even deeper or more clear if the message and my English are confusing.

Let me know if I can help you folks with anything on this, whether is with my experience, or with coding or whatever, the communication channel is always open here. Thanks!