Create start CLI

[timoconnellaus]

This discussion is to work through the requirements / ideas / approach for a CLI for creating a new tanstack start project

My thoughts are that the CLI should:

• work like astros cli - at the core it just handle some basic options name, folder, typescript support, etc
• allows you to choose a template to get started with. These could be synchronised with the stackblitz examples so there is no duplication

However, I think maybe there is a more composable approach - the cli could work like shadcn's cli. With this approach you would be able to create a plugin that can modify a tanstack start app. It would:

• modify / add files in standard folders (utils, routes, hooks, etc)
• be able to install dependencies that the plugin requires
• other plugins could be dependencies of a plugin - e.g. the tanstack query plugin would be a dependency to the convex plugin as convex utilises the query context
• plugins would be versioned and upgradable

[thomasballinger]

If this works it sounds great, potentially developers could add something after having developed for a while?

Taking adding Convex to an app as an example, this would require

• installing additional dependencies (sounds easy)
• writing files and directories (sounds easy, fail if these already exist)
• modifying app/routes/__root.tsx and app/router.tsx (interested in how these modifications would be defined, but doable with AST or regex — need to fail gracefully if the change can't be made)
• possibly add a demo page or modify routes/index.tsx

We could test running these plugin scripts at least on the bare bones starters, and possibly on apps that have had other plugins applied.

If this is too difficult the the choosing from a wizard to install a specific template seems hard to ignore (at Convex we maintain repo with lots of templates and use wacky git flows to keep them all updated) but it sure sounds nice to be able to maintain these as notional diffs.

[timoconnellaus]

This could be the answer https://plopjs.com/

[timoconnellaus]

Actually looks like maybe yeoman or possibly nx generators. Plop seems stale. Although I'm not sure if you can use nx generators without an nx workspace - I'm investigating that.

[timoconnellaus]

Questions:

• should vinxi deployment targets be include in the CLI?
• what would the default deployment target be? @tannerlinsley you should probably answer this one
• should we allow people to not use typescript?
• I think if typescript is chosen the strictness should be set as it's important to the router - is that correct?
• should we allow for the option to choose between file based and code based routing?
• should non tanstack-start package versions in templates be automatically kept up to date?
• which CLI tool should be used? I like strict-cli - it is typesafe and feels like a logical choice for the tanstack stack
• should the CLI allow for choosing the version of tanstack router / start to install? I think if the answer is yes then it should only be for a very basic template

Implementation:

• for prompts - @inquirer/prompts
• for cli - currently undecided. Question above ^^^^

General

• usage npx create tanstack@latest
• add documentation to website
• All prompts will have an associated CLI flag so you can run the CLI without being prompted
• Theme to match tanstack colors
• ascii palm tree and TANSTACK logo with gradient at top - animate it appearing. Will be nice to share on X
• shows the current version of the CLI at the top
• detects package manager being used and uses it for install step
• after the final step in the prompts, visuall indicate each of the steps being completed as they're done (creating folder, adding template, installing dependencies etc)
• Prompt Order:
  • directory
  • template
  • typescript
  • typescript strictness
  • install dependencies
  • git
• update to github workflow to run tests
• templates should have the versions updated as router / start is updated

Tests

• e2e: templates should include their own tests to ensure they're working correctly when a new version is deployed
• unit tests

Flags

• --hide-logo -l - hides the logo
• --silent -s - runs the cli without prompting - accepts any Y/N questoins automatically
• --install-dependencies -i - installs the dependencies after folder created
• --initiate-git -g - initiates git

Flags / Prompts

• directory
  • First positional arugment in CLI
  • Prompt
    • Where should the project be installed?
    • Default - two random words put together
  • Validations
    • folder doesn't exist
    • kebab case
    • more than one character
    • lower case
    • first character is alpha
  • Is used as the name for the project in the package.json
• deployment target
  • Flag: --deployment-target -d
  • Prompt: Deployment Target: select from list - default undecided
  • sets the deployment target in the app.config.ts
• Tailwind
  • when on - adds tailwind with postcss
  • Flag: --tailwind -t
  • Prompt: Tailwind: Yes / No
  • templates need to account for tailwind being on or off
• Template
  • Flag: --template -t
  • Prompt: Template - select from list. Defaults to starter (a simple example using tailwind to showcase some features)
  • Validations
    • template-name must exist when using flag

Inital Templates

• empty - bare bones template with an empty index route
• sample - has some sample files to see how tanstack works

[thomasballinger]

Here are my gut answers https://gist.github.com/thomasballinger/c703c32100d6bfdba15eac91cb9f15c1

[timoconnellaus]

Thanks @thomasballinger! I responded in the gist

[SeanCassiere]

should vinxi deployment targets be include in the CLI?

No, maybe just include a link to docs on the deployment guide. Possibly stuff this in the README.md?

what would the default deployment target be? @tannerlinsley you should probably answer this one

Currently, we are defaulting it to vercel (inside the defineConfig function) when one is not specified.

should we allow people to not use typescript?

TS all the way. Type-safe routing is a big selling point here.

I think if typescript is chosen the strictness should be set as it's important to the router - is that correct?

Strict as a MF.

should we allow for the option to choose between file based and code based routing?

We'll need to stick to file-based routing since Start needs the manifest in the generated route-tree.

should non tanstack-start package versions in templates be automatically kept up to date?

Yup. The base packages should be @tanstack/react-router and @tanstack/start. Everything else is optional.
That being said, should the devtools be included as a package then this would be a nice to have - https://github.com/SeanCassiere/nv-rental-clone/blob/master/src/components/router-devtools.tsx

which CLI tool should be used? I like strict-cli - it is typesafe and feels like a logical choice for the tanstack stack

No preference from my side.

should the CLI allow for choosing the version of tanstack router / start to install? I think if the answer is yes then it should only be for a very basic template

Do you mean the semver version? If so, then no.

[timoconnellaus]

I hadn't thought about devtools!

[AaronTan11]

Maybe I missed it but is there a PR already for the CLI?

[AaronTan11]

#2920

Well just when I was finding it haha.

X link for reach:
https://x.com/TimOConnellDev/status/1864168486056153447?t=ULo3Dg2UDRTineIiLNIcZw&s=19