August 14th, 2020
I was browsing the Svelte docs on my iPhone and came across a blaring UI bug. The notch in the REPL knob was totally out of whack. I’m always looking to contribute to open source, and I thought this would be a quick and easy fix. Turns out, there was a lot more to it than just changing one line of CSS.
Replicating, debugging, setting up the local environment was interesting, difficult, and meaningful.
I opened my browser DevTools, thinking I’d see the same issue in the phone view. But, the bug wasn’t there. Now this is a seriously tricky CSS problem.
💡 What I learned
If you’re using Chrome on iOS as your browser, you’re still using Safari’s renderer. From Wikipedia:
This is backed up by caniuse, which provides this note on iPS Safari:
Now it’s clear why the issue wasn’t showing up on my machine but it was showing up on my phone. Different rendering engines!
Reproduce the issue locally
I pulled down the project and ran it locally. I confirmed it was still an issue by running the local code in a simulator as well as on my actual iPhone. Safari on macOS has an easy way to open up DevTools instances of each one.
This provides access to a console just like you would in the browser but for iOS Safari. I’m not going to lie, Apple’s developer experience is top notch (see what I did there? 😬).
I’m able to reproduce the issue locally now.
💡 What I learned
After pulling down the Svelte repo and looking around the code a bit, I noticed the UI and SVGs were being pulled in via a package called @sveltejs/site-kit. Great, now I need my local version of site kit to get pulled into
svelte/site so I can see changes and debug the issue.
I needed to point the
node_modules in Svelte’s
package.json to my local copy of
site-kit. This sounded like a Symlink. After looking through the docs without much luck I Googled around and stumbled upon npm-link. That let me see what I was doing!
I can now make local changes to
site-kit and see them reflected in the Svelte project.
Solving the issue
Seriously, all this needed was a one-line change:
But locating where that one line should go was not as straightforward as you’d think. Source maps on the project are still a little rough around the edges and are showing this CSS coming from the
Nav.svelte component when it was really coming from another file. That would be another great way to contribute to the project!
Then you search around and learn that this is being handled and you learn a little more about how it’s done. Everything now looks great on mobile and desktop.
What started as a quick, one-line change became a bit of a journey. I had to:
- Run the project and component repositories
- Learn about system linking
- Contribute documentation about lining to site-kit
- Learn about different browser renderers
- Learn how to emulate an iOS Safari browser
- Learn how to get access to its debugger
- Find the issue when source maps weren’t working correctly
- Fix the issue (finally!)
Working on your own, you normally don’t get to deal with issues like this, or have a large complex system you need to build a mental model of and learn. You don’t get to learn from maintainers. Most importantly, you don’t see all of the hard work that goes into building a popular technical product.
Never stop learning
I grabbed another issue from the Svelte project and now I’m learning about CSSStyleSheet because there’s another issue (I think), with how Safari handles keyframe animations within stylemanager.ts. And so the learning continues down paths I never would have treaded in my day-to-day work.
When something breaks, enjoy the journey of learning the system. You’ll gain valuable insights into why that thing broke and what can be done to fix it. That’s one of the awesome benefits of contributing to open source projects and why I’d encourage you to do the same.
The orogonal post What I Learned by Fixing One Line of CSS in an Open Source Project.