A few months ago I wrote down how I set up every new project: one import alias, folders laid out before any code, typed content and data seams, a query client, design tokens and a CLAUDE.md that tells humans and AI where everything goes. Following it by hand takes about an hour.
I followed it by hand a lot. After the fifth or sixth time I noticed I wasn't making decisions any more, just retyping the same files and fixing the same typos in tsconfig.json. A checklist you run identically every time is a program you haven't written yet, so I wrote it.
The result is CleanStart, published on npm as @devjoemedia/cleanstart:
npx @devjoemedia/cleanstart
Run it inside a freshly created Next.js, TanStack Start or Expo app. It works out what the project is, asks a few questions, writes the structure into the right folders, patches the config and installs what's missing. This post covers what it adds, how it works inside, and the decisions that shaped it.
What you get
After a run, a new project has the same shape whichever framework it started on:
src/
├── components/
│ ├── common/icon.tsx string key → icon
│ └── layout/ ui/
├── content/ data/ typed page copy and mock records
├── hooks/queries/ mutations/
├── lib/ errors, http-client (+ utils and seo on web)
├── constants/ cache times, env, feature flags
├── integrations/tanstack-query/ query client + provider
├── stores/
└── types/index.ts every shape in the app
CLAUDE.md house rules for you and your AI pair
docs/00-setup.md first numbered plan
It also does the fiddly config work:
- adds the import alias:
@/on Next.js and Expo (the alias they already ship with),#/on TanStack Start - adds
typecheck,formatandcheckscripts, and turns onnoUnusedLocalsandnoUnusedParameters - wraps the app in a single
QueryProvideron Next.js and Expo (TanStack Start's router integration already provides one) - writes brand tokens into the stylesheet on web, or a light and dark palette with a
useColors()hook on Expo - installs
@tanstack/react-queryplus the icon and class-name helpers each platform needs
Only the files your framework uses are added. A Next.js app doesn't get a useColors() hook, and an Expo app doesn't get a Tailwind token block.
Detect, don't ask
The first design rule was that the tool should never ask something it can work out. Most of what it needs is already in the project:
export const FRAMEWORKS = {
next: { label: 'Next.js', dep: 'next', platform: 'web' },
tanstack: { label: 'TanStack Start', dep: '@tanstack/react-start', platform: 'web' },
expo: { label: 'Expo (React Native)', dep: 'expo', platform: 'native' },
}
The framework comes from package.json: whichever identifying dependency is installed. The package manager comes from the lockfile (pnpm-lock.yaml, yarn.lock, bun.lock, package-lock.json), falling back to the user agent of whatever ran npx. The source layout comes from the file system: Next.js with or without src/, and Expo Router reading routes from src/app or app/.
Only when detection is genuinely ambiguous does it ask, and --framework skips the question entirely. It also refuses early when the project can't work: no package.json, a Next.js Pages Router app, or an Expo app without Expo Router. Failing on the first line with a clear message beats writing forty files into the wrong place.
Templates in layers
The templates aren't one folder per framework. That would mean three copies of every shared file, drifting apart over time. Instead they're layers, applied in order:
function layersFor(framework, example) {
const { platform } = FRAMEWORKS[framework]
const layers = ['shared', platform, framework]
if (framework !== 'tanstack') layers.push('prettier')
if (example) layers.push('example/shared', `example/${platform}`, `example/${framework}`)
else layers.push('blank')
return layers
}
shared holds what every project gets: types, the error helper, the HTTP client, constants and CLAUDE.md. web or native add platform pieces like cn() or the colour hook. The framework layer adds the last few files that only make sense there. A file lives in exactly one layer, so fixing it fixes it everywhere.
Templates use a deliberately tiny syntax: {{key}} for values, and {{#flag}}…{{/flag}} blocks that only survive when the flag applies. One CLAUDE.md template covers all three frameworks:
{{#expo}}
- **Expo** with **React Native** and **Expo Router** (file-based routes in `{{appDir}}/`)
{{/expo}}
{{#web}}
- **Tailwind CSS v4** with shadcn/ui primitives; every colour is a CSS variable
{{/web}}
Templates are written with #/ imports. When the project uses @/, the renderer rewrites the prefix on the way out, so I maintain one spelling and every framework gets its own.
Patch, don't overwrite
Copying new files is the easy part. The risky part is editing files the project already has: package.json, tsconfig.json, the stylesheet and the root layout. CleanStart never replaces those. It makes the smallest change that does the job.
tsconfig.jsonfiles usually contain comments and trailing commas, whichJSON.parserejects. CleanStart ships a small JSONC reader instead of a dependency, adds the alias path and the two strictness flags, and leaves everything else alone.- The stylesheet gets one token block appended at the end, tagged with a
cleanstart:tokensmarker. If the project already defines--background, the block maps onto it instead of redefining it. - The Next.js layout gets
{children}wrapped in<QueryProvider>, and the import inserted after the last existing import. - The Expo layout returns a navigator, so CleanStart finds the default export's
return (, walks the parentheses to the matching), and wraps exactly that JSX. It handles the one-linereturn <Stack />form from the blank template too.
The inserted import matches the file's own style: double quotes if the file uses double quotes, semicolons if it uses semicolons. It's a small thing, but it means the diff looks like a person wrote it, and the formatter doesn't rewrite the file on the next save.
When a patch can't be applied safely, like a layout with no {children}, CleanStart says so and prints what to add by hand. It doesn't guess.
Safe to run twice
I wanted to be able to run it on a project that already has some of this setup, or rerun it after an upgrade, without fear. So every step is idempotent:
- existing files are skipped unless you pass
--force - the token block and the provider check for themselves before inserting
package.jsonscripts only fill gaps (pkg.scripts?.typecheck ?? 'tsc --noEmit'), so your own scripts win- an existing
CLAUDE.mdkeeps its content, and the house rules are appended below it once
--dry-run lists every file it would create, update or skip without writing anything. I use it on any project I didn't start myself.
Questions that fill in the files
The early versions left placeholders like <Project name> everywhere, and nobody ever went back to replace them. Since 0.5 it asks instead, and writes the answers straight into the files:
Project name (My App): Joe's Café
Short description (optional): Fresh coffee in Accra.
Site URL (https://www.example.com): joescafe.com
Author (Joseph Nartey):
Brand colour (#d2461a): #1e40af
Add the menu example slice? (y/N): y
Every answer is validated as you type. A URL without https:// gets one, a three-digit hex colour is expanded, and an invalid value asks again instead of failing later. The author defaults to your git user.name. Every question has a flag, and --yes skips them all, so the same command works in CI.
The brand colour is the most interesting answer. You pick one hex value, and the tool has to choose text that's readable on top of it. It computes the colour's relative luminance, the same formula WCAG uses for contrast, and picks white or near-black, whichever contrasts more:
export function readableOn(hex) {
const [r, g, b] = [1, 3, 5].map((i) => {
const c = parseInt(hex.slice(i, i + 2), 16) / 255
return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4
})
const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
return 1.05 / (luminance + 0.05) >= (luminance + 0.05) / 0.05 ? '#ffffff' : '#171717'
}
On Expo it also mixes a lighter version of the colour for the dark palette, so a deep blue stays visible on a dark background.
The example slice
An empty structure tells you where things go, but not how they connect. --example adds one complete vertical slice, a café menu, written the way every feature in the project should be:
type → data → query hook → page → component
The type lives in types/index.ts. The records live in data/menu.ts, behind the data seam. The copy, including the loading, empty and error messages, lives in content/menu.ts. The hook is the only thing the screen talks to:
const fetchMenu = withErrorHandling(async (category?: string) => {
await new Promise((resolve) => setTimeout(resolve, 300)) // simulate latency
return getMenu(category) // swap for httpClient.get<Array<MenuItem>>('/menu') when the API is live
}, 'Failed to load the menu')
export const menuQueryOptions = (category?: string) =>
queryOptions({
queryKey: menuKeys.list(category),
queryFn: () => fetchMenu(category),
staleTime: DEFAULT_STALE_TIME,
gcTime: DEFAULT_GC_TIME,
})
When the real API exists, you change one line in the hook. The page, the components and the loading states don't notice. The intended workflow is to copy the slice for your first real domain, then delete it. Without the flag, nothing menu-related is added.
Why CLAUDE.md is part of the output
Half the value of a convention is that it's written down where it will be read. Most of my projects are built with Claude Code in the loop, and an AI pair follows written rules far more reliably than implied ones.
So the generated CLAUDE.md isn't a generic template. It's rendered for the project: the real stack, the real commands for the detected package manager, the real alias, and the folder rules for this framework. docs/00-setup.md lists exactly what was installed and what's left to do, as the first numbered plan in the project's docs/ folder. The first time you ask for a feature, the structure is already explained to whoever, or whatever, writes it.
Zero dependencies
CleanStart has no runtime dependencies. Argument parsing is node:util's parseArgs, prompts are node:readline/promises, and file work is node:fs. That keeps npx fast on a cold cache, and it means a tool whose whole job is a clean starting point doesn't pull a few hundred transitive packages onto your machine first. The cost was writing a JSONC reader and a forty-line template renderer by hand, which was a fair trade.
Using it for real
The best test of a scaffolding tool is building on top of it. Lamp, the Scripture word game I'm building, started from a blank Expo app and one CleanStart run. Its CLAUDE.md still opens with the <!-- cleanstart --> marker. Every feature since then, from the word search to the Supabase-backed groups, followed the same type → data → hook → screen path the example slice demonstrates.
That's the payoff I was after. The hour of setup is gone, and so is the drift: every project starts with the same rules, so moving between them costs nothing.
Coming soon: NestJS and Node with Express
Today CleanStart covers the frontend: two web frameworks and one native one. Most of my projects also have an API beside them, and that side deserves the same treatment.
Next up is backend support, starting with NestJS and Node with Express. The goal is the same as on the frontend: run one command inside a fresh project and get a consistent structure. That means modules or routes laid out the same way every time, typed request and response shapes, config and environment handling, error handling in one place, and a CLAUDE.md that describes the backend's rules. Detection will work the same way too, from @nestjs/core or express in package.json.
If you'd like it to support a particular stack or convention, open an issue on GitHub.
Try it
# Next.js
npx create-next-app@latest my-app --ts --tailwind --eslint --app --src-dir
cd my-app && npx @devjoemedia/cleanstart
# TanStack Start
npx @tanstack/cli@latest create my-app --add-ons tanstack-query --toolchain eslint
cd my-app && npx @devjoemedia/cleanstart
# Expo
npx create-expo-app@latest my-app
cd my-app && npx @devjoemedia/cleanstart
Add --example for the menu slice, or --dry-run to see what would change first. It needs Node 20 or newer. The source is on GitHub under the MIT licence, and issues and pull requests are welcome.