create-trpc-appx

v1.0.3

Published

3 hours ago

Create tRPC-powered apps with one command

0High
0Medium
0Low

omar-dulaimi

trpc create-trpc-app

Quick start

Requires Node.js 22.12 or newer.

# 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
npx create-trpc-appx@latest my-app --example vite-react

# Scaffold from an official tRPC example (any directory in trpc/trpc examples/)
npx create-trpc-appx@latest my-app --example minimal

# Run an example from GitHub without scaffolding
npx create-trpc-appx@latest run trpc/trpc#main --example-path examples/minimal --prepare-only

Then:

cd my-app
npm run dev

Everything the CLI scaffolds targets tRPC v11 (currently 11.18.0).

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

Options

Scaffold options

Root options must come before a subcommand name, and subcommand options after it: create-trpc-appx run <url> --example-path <dir>.

Run options (by feature)

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

You can pass --use-npm, --use-pnpm or --use-yarn 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

Three templates ship inside the package, so they work with no network access to GitHub. All three are on tRPC v11 and are verified to build and run in CI.

The React templates use @trpc/tanstack-react-query, the integration tRPC recommends for new projects. The older @trpc/react-query package is now labelled "Classic" upstream.

npx create-trpc-appx@latest my-app                      # default
npx create-trpc-appx@latest my-app --example vite-react
npx create-trpc-appx@latest my-app --example nextjs-app

The template's own package.json decides which versions get installed. There is no second, hidden dependency list in the CLI.

Official tRPC examples

Any directory name from trpc/trpc/examples works too, and is fetched at scaffold time:

npx create-trpc-appx@latest my-app --example minimal
npx create-trpc-appx@latest my-app --example express-minimal
npx create-trpc-appx@latest my-app --example fastify-server

Note that the headline starters next-prisma-starter, next-prisma-todomvc, next-prisma-websockets-starter and kitchen-sink now live in their own trpc/examples-* repositories, so reach them by URL instead:

npx create-trpc-appx@latest my-app \
  --example https://github.com/trpc/examples-next-prisma-starter

Run examples from GitHub

run fetches an example into a cache directory and starts it, without creating a project you own. Use --example above if you want a project to keep.

# Short form plus an explicit subdirectory
npx create-trpc-appx@latest run trpc/trpc#main --example-path examples/minimal --prepare-only

# Full URL with the subdirectory in the path
npx create-trpc-appx@latest run https://github.com/trpc/trpc/tree/main/examples/minimal --prepare-only

# Drop --prepare-only to actually start it
npx create-trpc-appx@latest run trpc/trpc#main --example-path examples/express-minimal

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.

If the subdirectory you asked for is not in the repository, the command now fails with ERR_EXAMPLE_PATH instead of quietly preparing the repository root.

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).

If current dir has a runnable script → use it.
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
Otherwise, scan first two levels for runnable packages.

Troubleshooting

engines.node mismatch → use nvm/Volta to switch versions; this CLI needs Node 22.12+
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
ERR_EXAMPLE_PATH from run → the --example-path subdirectory is not in that repository at that branch
Could not locate an example named "..." → the name is not a directory in trpc/trpc/examples; the error lists the bundled templates, which always work offline

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:

npx create-trpc-appx@latest doctor

Security

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

Third-party archives are extracted with tar ^7.5.22, the first release line with no open advisories. Earlier 7.x releases, including the 7.5.7 that fixes GHSA-34x7-hfp2-rc4v alone, still carry others.

Development

npm ci
npm run build       # bundle to dist/ and copy templates
npm run typecheck   # tsc --noEmit
npm run lint        # eslint, zero warnings tolerated
npm test            # build, then unit + template contract tests
npm run test:smoke  # `run` subcommand against real GitHub repos (needs network)

# End-to-end against the PACKAGED artifact: npm pack, install the tarball into
# an empty directory, scaffold from that install, then build/run the result.
node tests/scaffold.test.mjs              # all three templates
node tests/scaffold.test.mjs nextjs-app   # just one

npm test is offline. npm run test:smoke and tests/scaffold.test.mjs reach the network; set GITHUB_TOKEN to avoid GitHub API rate limits.

tests/scaffold.test.mjs needs ports 2021 (default template) free.

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.