Create New Project

An agent plugin for Claude Code and Codex that scaffolds a full cross-platform product in one shot — Next.js + shadcn/ui on the web side, Expo + NativeWind v5 + react-native-reusables + @expo/ui on the mobile side, and a design-system viewer — all wired into a single pnpm monorepo.

Invoke with /create-new-project in Claude Code or $create-new-project in Codex, then answer three questions: project name, platforms, shadcn preset. Everything else is deterministic.

Philosophy

Scripts execute, the agent orchestrates.

Scaffolding is a deterministic task. When an agent has to faithfully reproduce config files, JSON merges, and component code on every run, drift creeps in — wrong paths, dropped function arguments, lost package.json scripts. This plugin narrows the agent's job to three things:

Check the environment (adapts to the user's machine).
Collect inputs through interactive prompts.
Invoke one shell script that does everything else.

Every file that gets written is a template vendored in this repo. Every transform (package.json merges, font sync, token sync, style sync) is a Node script. No freehand regeneration, no "manually copy these fields," no "carefully reproduce this file."

Install

Claude Code

/plugin marketplace add addisonk/create-new-project
/plugin install create-new-project@create-new-project

Then invoke with:

/create-new-project

Codex

This repo includes a Codex manifest at .codex-plugin/plugin.json.

For terminal Codex, install the skill directly into the shared agent skill directory:

mkdir -p ~/.agents/skills
ln -s ~/Projects/create-new-project/skills/create-new-project ~/.agents/skills/create-new-project

Restart Codex, then invoke:

$create-new-project

If you want to test the plugin marketplace metadata as well, add the repo as a marketplace:

codex plugin marketplace add addisonk/create-new-project

Terminal Codex currently exposes marketplace add/upgrade/remove commands, but not a separate plugin install command. The direct ~/.agents/skills install is the dependable terminal workflow.

System requirements

Checked automatically via preflight — the plugin stops and tells you what to fix if anything's missing.

Universal:

Node 20+ — node -v
pnpm 10 — corepack enable && corepack prepare pnpm@10 --activate
gh CLI — brew install gh (clones the design-system viewer)
git

Mobile paths (Both / Mobile only):

Xcode — from the Mac App Store, then sudo xcode-select --install
iOS simulator runtime matching your Xcode version exactly. Xcode 26.4 requires iOS 26.4 simulator — having only an older runtime like iOS 18.6 is not enough. Xcode needs a matching SDK to compile.
- CLI install: xcodebuild -downloadPlatform iOS (~8 GB, 15–20 min)
- Or: Xcode → Settings → Platforms → + → iOS

Usage

/create-new-project   # Claude Code
$create-new-project   # Codex

The skill asks:

Project name — e.g. my-app
Platform — Both (web + mobile monorepo, recommended), Web only, Mobile only
Preset — shadcn preset ID or full https://ui.shadcn.com/create?preset=... URL. Default: b0.

The scaffold runs in one pass, including the ~15 min iOS dev client build at the end (required because @expo/ui isn't Expo Go-compatible). When it finishes, pnpm dev from the repo root starts web + mobile + design-system together and everything just works — no second manual step.

If the dev client build fails for any reason (simulator not available, SDK mismatch, etc.), the rest of the scaffold is still valid — rerun:

cd {name}/apps/mobile && npx expo run:ios

Updating

/plugin marketplace update create-new-project

Updates only trigger when the plugin version field bumps — commits alone don't trigger them. Check releases for what's in each version.

Auto-updates

Self-hosted marketplaces ship with auto-update off by default. Once you opt in, Claude Code refreshes plugins from this marketplace at every session startup (no manual /plugin marketplace update needed). Two ways to enable it:

Per-user (one-time toggle):

Run /plugin in Claude Code.
Open the Marketplaces tab.
Toggle auto-update on for create-new-project.

Via settings.json (good for managed/team environments):

Add to ~/.claude/settings.json (per-user) or your org's managed-settings file (team-wide):

{
  "extraKnownMarketplaces": {
    "create-new-project": {
      "source": { "source": "github", "repo": "addisonk/create-new-project" },
      "autoUpdate": true
    }
  }
}

Updates only run at session startup, not as a background poll. After an update lands you'll see a prompt to /reload-plugins to apply it without restarting Claude Code. See Claude Code docs → Configure auto-updates for the upstream reference.

What you get

Both (default)

{name}/
├── apps/
│   ├── web/              # Next.js 16 + shadcn/ui + Turbopack
│   ├── mobile/           # Expo SDK 55 + NativeWind v5 + reusables + @expo/ui
│   └── design-system/    # Theme tinker, block explorer, color/font editors
│                         # (saves changes back to packages/ui globals.css)
├── packages/
│   ├── ui/               # 55+ shadcn components (web)
│   ├── shared/           # Cross-platform types / utilities
│   ├── eslint-config/
│   └── typescript-config/
├── scripts/sync-mobile-tokens.mjs  ← web oklch → mobile hex
├── turbo.json
├── pnpm-workspace.yaml
├── .npmrc                # shamefully-hoist=true for Expo
└── package.json          # pnpm overrides + packageExtensions

Run:

pnpm dev — all three apps in parallel (web + mobile + design-system)
pnpm dev:web — web only
pnpm dev:design-system — design-system only
cd apps/mobile && npx expo run:ios — first-time mobile build (required)
pnpm dev:mobile — after first run

Web only

Next.js + shadcn monorepo with the design-system viewer, no mobile. pnpm dev for the main app, pnpm dev:design-system for the viewer.

Mobile only

Standalone Expo app with Expo Router, NativeWind v5, reusables, and @expo/ui. No monorepo. npx expo run:ios first, then pnpm dev.

Mobile starter screens

The mobile app ships with a three-tab starter that demonstrates both halves of the stack:

Home — pure @expo/ui SwiftUI primitives. SF Symbol grid, system fonts, liquid-glass-ready. Demonstrates the fully-native escape hatch.
Browse — Cards + lucide icons using NativeWind + reusables. Demonstrates the cross-platform path (covers ~90% of screens).
Settings — iOS-style grouped rows with Avatar, Badge, Separator.

OS-driven dark mode via useColorScheme(). NativeTabs for iOS 26+ liquid glass on iOS, Material 3 bottom nav on Android.

Design-system viewer

Lives at apps/design-system/ in the scaffolded project. It visualizes your shadcn monorepo's design system and lets you edit themes live — changes save back to packages/ui/src/styles/globals.css.

What it shows

Typography — font name, Aa specimen, weights, character overview per font
Color Palette — primary grid with foreground labels, utility colors with WCAG auto-contrast, charts, sidebar
Radius — visual scale from none to 4xl, resolved from theme
Blocks — shadcn preview 01 / 02 masonry grid

Features

Press D — toggle dark mode
Click-to-edit color pickers with a sticky save bar
Inline font editing via Command palette (Figma-style hover hints)
Section filter — ?section=color URL param
Auto-contrast — WCAG contrast with alpha compositing
Dynamic icons — reads iconLibrary from components.json

Manual install (outside the plugin)

gh repo clone addisonk/create-new-project apps/design-system -- --depth 1
rm -rf apps/design-system/.git
pnpm install
pnpm --filter design-system dev

Sharp edges

The scaffold handles these automatically — worth knowing so you don't wonder why things are the way they are:

Expo in pnpm monorepo — the root pnpm.overrides + packageExtensions + .npmrc shamefully-hoist=true are all required. Without all three, mobile resolution fails.
@expo/ui + Expo Go — incompatible. First mobile run must be npx expo run:ios. Afterwards, mobile's dev script uses expo start --ios --dev-client — without --dev-client it tries to open the Expo Go URL scheme and fails with xcrun simctl openurl ... exited with non-zero code: 60.
Port 3000 race — web and design-system both default to port 3000. Scaffold adds a 2s sleep to design-system's dev script so web always claims the lowest free port first. Auto-fallback preserved so nothing collides with other projects on your machine.
lucide-react-native under pnpm strict hoisting — the reusables CLI doesn't always hoist it into apps/mobile/node_modules. Scaffold installs it explicitly.
Xcode ↔ iOS SDK exact-version match — preflight enforces major.minor match (not just major.*), because xcodebuild fails with Unable to find a destination otherwise.

Local development

For editing this plugin and testing changes immediately:

# one-time setup
git clone git@github.com:addisonk/create-new-project.git ~/Projects/create-new-project
ln -s ~/Projects/create-new-project/skills/create-new-project ~/.claude/skills/create-new-project
ln -s ~/Projects/create-new-project/skills/create-new-project ~/.agents/skills/create-new-project

The symlinks mean edits under skills/create-new-project/ are picked up immediately by Claude Code and Codex — no reinstall needed. Codex also detects skill changes automatically in most cases; restart Codex if the update does not appear.

Repo layout:

.
├── .claude-plugin/
│   ├── plugin.json          ← plugin manifest (bump version to ship updates)
│   └── marketplace.json     ← self-hosted marketplace catalog
├── .codex-plugin/
│   └── plugin.json          ← Codex plugin manifest
├── .agents/plugins/
│   └── marketplace.json     ← Codex marketplace catalog
└── skills/create-new-project/
    ├── SKILL.md             ← thin orchestration layer
    ├── scripts/
    │   ├── bootstrap.mjs                ← main orchestrator
    │   ├── patch-root-package.mjs       ← merges pnpm overrides
    │   ├── patch-design-system.mjs      ← style + font sync, stagger dev
    │   ├── install-mobile-templates.mjs ← overlays mobile templates
    │   └── sync-mobile-tokens.mjs       ← oklch → hex for RN
    └── templates/
        ├── root/            ← .npmrc, tsconfig.base.json
        ├── shared/          ← packages/shared placeholder
        └── mobile/          ← postcss, metro, tsconfig, tw/, welcome screens

Shipping an update

Make changes under skills/create-new-project/.
Test locally (symlink means no reinstall).
Commit with a conventional-commit prefix and push. The .github/workflows/auto-bump.yml action handles the rest:
- feat: → minor bump
- fix: / perf: → patch bump
- feat!: / BREAKING CHANGE → major bump
- docs: / chore: / refactor: / style: / test: → no bump
The workflow writes the new version into .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and .codex-plugin/plugin.json, commits as chore: release vX.Y.Z, tags it, and pushes back to main. Users pick it up on their next /plugin marketplace update.

Prerequisite skills

The mobile path treats these related skills as source of truth. If you're on the Both or Mobile path and haven't installed them, quality drops:

expo-tailwind-setup — NativeWind v5 + Tailwind v4 CSS-first recipe
react-native-reusables — shadcn-philosophy components for React Native
expo-ui-swiftui — @expo/ui SwiftUI primitives (iOS)
expo-ui-jetpack-compose — @expo/ui Jetpack Compose primitives (Android)
building-native-ui — Expo Router conventions
native-data-fetching — network / data-fetching defaults

License

MIT

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Create New Project

Philosophy

Install

Claude Code

Codex

System requirements

Usage

Updating

Auto-updates

What you get

Both (default)

Web only

Mobile only

Mobile starter screens

Design-system viewer

Sharp edges

Local development

Shipping an update

Prerequisite skills

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 100 Commits
.agents/plugins		.agents/plugins
.claude-plugin		.claude-plugin
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
app		app
components		components
docs/solutions/ui-bugs		docs/solutions/ui-bugs
lib		lib
scripts		scripts
skills		skills
README.md		README.md
components.json		components.json
next-env.d.ts		next-env.d.ts
next.config.mjs		next.config.mjs
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Create New Project

Philosophy

Install

Claude Code

Codex

System requirements

Usage

Updating

Auto-updates

What you get

Both (default)

Web only

Mobile only

Mobile starter screens

Design-system viewer

Sharp edges

Local development

Shipping an update

Prerequisite skills

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages