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

CONTRIBUTING.md

106 lines3.6 KB

1# Contributing
2​
3- Clone the repo
4 - `gh repo clone TanStack/create-tsrouter-app`
5- Ensure `node` is installed
6 - https://nodejs.org/en/
7- Ensure `pnpm` is installed
8 - https://pnpm.io/installation
9 - Why? We use `pnpm` to manage workspace dependencies. It's easily the best monorepo/workspace experience available as of when this was written.
10- Install dependencies
11 - `pnpm install`
12 - This installs dependencies for all of the packages in the monorepo, even examples!
13 - Dependencies inside of the packages and examples are automatically linked together as local/dynamic dependencies.
14- Run the build
15 - `pnpm build`
16- Build an example app with the builder:
17 - `node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js app-js`
18 - Do not attempt to build an app within the monorepo because the dependencies will be hoisted into the monorepo.
19- Run `pnpm dev` at that top level to build everything in watch mode
20- Run `pnpm build` and `pnpm test` to make sure the changes work
21- Check your work and PR
22​
23# Testing Your Changes
24​
25When testing use `pnpm dev` at the top level of the `create-tsrouter-app` repo.
26​
27Then from a peer directory use:
28​
29```bash
30node ../create-tsrouter-app/cli/create-start-app/dist/index.js
31```
32​
33To test `create-start-app` (or any of the CLIs).
34​
35You can also do:
36​
37```bash
38npm_config_user_agent=pnpm node ../create-tsrouter-app/cli/create-start-app/dist/index.js
39```
40​
41If you want to specify a package manager.
42​
43# Testing Add-ons and Starters
44​
45Create the add-on or starter using the CLI. Then serve it locally from the project directory using `npx static-server`.
46​
47Then, when creating apps with add-ons:
48​
49```bash
50node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js app-js --add-ons http://localhost:9080/add-on.json
51```
52​
53And when creating apps with a starter:
54​
55```bash
56node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js app-js --starter http://localhost:9080/starter.json
57```
58​
59# Developing on the CTA UI
60​
61The CTA UI is somewhat tricky to develop on because it's both a web server and a React app. You need to run the CLI in "API" model and then the React app in dev mode, as well as the whole monorepo in watch mode.
62​
63## Starting the API Server
64​
65Let's start off with how to run the CLI in "API" mode. Here we are running the CLI in an empty directory in app creation mode.
66​
67```bash
68CTA_DISABLE_UI=true node ../create-tsrouter-app/cli/create-tsrouter-app/dist/index.js --ui
69```
70​
71If this is working you will see the following output:
72​
73```
74Create TanStack API is running on http://localhost:8080
75```
76​
77Note that it say "Create TanStack **API**" and not "Create TanStack **App**". This is important. This means that the CLI is providing API endpoints, but **not** serving the static build files of the React app.
78​
79Here is the same command for the `add` mode:
80​
81```bash
82CTA_DISABLE_UI=true node ../create-tsrouter-app/cli/create-tsrouter-app/dist/index.js add --ui
83```
84​
85## Starting the React App
86​
87Now that we have the API server running, we can start the React app in dev mode.
88​
89```bash
90cd packages/cta-ui
91pnpm dev:ui
92```
93​
94Navigate to `http://localhost:3000` and see the React app connected to the API server on `http://localhost:8080`.
95​
96## Running the Monorepo in Watch Mode
97​
98At the top level of the monorepo, run the following command to start the build in watch mode.
99​
100```bash
101pnpm dev
102```
103​
104This will build the monorepo and watch for changes in any of the libraries. (It will **not** build changes for the React app within the `cta-ui` package.)
105​
106This is important because you might need to change API endpoints in the CTA library, or in the engine. If you do make those kinds of changes then the you will need to re-run the CLI in "API" mode to pick up the changes.