Start With the End in Mind
A lot of teams fall into the trap of designing everything around local development. That’s where you spend most days, so it’s natural. But what really matters is production. That’s where your decisions actually have to stand up to scrutiny.
If you want an Umbraco 17 setup that lasts, get clear on your environments from the start. You need at least three: local, staging, production. Each one should behave in a predictable way, with configuration differences made obvious and intentional—not accidental or mysterious.
This mindset helps with infrastructure, too. Figure out your hosting model early. Azure, AWS, whatever—it matters. Your choice shapes how you’ll deal with configuration, deployment, and scaling. Don’t just tack it on at the last minute.
So, don’t treat production as the finish line. Use it to shape your process from day one.
Choosing the right foundation
When you’re setting up your project, don’t overcomplicate. The latest .NET LTS with Umbraco 17 should be your starting point. Some people think splitting things into a bunch of projects is cleaner, but more often, it makes things messy before you really need the complexity.
Go for simplicity. A single web project is more than enough most of the time. What’s important isn’t being clever, it’s being consistent. Use clear folder structures, stick to simple naming conventions, and make sure everyone’s on the same page. Forget about over-abstracted architecture—you’ll end up with a monster nobody wants to deal with.
This isn’t the time for clever tricks. Save your creativity for solving business problems, not the solution structure.
Configuration done right!
Configuration almost always works—until it suddenly doesn’t. Leaning on just appsettings.json works for very simple setups, but once you add environments, cracks appear. Values drift. Secrets get tossed around. Pretty soon, you’re hunting down some weird issue at 11 p.m. and swearing under your breath.
Do it right: keep environment-specific settings out of your core configuration files. Put secrets where they belong, in real secret-management tools. Keep things clean and separated.
Strongly-typed configuration saves headaches. Instead of magic strings scattered everywhere, bind config to classes and validate them up front. It’s not glamorous, but your future self will thank you when you’re not pulling your hair out during a late-night bug hunt.
Dependency Injection: Keep it boring
Umbraco 17 lines up nicely with the .NET dependency injection system. That’s really all you need. There’s always a temptation to get fancy—custom containers, weird abstractions, patterns nobody remembers a month later. Ignore that urge.
Just register your services in a straightforward way. Clarity and maintainability matter more than “best practice” gymnastics. The real test? If a new dev joins, they should be able to understand how dependencies are wired up without a guided tour.
Content modeling that won’t haunt you
If you want to find the spot where shortcuts come back to bite the hardest, look at content modeling.
Good content modeling puts editors at the center. Clear naming, logical structures, and simplicity pay dividends. The new Block Grid editor is powerful, but don’t let it lure you into building something overly dynamic or deeply nested unless you really need it. Restraint is key.
Not every section needs to be configurable down to the pixel. Simple content models are easier to use, easier to maintain, and honestly, easier to explain to the people building content every week. Remember who’s in the CMS every day—it’s not usually the developer.
Local development that reflects reality
If you’ve ever heard, “Well, it works on my machine,” you know there’s a problem. Local development should reflect production as closely as you can make it. That doesn’t mean spinning up a full clone of every cloud service. But your key elements — database, configuration, critical dependencies — they should match up.
Getting started shouldn’t be a puzzle. A new hire should be able to clone the repo, follow some simple steps, and get up and running quickly. Docker can help, but it doesn’t replace discipline or clear instructions.
Pick a local setup and stick to it. Consistency is how you avoid nasty surprises when you move code from one environment to another.
Git, CI/CD, and Deployments
Here’s where a lot of setups start cracking. Manual deployments might work at first, but they don’t last. They’re slow, error-prone, and usually rely on just one or two people knowing “the” steps.
Automated pipelines are a must. With solid CI/CD, every change is automatically built, tested, and deployed the same way, every time. Less chaos, more control.
Just as important — have a rollback plan. Deployments will go sideways at some point. Make sure you can recover fast. Being able to flip back to a previous version is a survival tool, not a nice-to-have.
Performance is not a phase
Teams always say they’ll deal with performance “later”—but later rarely comes, and by then, the pain’s worse.
Even basic caching setups move the needle. Umbraco has decent tools for that built in, but they need intentional setup. Same goes for search — get Examine dialed in early, and think about bigger optimizations, like CDN integration, before you really need them.
No need to tune everything from day one, but don’t make choices that block easier wins later on.
Packages: Use them wisely
It’s tempting to install packages for everything, but every package is now your responsibility. You’ll need to maintain, update, and maybe replace them in the future.
Whenever possible, stick with what’s built in. When you need a package, pick one that’s actively maintained, has a community, and solves a real need — don’t just grab something because it saved you five minutes today.
A little caution now avoids big headaches when something breaks or is abandoned.
Documentation is part of the setup
People act like docuentation is optional. It isn’t. Good docs are part of a maintainable setup.
Clear onboarding guides, environment notes, deployment instructions — these reduce friction and keep knowledge from bottlenecking in one person’s head. Don’t skip editor documentation, either. People forget, and future you will thank you for the clarity.
A setup that stands the test of time
Great Umbraco 17 setups fly under the radar. They don’t draw attention or get in your way. They let you focus on the real work, roll with changes, and make deployments painless.
Stick to basics: consistency, clarity, and focusing on what your team actually needs — not what sounds cool.
The goal isn’t perfection on day one. The goal is building a project that makes sense — and still holds up — a year later.
So, take a hard look at your current setup. What’s likely to blow up or slow you down six months from now? That’s usually the place to start making real, lasting improvements.