Quick start

# Interactive scaffold (pass a name or answer the prompt)
npx create-trpc-appx@latest my-app
# or just:
npx create-trpc-appx@latest

# Scaffold from a bundled template
npx create-trpc-appx@latest my-app --example nextjs-app

# Run an example from GitHub (no scaffold)
create-trpc-appx run trpc/trpc-openapi#master --example-path examples/with-nextjs --prepare-only

Tip: add --yes to skip prompts. Use --verbose for debug logs.

Support the project

If this project helps you, please consider:

• Starring the repo
• Sponsoring on GitHub to support maintenance

Features

| ⚡ | What | Details | | --: | :-------------- | :----------------------------------------------------------- | | 🚀 | Fast builds | ESM output via tsup | | 🧠 | Smart scripts | Framework heuristics: dev → start/preview → build | | 🧭 | Workspace‑aware | Detects npm/yarn/pnpm workspaces and picks the right package | | 🛰️ | Robust runner | Cache, offline mode, retries, checksum verification | | 🔌 | Env/Ports | Inline env, env-file, fixed/auto ports |

Commands

| Command | Purpose | | :---------------------------------- | :------------------------------------------------------- | | create-trpc-appx | Interactive scaffold for a new app | | create-trpc-appx doctor | Diagnose Node, package managers, git, proxy, and network | | create-trpc-appx info [dir] | Show scripts, workspaces, engines for a project | | create-trpc-appx run <github-url> | Fetch, prepare, and run a public example from GitHub |

Options

Scaffold options

| Option | Type | Default | Description | | :--------------------------------- | :----- | :------ | :---------------------------------------------------------------- | | -e, --example [name\|github-url] | string | — | Use a bundled template or a GitHub URL | | --example-path <path> | string | — | Required when branch contains a slash or to target a subdirectory | | --use-npm / --use-pnpm | flag | auto | Prefer a package manager | | --yes | flag | false | Skip prompts | | --verbose | flag | false | Extra logs |

Run options (by feature)

| Option | Type | Default | Description | | :------------------ | :--------- | :-------- | :-------------------------------------------- | | --env KEY=VALUE | repeatable | — | Inline env vars to pass | | --env-file <path> | string | — | Load env vars from file | | --port <number> | number | — | Set PORT | | --auto-port | flag | false | Find a free port starting at --port or 3000 | | --script <name> | string | heuristic | Force a specific script |

| Option | Type | Default | Description | | :------------------- | :----- | :-------- | :-------------------------------------------------------- | | --offline | flag | false | Use cache only (no network) | | --no-cache | flag | false | Disable cache and force re‑download | | --cache-dir <path> | string | XDG cache | Use a custom cache dir | | --prepare-only | flag | false | Download/extract (and optionally install) without running | | --no-install | flag | false | Skip dependency installation |

| Option | Type | Default | Description | | :------------------ | :------------------------ | :------ | :--------------------------------------- | | --prebuild <mode> | auto|always|never | auto | Prebuild before start when appropriate |

Heuristics: Next.js/Remix/SolidStart → dev → start → build; Vite/Astro/SvelteKit → dev → preview → start.

You can pass --use-npm or --use-pnpm with run as well. The runner otherwise detects npm/yarn/pnpm via lockfiles and packageManager fields and installs at the appropriate workspace root when needed.

Templates

| Name | Stack | | :----------- | :--------------------------------- | | default | Node + tRPC server + simple client | | nextjs-app | Next.js App Router + tRPC | | vite-react | Vite + React + tRPC |

Use during scaffold with --example <name> or point to any GitHub example URL.

Run examples from GitHub

# Full URL with subdirectory
create-trpc-appx run https://github.com/trpc/trpc-openapi/tree/master/examples/with-nextjs --prepare-only

# Short/SSH forms and explicit example-path
create-trpc-appx run trpc/trpc-openapi#master --example-path examples/with-nextjs

The runner caches archives, verifies checksums, retries transient failures, and falls back to git clone when necessary. The cache can be safely removed at any time.

Monorepos & script detection

The runner scans workspaces (npm/yarn/pnpm) and common subfolders (apps/, packages/) to pick the best runnable directory based on scripts and naming.

The runner detects common frameworks (Next.js, Vite, Remix, Astro, SvelteKit, SolidStart) and picks the best script automatically:

• Next.js, Remix, SolidStart: prefers dev, then start, then build.
• Vite, Astro, SvelteKit: prefers dev, then preview, then start.
• Prebuild is triggered for preview/start if a build script exists (Vite/Astro/SvelteKit), or for start when build exists (Next.js/Remix/SolidStart).

1. If current dir has a runnable script → use it.

2. If workspace root → expand workspace globs and pick the best candidate based on:

   • script presence: dev > preview > start > build
   • directory hints: examples, app, web, site, server, api

3. Otherwise, scan first two levels for runnable packages.

Troubleshooting

• engines.node mismatch → use nvm/Volta to switch versions
• behind a proxy → set HTTP_PROXY/HTTPS_PROXY
• private repos or higher rate limits → set GITHUB_TOKEN
• no runnable scripts found → check package.json scripts or pass --script

If you see error: unknown command 'my-app' when running npx create-trpc-appx my-app, you're likely on an older CLI that didn't accept a positional project name at the root. Update to the latest version or run without the name and answer the prompt:

npx create-trpc-appx@latest

Run diagnostics:

create-trpc-appx doctor

Security

This CLI can download and run third‑party code. Review sources before running unfamiliar examples. Prefer a sandboxed/test environment when exploring.

Contributing

Contributions welcome—PRs and issues appreciated.

Acknowledgments

This project has been based on Create Next App, so a huge thank you goes to every and single one who worked on it.

Attribution for one of the icons used in the logo: Design icons created by monkik - Flaticon

License

Licensed under MIT.