How to write a project brief that actually helps you hire a Next.js developer

Writing a good brief before you hire a Next.js developer is the single thing that separates projects that land on time from ones that drift for months. After working through 15+ headless builds — some I briefed myself, many I was handed — the pattern is consistent: the brief determines the outcome more than the developer does.

The four mistakes I see in almost every agency brief

'Just like our current site, but faster.' This shows up verbatim more than you'd expect. It tells a developer nothing about what 'faster' means to you (sub-2-second load? better Google scores? reduced bounce?), and it implicitly asks them to replicate a structure that probably needs rethinking. Developers will fill the gaps with their own assumptions. Those assumptions will be wrong, and you'll pay to fix them.

Starting dev before the content model is agreed. A headless CMS like Sanity structures your content into types — a blog post is different from a case study, which is different from a team member profile. If your developer starts building while you are still deciding what content you have, one of two things happens: they build a generic schema that needs expensive rework, or they pause and wait while you figure it out. Neither is cheap. Content modelling is a design decision, not a dev task. It needs to happen before the first line of code.

No staging environment expectation. It surprises clients when I ask: 'Where do you want to review work in progress?' The answer is almost always 'Oh, can't you just show me screenshots?' A headless build needs a staging URL — ideally a Vercel preview deployment tied to a branch — where you can click through real pages, test forms, and check the CMS editor before anything goes live. If this is not written into the brief, it either gets skipped or gets added as a change request.

A Figma file with no copy. Handing over a design with placeholder text ('Lorem ipsum' or 'Headline goes here') means your developer will build components that have never been tested with real content. Headlines will be too short. Navigation labels will overflow. The hero image ratio will be wrong for your actual photography. Designs without real copy are wireframes dressed up as specifications. They create rework.

What a good brief actually contains

Goals and success metrics. What does success look like six months after launch? Be specific: 'Core Web Vitals scores above 90 on PageSpeed Insights', 'editorial team can publish a new case study without developer involvement', 'site loads in under 1.5 seconds on a mid-range Android device on 4G'. Vague goals produce vague proposals. Specific goals let a developer tell you honestly whether your budget covers them.

A content inventory. List every content type your site needs: pages, blog posts, case studies, team bios, product listings, testimonials, FAQs, event listings. For each one, note roughly how many items exist now and how often they change. This is not a full schema design — that is the developer's job — but it gives them the information they need to estimate the CMS setup accurately.

Integration requirements. Be explicit about every third-party service the site must connect to. Contact forms — which provider? HubSpot, Formspree, a custom SendGrid route? E-commerce — Shopify, Stripe, something else? Analytics — GA4, Plausible, Fathom? Cookie consent — OneTrust, CookieYes? Each integration adds scoping time, and missing one is how projects run over budget.

Performance targets. If you have specific Core Web Vitals thresholds, state them. If you do not know what those are, say 'we want to score above 90 on Google PageSpeed Insights for mobile' — that is a reasonable default and every good Next.js developer will know what it requires. If speed is genuinely not a priority, say that too. It changes architectural decisions.

Handoff and support requirements. What happens after launch? Does the developer hand over to an in-house team? Do they need to write documentation for non-technical editors? Is there a retainer for ongoing changes? Who owns the CMS project and the Vercel account after handoff? These questions feel administrative, but they determine how a developer prices ongoing work and whether they build for maintainability or for speed of delivery.

Timeline and hard constraints. A product launch date, a trade show, a contract renewal — if there is a real deadline, name it and explain why it is fixed. Developers will design a delivery plan around hard constraints. They cannot do that if you list a target date but not the reason behind it.

A brief checklist before you send the document

Before you share a brief with any developer or agency, run through this list:

• [ ] Success metrics are specific and measurable, not adjectives ('faster', 'better', 'modern')
• [ ] Every content type is listed, with rough item counts and update frequency
• [ ] Every third-party integration is named, not implied
• [ ] A performance target is stated (PageSpeed score, LCP in seconds, or equivalent)
• [ ] Staging environment access is expected and described
• [ ] Figma files include real headlines, real navigation labels, and real body copy samples
• [ ] Post-launch support expectations are written down (retainer, handoff docs, ownership)
• [ ] Any hard deadlines are named with the reason behind them

A brief built on this list will take two to four hours to write properly. That investment will save you far more than two to four hours in back-and-forth, scope creep, and rework once the build starts. Developers price uncertainty — a clear brief is the most direct way to bring a quote down.