Atomic Migration Strategy for Web Teams

Table of contents

1. Preface
   1. Important Concepts
      1. Atomic Design
      2. Technical Debt
      3. Migration Versus Rewrite
   2. What to Expect from This Report
   3. Conventions Used in This Report
   4. Using Code Examples
   5. O’Reilly Safari
   6. How to Contact Us
   7. Acknowledgments
2. 1. When to Rewrite an Application
   1. When Your Existing Application Is Likely the Best Choice
      1. You Are Still Finding Product/Market Fit
      2. The Product Is Mature and Not Being Actively Developed
      3. The Engineering Team Is Still Productive
   2. When a Rewrite Makes Sense
      1. Declining Marginal Productivity of an Additional Engineer
3. 2. Synchronous Versus Asynchronous Rewrites
   1. Synchronous Rewrite
      1. Large Teams
      2. Large Scope
      3. When to Do a Synchronous Rewrite
   2. Asynchronous Rewrite
      1. Building Modularly
      2. Developing at a Natural Pace
      3. Large Teams
      4. Large Scope
      5. When to Do an Asynchronous Rewrite
4. 3. Atomic Design: A Tool for Migration
   1. Build Complex Systems out of Simple Parts
      1. Atoms
      2. Molecules
      3. Organisms
      4. Templates and Pages
   2. Testing
      1. Pure UI
      2. Snapshot Testing
      3. Integration Testing
   3. Advantages
      1. A Complex System of Simple Parts
      2. Developing Components in Isolation
   4. Gotchas
      1. Huge Snapshot Files
      2. Atom or Molecule?
      3. Accidentally Synchronous Rewrites
   5. Product Roadmap and Migration Plan Alignment
      1. Similar Designs
      2. Differing Designs with an Inconsistent Existing Design
      3. Differing Designs with a Consistent Existing Design
5. 4. Step-by-Step Migration Guide with Atomic Design
   1. Getting Set Up
      1. Evaluating and Adjusting the Current Development Environment
   2. Initializing an Atom Library
      1. Set Up the Component Library
      2. Build the First Atom
      3. Atom Library Setup and Build and Publish Scripts
      4. Set Up Snapshot Tests
      5. Publish the Atom Library
      6. Migrate the First Atom
   3. A New Application Base
      1. Architecture
      2. Create a Git Repository
      3. Clone the Git Repository
      4. Initialize Package
      5. Initialize Tooling
      6. Create a Backend Package
      7. Create a Frontend Package
   4. Migrating the First Molecule
      1. Choose the First Molecule
      2. Build the First Molecule
      3. Migrate the First Molecule
   5. Continuing on the Migration Path
6. 5. Making the Business Case for a Migration
   1. Set Up Your Team for Success
      1. Onboarding the Team
      2. Enabling Independent Work in a Shared Repository
   2. Making the Business Case for a Migration
      1. The Product/Business Driven Engineering Team
      2. The Engineering-First, Technically Driven Team
      3. The Engineering/Product Partnership Team
7. 6. Conclusion: Building for Change