Preface
Atomic design is the concept of “building web applications like Lego,” creating a solid reliable base off which you can iterate fast on your user interface. This guide gives detailed examples of atomic migration strategies for frontend teams to follow.
We’ve written this report with technical leads and engineering managers of frontend web teams working with single-page web applications in mind. It’s the guide that we wish we had when we undertook the daunting task of rewriting the client of our single-page application at Buffer.
We’ve taken a how-to guide approach for easy reference, but are speaking from our own experience. These steps have proven useful for team sizes from under 12 developers to larger engineering organizations of around 40 developers, where frontend infrastructure is an important part of the stack.
An application that’s fully server-side rendered or doesn’t have a frontend separated from the data and behavioral logic, or a team with hundreds of developers, will both likely have different needs. The further your own architecture and team context diverges from ours, the more judgment you’ll need to employ in deciding whether and how to apply this advice to your own situation.
Important Concepts
This section will give you an overview of concepts and principles that are essential to atomic design.
Atomic Design
Atomic design is a design system created by Brad Frost that shifts focus from designing full web pages to thinking in systems of modular components. It breaks up large complex interfaces into small simple pieces such as a generic button that can be conceptualized individually and used in a number of different contexts. Inspired by chemistry, Frost defines three constructs in growing order of complexity—Atom, Molecule, and Organism—that you can see illustrated in Figure P-1.
Figure P-1. An Atom, Molecule, and Organism
In atomic design, complexity is created by stitching atoms (the simplest components) together into molecules, and molecules into organisms—much like Lego blocks. Following other disciplines, symbols are defined that represent complex components made of simpler components. This allows engineers to reason about larger groups of complex systems without needing the entire context of the sub-components in their consciousness. As simple components are reused to form complex components, time is saved on testing and the user experience remains consistent across features.
Technical Debt
The metaphor technical debt was developed by Ward Cunningham to help us make a decision between two common approaches to adding a feature to some software: a quick and dirty solution that is difficult to extend and maintain, and a long-run maintainable solution that will take longer to implement initially. The idea is that when you take on technical debt, you get an immediate payoff up front with a speedy feature, but you pay that back over time with interest as the long-run consequences are felt.
In this text, we’re extending technical debt to include Martin Fowler’s sense of past decisions that are no longer what the application needs and that are hard to reverse without substantial refactoring. These decisions increase the complexity of the codebase because they make future changes more difficult, so we’re including this type of decision as technical debt, too
Much like financial debt, technical debt can be used as a tool that can be helpful in small amounts and crushing when it becomes unmanageably large. Incurring some technical debt can be a good thing if it helps get the product out sooner, so long as you go back and refactor the software to pay back some of the debt so it remains manageable.
The term technical debt is used in several places throughout this report and is an important metaphor to understand when deciding to do a software rewrite. Even though it is difficult to directly measure technical debt, when enough of it piles up that the codebase becomes extremely difficult to change, a software rewrite might be the best option to pay the technical debt back.
There is an alternative sense in which any older code is referred to as technical debt. Your old code might be just fine, and it’s definitely (and disturbingly!) possible to create brand-new technical debt as well.
Migration Versus Rewrite
In many ways, this is a rewrite manual, but we’ve chosen to use the term “migration” instead of “rewrite" to emphasize that this is not a full application rewrite of an entire codebase. Instead, this is a partial rewrite of the client only—the presentation layer of your app. This manual assumes that your data and behavior are fairly separated out from the frontend presentation, so that you can swap out the user interface without changing how data is stored, accessed, and transformed.
We’ve used the term migration to highlight the fact that this method is a modular, continuous rewrite of your apps’ views from one presentation system, or client, to another. It can happen over time while the product is in continuous use and development, rather than requiring a brand-new interface that is built and put into production to replace the old in one fell swoop.
What to Expect from This Report
This preface has provided you with an overview of the key concepts and principles of atomic migration. In Chapter 1, you’ll learn how to decide if a software rewrite makes sense for your situation, or if sticking with the current codebase is the best option. Next, in Chapter 2, you’ll see two different patterns for rewriting software: the more traditional synchronous rewrite and the nonblocking asynchronous rewrite. In Chapter 3 you’ll gain a deeper understanding of atomic design and how it can be used as a tool for rewriting software. From there, in Chapter 4, you’ll apply what you learned and go step by step through an asynchronous rewrite with atomic design. Finally, in Chapter 5, you’ll learn how to set your team up for long-term success with the rewrite process.
Conventions Used in This Report
The following typographical conventions are used in this report:
- Italic
-
Indicates new terms, URLs, email addresses, filenames, and file extensions.
Constant width-
Used for program listings, as well as within paragraphs to refer to program elements such as variable or function names, databases, data types, environment variables, statements, and keywords.
Constant width bold-
Shows commands or other text that should be typed literally by the user.
Constant width italic-
Shows text that should be replaced with user-supplied values or by values determined by context.
Tip
This element signifies a tip or suggestion.
Note
This element signifies a general note.
Warning
This element indicates a warning or caution.
Using Code Examples
Supplemental material (code examples, exercises, etc.) is available for download at https://github.com/hharnisc/my-component-library-boilerplate and https://github.com/hharnisc/my-monorepo-boilerplate.
This report is here to help you get your job done. In general, if example code is offered with this report, you may use it in your programs and documentation. You do not need to contact us for permission unless you’re reproducing a significant portion of the code. For example, writing a program that uses several chunks of code from this report does not require permission. Selling or distributing a CD-ROM of examples from O’Reilly books and reports does require permission. Answering a question by citing this report and quoting example code does not require permission. Incorporating a significant amount of example code from this report into your product’s documentation does require permission.
We appreciate, but do not require, attribution. An attribution usually includes the title, author, publisher, and ISBN. For example: “Atomic Migration Strategy for Web Teams by Harrison Harnisch and Katie Womersley (O’Reilly). Copyright 2018 O’Reilly Media, Inc., 978-1-491-99994-3.”
If you feel your use of code examples falls outside fair use or the permission given above, feel free to contact us at [email protected].
O’Reilly Safari
Note
Safari (formerly Safari Books Online) is a membership-based training and reference platform for enterprise, government, educators, and individuals.
Members have access to thousands of books, training videos, Learning Paths, interactive tutorials, and curated playlists from over 250 publishers, including O’Reilly Media, Harvard Business Review, Prentice Hall Professional, Addison-Wesley Professional, Microsoft Press, Sams, Que, Peachpit Press, Adobe, Focal Press, Cisco Press, John Wiley & Sons, Syngress, Morgan Kaufmann, IBM Redbooks, Packt, Adobe Press, FT Press, Apress, Manning, New Riders, McGraw-Hill, Jones & Bartlett, and Course Technology, among others.
For more information, please visit http://oreilly.com/safari.
How to Contact Us
Please address comments and questions concerning this report to the publisher:
- O’Reilly Media, Inc.
- 1005 Gravenstein Highway North
- Sebastopol, CA 95472
- 800-998-9938 (in the United States or Canada)
- 707-829-0515 (international or local)
- 707-829-0104 (fax)
To comment or ask technical questions about this report, send email to [email protected].
For more information about our books, courses, conferences, and news, see our website at http://www.oreilly.com.
Find us on Facebook: http://facebook.com/oreilly
Follow us on Twitter: http://twitter.com/oreillymedia
Watch us on YouTube: http://www.youtube.com/oreillymedia
Acknowledgments
We’d like to thank Case Sandberg for inspiring the direction of this report and the Buffer team for working with us to validate these ideas and approaches in the real world.