Mark Jaquith: Making ScoutDocs: React
Continuing my series about ScoutDocs and the process of building it, this week I’m talking about React.
What is ScoutDocs? ScoutDocs is a WordPress plugin that adds simple file-sharing to your WordPress site.
After the first iteration of ScoutDocs was built and none of the partners on the project were happy with its experience, it became clear that in order to deliver a clean, simple interface for file uploading and sharing we needed to leave the bounds of the WordPress admin. It didn’t take me long to decide that React would be the tool I used to build the new interface.
There is an incredible momentum behind React, and a rich ecosystem of libraries, tools, and educational resources. But beyond all that, React is just plain fun to code. Once you accept the central premise that a view layer and the controller that handles that view are inextricably linked, and once you get over the weirdness of quasi-HTML-in-JS that is JSX, coding in React is a joy.
Make no mistake, learning React is not a weekend project. It will take a while before it feels like home. But once you get it, you feel very powerful.
The first lesson I learned was don’t learn React by rewriting your app in React. I tried this. I read some tutorials about React and it felt straightforward, and I was like “let’s do this.”
This was a bad idea. I was overwhelmed. I had no idea where to start. Next, I tried following some of the interactive tutorials that required me to build a simple React app and then slowly add functionality to it, refactoring it multiple times, until I understood not just the code that I ended up with, but the process of creating it. This went much better.
Start small, and build a bunch of “toy” apps before you use React for your own apps. Once you are able to “think in React”, you’ll be nearly physically itchy to go re-code your app in React, and that’s how you know you’re ready. If you jump the gun, you are going to get stuck a lot, and it will be frustrating.
As you learn React and explore the React ecosystem, you will likely hear about Redux, which is a system for storing application state, and is commonly used with React apps. It looked complicated, and even its creator wrote a post saying you might not need Redux. So I skipped it. This was probably the right call when I was starting out. But as I fleshed out the ScoutDocs app and its complexity increased, I ran into a problem.
See, React breaks your app up into these nested chunks of UI and functionality called components. Data flows down through your components. So if a user updates their name, that change will flow down from higher up components like a Page component down to a PageHeader, down to a NavBar, down to a UserStatus. Once this is all set up and you update data in a parent component, the changes automatically flow downstream, and the UserStatus component updates and re-renders. It’s great. Except that there are a bunch of intermediate components that accept and “forward” that user name data to their children, without actually caring about it themselves. When you inevitably refactor something and need to add new data that flows through these components, every single intermediate one needs to be updated to pass it on. It is tedious. You will hate it.
Worse, because events in React flow upwards, if a user updates their name in the UserName component, that change needs to flow up to ProfileForm, up to Profile, up to Page, and then up to your main App component. When you refactor, you need to make sure this event forwarding chain stays connected. Yet more tedium that you will hate.
Redux solves this by letting your React components, no matter how deeply they are nested, subscribe directly to the data they need.
I really wish Dave Ceddia had written this excellent post about Redux two months earlier.
If you have a component structure like the one above – where props are being forwarded down through many layers – consider using Redux.
This is what I needed to hear, and knowing this would have saved me a lot of frustration and time that I now have to spend converting ScoutDocs to use Redux.
Use Redux when your React data flow starts to get unwieldy.
Another mistake I made early on was making the data my React components accepted too restrictive. For example, I wanted the ability to prefix a Row component with a clickable icon. So I let the component accept an icon and onClickIcon property. I just passed a Font Awesome icon name in, and a function I wanted to run when clicked. It worked great.
Then I needed to add a second icon in front, in some circumstances. Ugh. I certainly didn’t want to do otherIcon and onClickOtherIcon. Instead, what I should have done was let the component accept beforeRow which could be anything… like an array of <Icon> components or a single one or even other components altogether.
This can be used for many more situations than the one (“put an icon before the row”) that I’d originally envisioned.
Your React components should be flexible, so they can be reusable.
Other posts in this series:
- Outsourcing
- React
- WordPress Rest API
- PHP 7
- Build tools
- Unit testing
Continuing my series about ScoutDocs and the process of building it, this week I’m talking about React. What is ScoutDocs? ScoutDocs is a WordPress plugin that adds simple file-sharing to your WordPress site. After the first iteration of ScoutDocs was built and none of the partners on the project were happy with its experience, it became clear that in order to deliver a clean, simple interface for file uploading and sharing we needed to leave the bounds of the WordPress admin. It didn’t take me long to decide that React would be the tool I used to build the new interface. There…
Source: WordPress
