The hard part of a starter-kit generator isn't templating — it's compatibility

aymen jdily — Wed, 02 Sep 2026 23:33:10 +0000

Every starter kit I tried had the same shape: one big repo with everything in it. Clone it, then spend an afternoon deleting the auth provider you don't use, the ORM you don't use, and the billing integration you won't need for months.

So I built the opposite — a generator that asks 10 questions and emits only the stack you picked. Framework, components, database, ORM, auth, billing, email, landing page, package manager, name.

I assumed the hard part would be templating. It wasn't. Templating is string interpolation with extra steps. The hard part is that most combinations of those answers are illegal, and the interesting bugs all live in that gap.

The problem: a menu that lies

Say someone picks React + Vite, then Drizzle, then Stripe.

That project cannot work. A Vite SPA is a bundle that runs in someone's browser. There is no server, so there is nowhere to keep a Postgres connection string or a Stripe secret key. Anything the app can read, every visitor can read. Generate it anyway and you've handed someone a repo that leaks its own credentials the first time they deploy it.

The lazy fix is to generate it and put a warning in the README. The slightly-less-lazy fix is to grey the option out. I didn't like either — a greyed row invites a click and then explains nothing.

Options carry their own requirements

Instead of a wizard full of if statements, each option declares what it needs:

{
  id: "drizzle",
  label: "Drizzle",
  icon: "drizzle",
  requires: { database: "sql", framework: "server" },
},

And each option offers tags describing what it is:

{
  id: "nextjs",
  label: "Next.js",
  icon: "nextdotjs",
  tags: ["nextjs", "server"],
},

Tags rather than ids, deliberately. If requirements named ids, adding a new Postgres host would mean revisiting every ORM to add it to a list. A new host tagged sql is understood by Drizzle without touching Drizzle at all.

Filtering is then one function:

export function optionsFor(
  question: StarterQuestion,
  answers: StarterAnswers,
): readonly StarterOption[] {
  return (question.options ?? []).filter((option) =>
    Object.entries(option.requires ?? {}).every(([id, tag]) =>
      tagsOf(id as StarterQuestionId, answers).includes(tag),
    ),
  );
}

An option whose requirement isn't met is left out entirely, not disabled. Pick React + Vite and Drizzle, Stripe and Resend simply aren't on the menu.

A few rules this encodes that surprised me while writing them:

Auth0 only appears beside Next.js. @auth0/nextjs-auth0 is the only SDK of theirs with a server session. The React one is client-only, so currentUser() would have nothing to read during SSR.
Supabase Auth only appears if you picked Supabase. It's part of the host, not a library you bolt onto Neon.
Every email provider needs a server. They all authenticate with an API key that can send mail as you. Shipping that in a browser bundle is handing it away.

Changing an answer has to un-choose things

There's a second-order problem. Pick Supabase, then Supabase Auth, then go back and switch to Neon. Supabase Auth is no longer on offer — but it's still sitting in the payload, invisible in the UI.

So the answers get pruned on every change, using the same optionsFor that drives the menu:

export function pruneAnswers(answers: StarterAnswers): StarterAnswers {
  const kept: StarterAnswers = {};

  for (const question of STARTER_QUESTIONS) {
    const answer = answers[question.id];
    if (answer === undefined) continue;

    if (question.kind === "text") {
      kept[question.id] = answer;
      continue;
    }
    if (optionsFor(question, kept).some((option) => option.id === answer)) {
      kept[question.id] = answer;
    }
  }
  return kept;
}

One source of truth for "is this legal", used by both the UI and the payload.

Proving it: build all of them

Rules in a data structure are a claim. The only way I know to keep a claim true is to execute it, so CI generates every legal combination on every push and parses the TypeScript that comes out.

That's 450 stacks. It would be far more, except questions that can't interact with anything are pinned to a single value rather than multiplied out. Package manager is a good example: nothing requires a tag it carries, and none of its options require anything. Multiplying it out took the matrix from 696 to 2,784 to 11,136 combinations and told me nothing new.

Rather than hardcode which questions to pin, the matrix reads the requirement graph:

export function isOrthogonal(question: StarterQuestion): boolean {
  const ownsRequirements = (question.options ?? []).some(
    (option) => Object.keys(option.requires ?? {}).length > 0,
  );
  if (ownsRequirements) return false;

  const mine = tagsOffered(question);
  return !requirementGraph().some(
    ([id, tag]) => id === question.id || mine.has(tag),
  );
}

The moment someone writes requires: { packageManager: ... }, the pinning stops on its own and the full cross-product comes back. There's a test asserting that too — the pinning is a claim about the data, and a stale claim would silently shrink the coverage of three suites.

The generated repo tests itself

Each starter arrives with its own suite already passing — a spec beside every module, and some rules about its own structure. My favourite is this one, which walks src/ and fails if any file other than the two env modules reads the raw environment:

it("reads the environment only in env.ts and public-env.ts", async () => {
  // ...walks src/, collects offenders...
  expect(offenders).toEqual([]);
});

The point is that process.env.DATABASE_URL! scattered around a codebase fails at 3am in production with "cannot read property of undefined", instead of at boot with the name of the variable you forgot.

That test caught me. My Prisma client template decided whether to cache itself across hot reloads by reading process.env.NODE_ENV directly — so every starter generated with Prisma failed its own suite on a clean checkout. The first thing a buyer runs, broken.

The guard that should have caught it existed. It just built a single fixture, and that fixture pinned the ORM to Drizzle, so the Prisma template was never generated inside the test. I widened it to walk the whole matrix, watched it fail, fixed the template, watched it pass:

- []
+ [ "src/db/client.ts" ]

Then I reverted the fix to make sure the test failed again for the right reason. A guard you haven't watched fail is a guard you're guessing about.

What I'd tell myself at the start

Model compatibility as data, not control flow. The rules ended up being a handful of requires declarations rather than a wizard full of branches, and adding an option now means adding an option.
Remove impossible choices instead of disabling them. A disabled row is a question the UI refuses to answer.
Generate the whole matrix in CI. Every "surely that combination is fine" I've had has been wrong at least once.
Write the fixture wide. My one real bug got through a test that existed and passed, because the fixture was narrow.

The generator is free while it's in beta if you want to try breaking it: https://www.startersaaskit.com

I'd genuinely like to hear which stack pairings you think are missing — or which ones I'm wrong to be blocking.