Skip to content

Commit c5bd0a3

Browse files
jherrjherr
committed
fix: merging in alpha
2 parents 09f8e95 + 56d09e5 commit c5bd0a3

File tree

640 files changed

+37519
-4309
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

640 files changed

+37519
-4309
lines changed

‎.cursor/mcp.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"mcpServers": {
3+
"nx-mcp": {
4+
"url": "http://localhost:9733/sse"
5+
}
6+
}
7+
}

‎.gitignore‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,14 @@ my-app
55
.DS_Store
66
**/node_modules
77
**/dist
8-
8+
.vinxi
9+
**/lib-dist
10+
**/api-server-dist
911
.vscode
1012

1113
.nx/cache
12-
.nx/workspace-data
14+
.nx/workspace-data
15+
16+
.content-collections
17+
18+
coverage

‎.husky/pre-commit‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
#!/usr/bin/env sh
2+
. "$(dirname -- "$0")/_/husky.sh"
3+
4+
pnpm build
5+
pnpm test

‎ARCHITECTURE.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
## Nomenclature
2+
3+
- `cta` - Create Tanstack Application
4+
- CTA Framework - A framework that supports the creation of a TanStack Application using a specific technology (e.g. React, Solid, Vue, etc.)
5+
- `code-router` - One of two _modes_ of TanStack Application. The other is `file-router`. The code router is when the applications routes are defined in code.
6+
- `file-router` - One of two _modes_ of TanStack Application. The other is `code-router`. The file router is when the applications routes are defined in files (usually in the `src/routes` directory).
7+
- `add-on` - A plugin that extends the capabilities of a TanStack Application (e.g. the `tanstack-query` add-on integrates TanStack Query into the application).
8+
- custom `add-on` - An externalized `add-on` contained in a single JSON file that can integate technologies that aren't covered with the built-in add-ons.
9+
- `starter` - An application template that is constructed from an existing CTA created application that has been modified to the customers needs. The advantage of a starter over a cloneable git repo is that when a starter is used the add-ons and project will be created using the latest version of the CTA framework and the add-ons. This reduces the versioning burden on the customer. This does come with a risk of potential breaking changes.
10+
11+
## CLI applications
12+
13+
- `create-tanstack` - The CLI application for creating a TanStack Application.
14+
- `create-start-app` - The CLI application for creating a TanStack Start Application.
15+
- `create-tsrouter-app` - The CLI application for creating a TanStack Router Application.
16+
17+
## Packages
18+
19+
- `@tanstack/cta-cli` - The command line interface for TanStack CTA.
20+
- `@tanstack/cta-engine` - The core engine that powers TanStack CTA.
21+
- `@tanstack/cta-ui` - The UI components for TanStack CTA.
22+
23+
## Frameworks
24+
25+
- `@tanstack/cta-frameworks-react-cra` - The React (Create React App) framework for TanStack CTA.
26+
- `@tanstack/cta-frameworks-solid` - The Solid framework for TanStack CTA.
27+
28+
## File Templates
29+
30+
The CTA system uses EJS to render the files into the final application.
31+
32+
Below are all of the variables that are available to the file templates.
33+
34+
| Variable | Description |
35+
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
36+
| `packageManager` | The package manager that is being used (e.g. `npm`, `yarn`, `pnpm`) |
37+
| `projectName` | The name of the project |
38+
| `typescript` | Boolean value that is `true` if TypeScript is being used, otherwise it is `false` |
39+
| `tailwind` | Boolean value that is `true` if Tailwind CSS is being used, otherwise it is `false` |
40+
| `js` | The file extension for files that do not include JSX. When in TypeScript mode it is `ts`. When in JavaScript mode it is `js`. |
41+
| `jsx` | The file extension for files that include JSX. When in TypeScript mode it is `tsx`. When in JavaScript mode it is `jsx`. |
42+
| `fileRouter` | Boolean value that is `true` if the file router is being used, otherwise it is `false` |
43+
| `codeRouter` | Boolean value that is `true` if the code router is being used, otherwise it is `false` |
44+
| `addOnEnabled` | An object that contains the enabled add-ons. The keys are the `id` values of the add-ons. For example, if the tanstack-query add-on is enabled the `addOnEnabled]['tanstack-query']` will be `true`. |
45+
| `addOns` | An array of the enabled add-on objects |
46+
| `integrations` | An array of the enabled integrations |
47+
| `routes` | An array containing all of the routes from all of the add-ons. (Used by the header and the `code-router` setup.) |
48+
| `getPackageManagerAddScript` | A function that returns the script to add a dependency to the project. |
49+
| `getPackageManagerRunScript` | A function that returns the script to run a command in the project. |
50+
| `relativePath` | A function that returns the relative path from the current file to the specified target file. |
51+
| `ignoreFile` | A function that if called will tell CTA to not include this file in the application. |

‎CONTRIBUTING.md‎

Lines changed: 67 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -13,24 +13,74 @@
1313
- Dependencies inside of the packages and examples are automatically linked together as local/dynamic dependencies.
1414
- Run the build
1515
- `pnpm build`
16-
- Build an example app with the builder. This is actually a little trick because if you build an app in the monorepo it will inherit the monorepo setup and won't work. So you need to have a temporary directory outside of the monorepo to create apps. An example test command command is below. The `-C` flag is used to the working directory of PNPM to the root of the CLI code, and the `--target-dir` flag is used to specify to the CLI the directory to create the app in.
17-
- `pnpm -C [root of the monorepo]/cli/create-tsrouter-app start --target-dir [temporary directory path]/app-js app-js`
18-
- Since you will probably be working on `./packages/cta-engine` a lot, you can run the following command to start the CLI in watch mode. After you have built the code at the root with `pnpm build`, you can run the following command to start the CLI in watch mode.
19-
- `cd ./packages/cta-engine && pnpm dev`
20-
- Run the `app-js` app just to make sure it works
21-
- Make changes to the code
22-
- Re-run `pnpm build` and `pnpm start` (in all its configurations) to make sure the changes work
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
2321
- Check your work and PR
2422

25-
# Testing combinations
23+
# Testing Add-ons and Starters
2624

27-
These must all product running applications that can be built (`pnpm build`) and tested (`pnpm test`).
25+
Create the add-on or starter using the CLI. Then serve it locally from the project directory using `npx static-server`.
2826

29-
| Command | Description |
30-
| -------------------------------------------------------- | ------------------------------------------------------------------ |
31-
| `pnpm start app-js` | Creates a JavaScript app |
32-
| `pnpm start app-ts --template typescript` | Creates a TypeScript app |
33-
| `pnpm start app-js-tw --tailwind` | Creates a JavaScript app with Tailwind CSS |
34-
| `pnpm start app-ts-tw --template typescript --tailwind` | Creates a TypeScript app with Tailwind CSS |
35-
| `pnpm start app-fr --template file-router` | Creates a TypeScript app with File Based Routing |
36-
| `pnpm start app-fr-tw --template file-router --tailwind` | Creates a TypeScript app with File Based Routing with Tailwind CSS |
27+
Then, when creating apps with add-ons:
28+
29+
```bash
30+
node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js app-js --add-ons http://localhost:9080/add-on.json
31+
```
32+
33+
And when creating apps with a starter:
34+
35+
```bash
36+
node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js app-js --starter http://localhost:9080/starter.json
37+
```
38+
39+
# Developing on the CTA UI
40+
41+
The 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.
42+
43+
## Starting the API Server
44+
45+
Let'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.
46+
47+
```bash
48+
CTA_DISABLE_UI=true node ../create-tsrouter-app/cli/create-tsrouter-app/dist/index.js --ui
49+
```
50+
51+
If this is working you will see the following output:
52+
53+
```
54+
Create TanStack API is running on http://localhost:8080
55+
```
56+
57+
Note 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.
58+
59+
Here is the same command for the `add` mode:
60+
61+
```bash
62+
CTA_DISABLE_UI=true node ../create-tsrouter-app/cli/create-tsrouter-app/dist/index.js add --ui
63+
```
64+
65+
## Starting the React App
66+
67+
Now that we have the API server running, we can start the React app in dev mode.
68+
69+
```bash
70+
cd packages/cta-ui
71+
pnpm dev:ui
72+
```
73+
74+
At this poing you should be able to navigate to `http://localhost:3000` and see the React app connected to the API server on `http://localhost:8080`.
75+
76+
## Running the Monorepo in Watch Mode
77+
78+
At the top level of the monorepo, run the following command to start the build in watch mode.
79+
80+
```bash
81+
pnpm dev
82+
```
83+
84+
This 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.)
85+
86+
This 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.

‎cli/create-start-app/package.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "create-start-app",
3-
"version": "0.10.0-alpha.25",
3+
"version": "0.10.0-alpha.31",
44
"description": "Tanstack Start Builder",
55
"bin": "./dist/index.js",
66
"type": "module",
@@ -28,7 +28,9 @@
2828
"license": "MIT",
2929
"packageManager": "[email protected]",
3030
"dependencies": {
31-
"@tanstack/cta-engine": "workspace:*"
31+
"@tanstack/cta-cli": "workspace:*",
32+
"@tanstack/cta-framework-react-cra": "workspace:*",
33+
"@tanstack/cta-framework-solid": "workspace:*"
3234
},
3335
"devDependencies": {
3436
"@types/node": "^22.13.4",

‎cli/create-start-app/src/index.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
#!/usr/bin/env node
2-
import { cli } from '@tanstack/cta-engine'
2+
import { cli } from '@tanstack/cta-cli'
3+
4+
import { register as registerReactCra } from '@tanstack/cta-framework-react-cra'
5+
import { register as registerSolid } from '@tanstack/cta-framework-solid'
6+
7+
registerReactCra()
8+
registerSolid()
39

410
cli({
511
name: 'create-start-app',

‎cli/create-tanstack/package.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "create-tanstack",
3-
"version": "0.10.0-alpha.25",
3+
"version": "0.10.0-alpha.31",
44
"description": "Tanstack Application Builder",
55
"bin": "./dist/index.js",
66
"type": "module",
@@ -28,7 +28,9 @@
2828
"license": "MIT",
2929
"packageManager": "[email protected]",
3030
"dependencies": {
31-
"@tanstack/cta-engine": "workspace:*"
31+
"@tanstack/cta-cli": "workspace:*",
32+
"@tanstack/cta-framework-react-cra": "workspace:*",
33+
"@tanstack/cta-framework-solid": "workspace:*"
3234
},
3335
"devDependencies": {
3436
"@types/node": "^22.13.4",

‎cli/create-tanstack/src/index.ts‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,14 @@
11
#!/usr/bin/env node
2-
import { cli } from '@tanstack/cta-engine'
2+
import { cli } from '@tanstack/cta-cli'
3+
4+
import { register as registerReactCra } from '@tanstack/cta-framework-react-cra'
5+
import { register as registerSolid } from '@tanstack/cta-framework-solid'
6+
7+
registerReactCra()
8+
registerSolid()
39

410
cli({
511
name: 'create-tanstack',
612
appName: 'TanStack',
13+
defaultTemplate: 'file-router',
714
})

‎cli/create-tsrouter-app/package.json‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "create-tsrouter-app",
3-
"version": "0.10.0-alpha.25",
3+
"version": "0.10.0-alpha.31",
44
"description": "Tanstack Application Builder",
55
"bin": "./dist/index.js",
66
"type": "module",
@@ -28,7 +28,9 @@
2828
"license": "MIT",
2929
"packageManager": "[email protected]",
3030
"dependencies": {
31-
"@tanstack/cta-engine": "workspace:*"
31+
"@tanstack/cta-cli": "workspace:*",
32+
"@tanstack/cta-framework-react-cra": "workspace:*",
33+
"@tanstack/cta-framework-solid": "workspace:*"
3234
},
3335
"devDependencies": {
3436
"@types/node": "^22.13.4",

0 commit comments

Comments
 (0)