Read the docs. Every last word.

What I learned from reading the documentation for styled-components

🕯 Flame|First lit on March 28, 2022

8 min read

Table of contents

Why did I decide to read all the docs?Developing a docs-reading habit What I learned Things I didn't know about SC attrs Transient Props Test utilities SSG @import in `createGlobalStyle`Other things I learned by reading the docs Information Architecture Idiomatic usage Extra reading Confidence

Before last week, I had never read all of the documentation for a technology from start to finish. I'm currently working through Josh Comeau's excellent CSS for JS devs course in which he chooses to use styled-components.And gives an excellent breakdown of the pros and cons of various styling choices which I won't reproduce here. I chose to use SC (styled-components) for this blog because I wanted to learn it—it's popular and I was seeking to understand the debates around CSS-in-JS by trying it out myself. But after installing it and learning how to add styling, I didn't dig much deeper. It turns out, I was missing out on a whole mental model.

Why did I decide to read all the docs?

I already knew everything I needed to about SC to use it. I knew how to style components dynamically based on their props. I knew about the createGlobalStyle function for, yep you guessed it, creating global stylesThat temptation to roll your eyes is how you know it was well named.. But occasionally I found myself doing things I didn't like. I would create extra wrappers - unnecessarily polluting the DOM with more divs - or sometimes style nested elements from a parent component. And although I couldn't identify why I disliked it, I trusted my instincts and decided to find out what I was doing wrong.

Also, in one of my interviews for a company I'll be joining soon, it sounded like they were considering adopting SC, making this the opportune moment to become an expert on it. And if you want to know everything about a technology, then you better have read the documentation, right?This isn't actually rhetorical. Mastering a technology takes more than just reading the docs. And reading all of the documentation is only as useful as the documentation is good.

Developing a docs-reading habit

I wanted to practice reading documentation. And the SC docs are relatively short, so this was a good place to start. They took me a little over an hour to read at a careful pace, so much less than an hour if you want to skim them. They are also organised. I didn't suffer from sidebar overwhelm.

Why get good at reading docs? Sometimes, reading the docs is your best, or only, option. In closed-source tech, you have to rely on documentation. And for OSS, reading the source may take a lot of time. That might be worthwhile if you're looking to contribute, but not if you just want to assess the api.

Also, I've never done it before. I've definitely claimed that I learn new tech by reading documentation, but realised when I heard Wes Bos say that he skims all the docs to get an idea of a technology's surface area, that I had never done that. So, instead of changing my narrative, I did the work to make it come true.

What I learned

I learned things about SC. I have a better mental model for how it works. I have a better feel for idiomatic usage—how to use the library as it was designed to be used. I know the surface area of the api, so if I come up against an issue, my memory will likely remind me that there's a method for solving it. And I now know about some gotchas with SSR, which I use on this blog, so I could apply that benefit immediately.

But I learned about other things by doing this too. Primarily, I developed my ideas about good documentation and information architecture; this is important if you're a dev and you need to write docs yourself.

Things I didn't know about SC

This is more for my reference, or for those who know SC and are curious.

attrs

.attrs() is a useful method I didn't know about. It provides a way for adding props to a styled component. Use it when you want every instant of that styled component to have the same prop(s).

How to use it is well documented in the basics section of the documentation. The api is clarified in the API reference. What wasn't clear to me was when to use it—and when not to. I had to find that out in the FAQs section. So that's another win for reading all the documentation, but it also shows that I wasn't the only one unsure of the use case for .attrs(). It is better to include these things in the main docs. Sections like Tooling and FAQs are extras that most people won't be reaching.

Transient Props

Forwarding props is a useful pattern in React. In using it, however, we risk passing non-standard attributes to HTML elements. This will probably show an annoying warning in the console and nothing more. But accidentally forwarding the wrong prop to another React component could change its expected behaviour.

As of v5.1, SC allows you to prefix a prop with a dollar sign, marking it as for SC's use only.

Incidentally, look at how they highlighted which version this is available from. Definitely something to emulate.

A screenshot from the docs showing how version numbers are included in the API reference's headings — Taken from the docs

Test utilities

It had never occurred to me that using SC could affect your tests. It's useful to know before using it in a serious application that the library itself provides some methods.

So reading the docs is clearly a good way to assess whether you want to adopt a technology at work because this prompts further research. Does it play nicely with our test suite? Is it easier to use with Jest than with Mocha?

SSG @import in `createGlobalStyle`

The docs recommend - again in the FAQs instead of somewhere more prominent - that we don't use @import in the createGlobalStyle function "due to some issues with how browsers process @import via the CSSOM APIs."

I can easily imagine doing exactly that - why would I not? - and spending hours, if not days, trying to work out what had gone wrong. Now, I am forewarned.