In this article we explain how creating an open-source project helped us make sure that an internal library we developed at Wix and published to a public repository stays simple and safe to consume by third-party developers outside of the organization.
Happy Library Publishing Day
Congrats! You’ve just finished writing your first library in your favorite programming language and you are about to publish it to a public repository.
It wasn’t easy, you have invested many hours into coding and testing, integrated with some great third-party libraries, found the most suitable build tool, and now you can finally take a deep breath and let your library be free in the outside world.
But... wait a second. Are you truly done at this point?
As the creator of a library, you have to make sure that your users know how to use it. You need to make sure that future versions of your library will not break the things your consumers rely upon.
Well, as long as the library is well documented and follows the language conventions and best practices there is no reason why your users would get in trouble, right? As long as you have an organized CI/CD process there is no reason why you would break your users’ installation process in the future… After all, if the build is running on your machine why wouldn’t it run on theirs?
Cool.
The Enterprise Pain
Now let me add another variable to the equation. Let’s say you are one of those lucky people who work at a company that publishes some of its libraries to public repositories. The pros are obvious — you can use your company infrastructure and CI/CD tools, and you are even being paid for it!
The cons, however, are somewhat trickier.
How do we make sure that our users know how to consume the library? The users are not part of the company and their project setup and build methods might be completely different!
If your library build is green in your internal CI/CD servers, what guarantees do you have that external users outside of your inner company network, who don’t have access to private packages that you may have added as dependencies to your library, will also be able to consume your library without getting things broken?
The components group at Wix asked themselves that exact question.
wix-style-react, for example, is a widely used React library within Wix. For us Wixers, consuming the library is easy-peasy. Integrating with it comes with zero effort as our infra automatically supports it and our builds are protected by the internal CI/CD mechanism. Nothing gets broken.
However, as explained above, external users are a completely different story.
Photo by ThisisEngineering RAEng on Unsplash
Open Source FTW
One way to make sure that our users are safe is to get out of the organization and be our users.
By creating an external project that consumes the library and does not rely on any part of the company’s infrastructures, whose CI/CD mechanism is also external and independent, we can make sure that the library stays friendly for external users and is not coupled or dependent on any Wix private code.
In addition, if the CI/CD process of the project fails for some reason, the maintainer of the library we integrated into the project will be glad to be notified about the failure.
‘Design Systems Examples’ is a completely open source project that was created exactly for this purpose. It demonstrates how some Wix libraries can be used and allows developers to understand how to adjust their build flows to work with those libraries’ dependencies.
The project README file contains a description of the commands and steps that were taken in order to create the apps within this project from scratch and then to integrate them with our libraries. By creating such apps, we are able to make sure that the libraries are completely decoupled from Wix private code and can be integrated easily in new external projects.
In addition, the project uses Github Actions for CI/CD. It is being built and published upon any code change, and also periodically. In case a build breaks, the CI process notifies the inner Slack CI channel, so that the library maintainers know ASAP about that. Even though inside Wix the library build might be all good, when non-Wixers are getting breaks, we need to check why.
Creating this whole project from scratch took less than 4 days and since its creation it has notified us several times about potential issues.
For example, recently we have received a Slack message about a broken build. After checking the root cause of the failure we discovered that a new dependency of the library was a Wix private package that has not been published to a public repository yet. So even though within Wix the package installation works just fine, outside users were not able to install the library (and their builds were broken!).
GitHub Actions — is it that simple?
Yes. Super simple. As explained in their docs, all you need to do is create a .yml file that needs to contain the build configurations, and place it under .github/workflows.
Lets take a quick look at our publish.yml file:
First, we define what will trigger our job. This job is triggered by on.push.branches: main, meaning it is triggered each time someone pushes code to the main branch.
In addition, we have one more trigger — on.push.schedule: cron, meaning every day at 8:00 PM.
The rest of publish.yml contains the steps for the job.
There are currently 5 steps in our publish job:
Step 1 — configurations — use the right node version for the build.
Step 2 — build — try to build the application using bash commands.
Step 3 — publish — in case the build succeeded, publish the application to Vercel.
Step 4 — report to Slack — a conditional step that runs in case the build fails. This step sends a Slack message to a predefined Slack channel letting us know that something went wrong with the build.
Step 5 — return error code — in case the build failed.
As you can see the configuration of the build in our case is relatively simple and short. In case you need to create a more sophisticated flow, I recommend taking a look at the great GitHub Actions docs.
I was lucky to take part in creating this OS project together with the amazing Tal Zaidman and Shlomi Tussia Cohen.
This post was written by Uri Michael Goldberg
For more engineering updates and insights:
Join our Telegram channel
Visit us on GitHub
Subscribe to our YouTube channel