Rickety local builds are a bad project smell

Published 2020-05-25

Everyone (engineers, designers, project managers) on a web project should be able to spin up a local dev environment in less than two hours, using their preferred hardware and a README

This is a two-way test:

  1. the engineering team should have the build optimized and documented such that this task is relatively simple
  2. the non-engineering team should have enough savvy to follow the recipe

If a relatively savvy user needs half a day & a lot of handholding to get a local build running, that’s a bad project smell. It means the project exceeds its team’s capabilities.


  • … the project is too complex
  • … the architecture is too fragile/hardware dependent
  • … the team is too small for its ambitions
  • … you need dedicated operations personnel
  • … you need containerization
  • … your documentation sucks
  • … your team isn’t techy enough

If your build recipe is “go ask the lead engineer for help” and/or “use only this exact hardware profile” and it scales, you are fine. That means your architecture is right-sized for your ambitions.

But if a local (re) build blocks progress (examples: onboarding a new member, a remote dev trying to contribute, a designer who needs to test a feature branch for acceptance)…then your project has officially outgrown something.