Skip to content
Source
Sign inSign up
TanStack/cli
Open History to see the last commit

README.md

152 lines6.6 KB

1# Create React App for TanStack Router
2​
3This CLI application builds Tanstack Router applications that are the functional equivalent of [Create React App](https://create-react-app.dev/).
4​
5To help accelerate the migration away from `create-react-app` we created the `create-tanstack-app` CLI which is a plug-n-play replacement for CRA.
6​
7## Quick Start
8​
9To maintain compatability with `create-react-app` you can build a new application by running:
10​
11| Command | Description |
12| --------------------------------------------------------------------------------- | ------------------------------------------------- |
13| `pnpm dlx create-tanstack-app@latest my-app` | Create a new app |
14| `pnpm dlx create-tanstack-app@latest my-app --template file-router` | Create a new file based app |
15| `pnpm dlx create-tanstack-app@latest my-app --template typescript` | Create a new TypeScript app using the Code Router |
16| `pnpm dlx create-tanstack-app@latest my-app --tailwind` | Deprecated compatibility flag (ignored) |
17| `pnpm dlx create-tanstack-app@latest my-app --framework solid` | Create a Solid app |
18| `pnpm dlx create-tanstack-app@latest my-app --framework solid --template file-router` | Create a Solid app with file-router |
19​
20If you don't specify a project name, the CLI will walk you through an interactive setup process:
21​
22```bash
23pnpm dlx create-tanstack-app@latest
24```
25​
26This will start an interactive CLI that guides you through the setup process, allowing you to choose:
27​
28- Project Name
29- Router Type (File-based or Code-based routing)
30- TypeScript support
31- Tailwind CSS integration
32- Package manager
33- Toolchain
34- Git initialization
35​
36## Command Line Options
37​
38You can also use command line flags to specify your preferences directly:
39​
40```bash
41pnpm dlx create-tanstack-app@latest my-app --template file-router --package-manager pnpm
42```
43​
44Available options:
45​
46- `--template <type>`: Choose between `file-router`, `typescript`, or `javascript`
47- `--tailwind` / `--no-tailwind`: Deprecated compatibility flags; accepted but ignored (Tailwind is always enabled)
48- `--package-manager`: Specify your preferred package manager (`npm`, `yarn`, `pnpm`, `bun`, or `deno`)
49- `--toolchain`: Specify your toolchain solution for formatting/linting (`biome`, `eslint`)
50- `--no-git`: Do not initialize a git repository
51- `--add-ons`: Enable add-on selection or specify add-ons to install
52​
53When using flags, the CLI will display which options were provided and only prompt for the remaining choices.
54​
55## Features
56​
57What you'll get is a Vite application that uses TanStack Router. All the files will still be in the same place as in CRA, but you'll get a fully functional Router setup under in `app/main.tsx`.
58​
59`create-tanstack-app` is everything you loved about CRA but implemented with modern tools and best practices, on top of the popular TanStack set of libraries. Which includes [@tanstack/react-query](https://tanstack.com/query/latest) and [@tanstack/react-router](https://tanstack.com/router/latest).
60​
61## Routing Options
62​
63### File Based Routing (Recommended)
64​
65File Based Routing is the default option when using the interactive CLI. The location of the home page will be `app/routes/index.tsx`. This approach provides a more intuitive and maintainable way to structure your routes.
66​
67To explicitly choose File Based Routing, use:
68​
69```bash
70pnpm dlx create-tanstack-app@latest my-app --template file-router
71```
72​
73### Code Based Routing
74​
75If you prefer traditional code-based routing, you can select it in the interactive CLI or specify it by using either the `typescript` or `javascript` template:
76​
77```bash
78pnpm dlx create-tanstack-app@latest my-app --template typescript
79```
80​
81## Additional Configuration
82​
83### TypeScript
84​
85- File Based Routing always uses TypeScript
86- For Code Based Routing, you can choose between TypeScript and JavaScript
87- Enable TypeScript explicitly with `--template typescript`
88​
89### Tailwind CSS
90​
91Tailwind CSS is always configured by default. `--tailwind` / `--no-tailwind` are accepted for compatibility but ignored.
92​
93### Package Manager
94​
95Choose your preferred package manager (`npm`, `bun`, `yarn`, `pnpm`, or `deno`) either through the interactive CLI or using the `--package-manager` flag.
96​
97Extensive documentation on using the TanStack Router, migrating to a File Base Routing approach, as well as integrating [@tanstack/react-query](https://tanstack.com/query/latest) and [@tanstack/store](https://tanstack.com/store/latest) can be found in the generated `README.md` for your project.
98​
99### Toolchain
100​
101Choose your preferred solution for formatting and linting either through the interactive CLI or using the `--toolchain` flag.
102​
103Setting this flag to `biome` will configure it as your toolchain of choice, adding a `biome.json` to the root of the project. Consult the [biome documentation](https://biomejs.dev/guides/getting-started/) for further customization.
104​
105Setting this flag to `eslint` will configure it as your toolchain of choice, adding an `eslint.config.js` and `prettier.config.js` to the root of the project, as well as a `.prettierignore` file. Consult the [eslint documentation](https://eslint.org/docs/latest/) and [prettier documentation](https://prettier.io/docs/) for further customization.
106​
107## Add-ons (experimental)
108​
109You can enable add-on selection:
110​
111```bash
112pnpm dlx create-tanstack-app@latest --add-ons
113```
114​
115This will prompt you to select the add-ons you want to enable during application creation.
116​
117You can enable specific add-ons directly by adding a comma separated list of add-on names to the `--add-ons` flag. For example:
118​
119```bash
120pnpm dlx create-tanstack-app@latest my-app --add-ons shadcn,tanstack-query
121```
122​
123You can get a list of all available add-ons by running:
124​
125```bash
126pnpm dlx create-tanstack-app@latest --list-add-ons
127```
128​
129This will display a list of all available add-ons for React that are compatible with the Code Router.
130​
131```bash
132pnpm dlx create-tanstack-app@latest --list-add-ons --framework solid --template file-router
133```
134​
135Will get you a list of all available add-ons for Solid that are compatible with the File Router.
136​
137## Agent Usage
138​
139The CLI no longer includes an MCP server. Use direct CLI introspection commands instead:
140​
141```bash
142pnpm dlx create-tanstack-app@latest --list-add-ons
143pnpm dlx create-tanstack-app@latest --addon-details tanstack-query
144```
145​
146# Contributing
147​
148Check out the [Contributing](CONTRIBUTING.md) guide.
149​
150# License
151​
152MIT