Combine react components with Vanilla framework

[anthonydillon]

For ease of usage and integration with Vanilla versions, it would be better to integrate the React components library code base into Vanilla framework.

Pros:

• Would give us a centralised place to develop all things Vanilla.
• Would speed up development as the styling would be already be in Vanilla instead of porting styling around when components land.
• Would give us much more public documentation for the React components by rendering them on vanillaframework.Io/docs.
• Help the cognitive load when working between the projects.

Cons:

• React components releases would be tied to the releases on Vanilla framework (targeted each 2 weeks).
• Would increase the size on disk for developers using Vanilla framework in there projects. If only using the styling aspect.

Proposed requirements:

• Would need to provide a way to import styling via SCSS and the import the React components so usage is similar to the current system for both systems.
• Would need to provide documentation for the React components. Maybe simply add a section to the usage documentation and links from each component docs to the story book for the components.

[lyubomir-popov]

• Possilbe roadmap item? We'll discuss tomorrow in the planning brainstorming session
• Discuss with @squidsoup, @hatched, @huwshimi, others involved in the react components library

[squidsoup]

Would give us much more public documentation for the React components by rendering them on vanillaframework.Io/docs.

Including react-components in vanilla documentation is a great idea, but we don't need to combine the repos for this to happen - storybook provides iframeable content which we could render in the vanilla docs now.

[squidsoup]

Another Con, react-components is a level of abstraction above vanilla. Using react-components should not require any knowledge of vanilla.

[anthonydillon]

Having the react component documented on vf.io is not the main point here.

The main benefit of combining the codebases is to reduce the complexity of having separate dependencies. Each release will need to be tested with eachother.

By bundling the CSS and React components in a single repo we ensure they are tested together and can be confident they are fully compatible.

It's a better user experience in my opinion is to install Vanilla framework and import the React components and you are away. There is no need for you to know anymore about Vanilla then you do now. It also makes it easier to move from CSS only to using the react components as they are available already.

As there is a single team maintaining Vanilla it benefits them to have a single repo to focus there energy on.

[squidsoup]

Is it a problem for the websites that the bundle size would be increased quite a bit?

Bundling react-components with vanilla will add an additional ~40k minified/8k gzipped.

[anthonydillon]

The only increase would be for the developers working on the site lovely. This should not add to the download size of a site if it is not importing the React components.

[bartaz]

We talk here about pros and cons, technical consequences, etc, but what is the problem we are trying to solve with this merge?

Is it the problem of app developers who need to maintain 2 separate dependencies (vanilla and react components) in their project and keep them separately up to date? Is it a problem of react-components developers that they need to follow updates to Vanilla?

I see couple of aspects of this.

Maintaining compatible versions of Vanilla and react-components

Currently app developers (MAAS, JAAS, snapcraft) that use react-components need to have both Vanilla and react-components dependencies that are versioned separately and possibly may get out of sync and become incompatible. Of course one quite heavy solution is to merge Vanilla and react components into one repo and npm package and release them as one. But it's not necessarily the only solution.

Because react-components are built on top of Vanilla (in the same way they are built on top of React) they could list Vanilla (in a compatible version) as a peer dependency, so npm/yarn will warn developers to install correct version. These would still be separate dependencies, but at least dependencies system will help in making sure they are in compatible versions.

One step further would be to include Vanilla SCSS in react components package. So react-components (that has Vanilla as dependency anyway) would include (either in source SCSS form, or built as CSS) in their npm package, so any project using react-components wouldn't need to install Vanilla. They would be able to import Vanilla from react-components (instead of vanilla-framework). This way the Vanilla CSS version they include would always be compatible with react-components. Another benefit could be that this version of Vanilla can include the custom react-components SCSS out of the box, so by importing styles from react-components you would get whole Vanilla + react custom styles.

Keeping react-components up to date with Vanilla

Another aspect that could be improved is making sure updates to Vanilla get into react-components. While we are keeping react-components version of Vanilla up to date (thanks to renovate) we don't really do anything except version bumps. In patch releases it's probably fine (as they don't introduce any changes), but we do often release new features (additional class names, variants, etc), we do update markup and deprecate things. Because we keep (as much as possible) backwards compatibility in Vanilla we don't break things (which is good obviously), but this also means we don't feel the need to update the React components (that are working). But with every Vanilla release this means React components are more and more outdated in terms of Vanilla changes. And we should change that.

But we don't necessarily need to merge the projects to achieve this. What we should start doing is, instead of just bumping version of Vanilla whenever release happens and renovate creates the PR, we should make it part of Vanilla release process to update react-components. Not just by bumping the version, but by actually applying any changes in that version to components affected.

Now that I've written this I feel like we kind of already discusses something like this before, but that never happened.

[anthonydillon]

It's important that everyone is onboard with a fundamental change like this and it would seem there is some push back. In that case, let's spend the time to feel the pain of managing separate tightly couple projects. Which is a process the team have been through a few times with Vanilla themes.

My main concern is that the Vanilla team is small and it takes a lot of time and precision to line up, test and manage coupled releases.

As you asked:

what is the problem we are trying to solve with this merge?

There is no problem but optimisation in structure. The aim is to make the project easier to work on. Make both aspects (styling and functionally) first class citizens. Improve the experience of using Vanilla. (Import one project and use consolidated docs).

I will leave the decision here to the Vanilla team but I ask that we aim for the following:

• React components project should contain no specific styling. All styling should come from Vanilla for maintainability.
• Docs are clear and easy for users to use React components along side Vanilla components
• Updates continue to be well managed and clear when users can and should action an upgrade of either React components or Vanilla components
• Keep the barrier of releases as low as possible
• Optimise the creation and modification of React components and porting of styles to the correct place.

Feel free to close this issue as long as we agree to strive for the statements above.

On Wed, 7 Oct 2020, 07:58 Bartek Szopka, notifications@github.com wrote:

We talk here about pros and cons, technical consequences, etc, but what is the problem we are trying to solve with this merge?

Is it the problem of app developers who need to maintain 2 separate dependencies (vanilla and react components) in their project and keep them separately up to date? Is it a problem of react-components developers that they need to follow updates to Vanilla?

I see couple of aspects of this. Maintaining compatible versions of Vanilla and react-components

Currently app developers (MAAS, JAAS, snapcraft) that use react-components need to have both Vanilla and react-components dependencies that are versioned separately and possibly may get out of sync and become incompatible. Of course one quite heavy solution is to merge Vanilla and react components into one repo and npm package and release them as one. But it's not necessarily the only solution.

Because react-components are built on top of Vanilla (in the same way they are built on top of React) they could list Vanilla (in a compatible version) as a peer dependency, so npm/yarn will warn developers to install correct version. These would still be separate dependencies, but at least dependencies system will help in making sure they are in compatible versions.

One step further would be to include Vanilla SCSS in react components package. So react-components (that has Vanilla as dependency anyway) would include (either in source SCSS form, or built as CSS) in their npm package, so any project using react-components wouldn't need to install Vanilla. They would be able to import Vanilla from react-components (instead of vanilla-framework). This way the Vanilla CSS version they include would always be compatible with react-components. Another benefit could be that this version of Vanilla can include the custom react-components SCSS out of the box, so by importing styles from react-components you would get whole Vanilla + react custom styles. Keeping react-components up to date with Vanilla

Another aspect that could be improved is making sure updates to Vanilla get into react-components. While we are keeping react-components version of Vanilla up to date (thanks to renovate) we don't really do anything except version bumps. In patch releases it's probably fine (as they don't introduce any changes), but we do often release new features (additional class names, variants, etc), we do update markup and deprecate things. Because we keep (as much as possible) backwards compatibility in Vanilla we don't break things (which is good obviously), but this also means we don't feel the need to update the React components (that are working). But with every Vanilla release this means React components are more and more outdated in terms of Vanilla changes. And we should change that.

But we don't necessarily need to merge the projects to achieve this. What we should start doing is, instead of just bumping version of Vanilla whenever release happens and renovate creates the PR, we should make it part of Vanilla release process to update react-components. Not just by bumping the version, but by actually applying any changes in that version to components affected.

Now that I've written this I feel like we kind of already discusses something like this before, but that never happened.

— You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub https://github.com/canonical-web-and-design/vanilla-framework/issues/3312#issuecomment-704737006, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAKZDHTLFYTXGJZUJMV57NTSJQGSHANCNFSM4R3MBR7Q .

[squidsoup]

Because react-components are built on top of Vanilla (in the same way they are built on top of React) they could list Vanilla (in a compatible version) as a peer dependency, so npm/yarn will warn developers to install correct version. These would still be separate dependencies, but at least dependencies system will help in making sure they are in compatible versions.

+1 for vanilla as a peer dep, that's a great idea.

[bartaz]

Feel free to close this issue as long as we agree to strive for the statements above.

Sure, thanks.

I think it's a roadmap item we should take into next cycle. Even if our current goal won't me merging the two project, we should aim to improve how they coexist together in the areas pointed by Ant.

I'll think about specific tasks and write a brief for planning week, but some areas to improve would involve:

• making vanilla peerdependency of react-components
• upstreaming all local styling from react-components to Vanilla
• updating react-components to changes introduced in Vanilla recently
• make updating react-components integral part of Vanilla release process
• improve/automate react-component release process (GitHub action similar to Vanilla)
• improve process of upstreaming styles from react-components to Vanilla

Some of these are more actionable than the others, but that gives us quite defined list of work for next cycle. And I think this may also give us a good ground for talking the ownership of the react-components repo from MAAS team to Vanilla squad by the end of the upcoming cycle.

[bartaz]

I created a draft of a brief that lists the tasks we discussed before: https://docs.google.com/document/d/1LVPDGVtp_iNRIziubunVSyMHJeh7HELP7EUbvioeCak/edit#

[anthonydillon]

Thanks @bartaz

[lyubomir-popov]

We now have a master epic for this, and it includes a link to this issue for context.