fix: merging in alpha

Author: jherr

.cursor/mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcpServers": {
+    "nx-mcp": {
+      "url": "http://localhost:9733/sse"
+    }
+  }
+}

.gitignore

@@ -5,8 +5,14 @@ my-app
 .DS_Store
 **/node_modules
 **/dist
-
+.vinxi
+**/lib-dist
+**/api-server-dist
 .vscode
 
 .nx/cache
-.nx/workspace-data
+.nx/workspace-data
+
+.content-collections
+
+coverage

.husky/pre-commit

@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+pnpm build
+pnpm test

ARCHITECTURE.md

@@ -0,0 +1,51 @@
+## Nomenclature
+
+- `cta` - Create Tanstack Application
+- CTA Framework - A framework that supports the creation of a TanStack Application using a specific technology (e.g. React, Solid, Vue, etc.)
+- `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.
+- `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).
+- `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).
+- 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.
+- `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.
+
+## CLI applications
+
+- `create-tanstack` - The CLI application for creating a TanStack Application.
+- `create-start-app` - The CLI application for creating a TanStack Start Application.
+- `create-tsrouter-app` - The CLI application for creating a TanStack Router Application.
+
+## Packages
+
+- `@tanstack/cta-cli` - The command line interface for TanStack CTA.
+- `@tanstack/cta-engine` - The core engine that powers TanStack CTA.
+- `@tanstack/cta-ui` - The UI components for TanStack CTA.
+
+## Frameworks
+
+- `@tanstack/cta-frameworks-react-cra` - The React (Create React App) framework for TanStack CTA.
+- `@tanstack/cta-frameworks-solid` - The Solid framework for TanStack CTA.
+
+## File Templates
+
+The CTA system uses EJS to render the files into the final application.
+
+Below are all of the variables that are available to the file templates.
+
+| Variable                     | Description                                                                                                                                                                                          |
+| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `packageManager`             | The package manager that is being used (e.g. `npm`, `yarn`, `pnpm`)                                                                                                                                  |
+| `projectName`                | The name of the project                                                                                                                                                                              |
+| `typescript`                 | Boolean value that is `true` if TypeScript is being used, otherwise it is `false`                                                                                                                    |
+| `tailwind`                   | Boolean value that is `true` if Tailwind CSS is being used, otherwise it is `false`                                                                                                                  |
+| `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`.                                                                        |
+| `jsx`                        | The file extension for files that include JSX. When in TypeScript mode it is `tsx`. When in JavaScript mode it is `jsx`.                                                                             |
+| `fileRouter`                 | Boolean value that is `true` if the file router is being used, otherwise it is `false`                                                                                                               |
+| `codeRouter`                 | Boolean value that is `true` if the code router is being used, otherwise it is `false`                                                                                                               |
+| `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`. |
+| `addOns`                     | An array of the enabled add-on objects                                                                                                                                                               |
+| `integrations`               | An array of the enabled integrations                                                                                                                                                                 |
+| `routes`                     | An array containing all of the routes from all of the add-ons. (Used by the header and the `code-router` setup.)                                                                                     |
+| `getPackageManagerAddScript` | A function that returns the script to add a dependency to the project.                                                                                                                               |
+| `getPackageManagerRunScript` | A function that returns the script to run a command in the project.                                                                                                                                  |
+| `relativePath`               | A function that returns the relative path from the current file to the specified target file.                                                                                                        |
+| `ignoreFile`                 | A function that if called will tell CTA to not include this file in the application.                                                                                                                 |

CONTRIBUTING.md

@@ -13,24 +13,74 @@
   - Dependencies inside of the packages and examples are automatically linked together as local/dynamic dependencies.
 - Run the build
   - `pnpm build`
-- 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.
-  - `pnpm -C [root of the monorepo]/cli/create-tsrouter-app start --target-dir [temporary directory path]/app-js app-js`
-- 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.
-  - `cd ./packages/cta-engine && pnpm dev`
-- Run the `app-js` app just to make sure it works
-- Make changes to the code
-  - Re-run `pnpm build` and `pnpm start` (in all its configurations) to make sure the changes work
+- Build an example app with the builder:
+  - `node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js app-js`
+  - Do not attempt to build an app within the monorepo because the dependencies will be hoisted into the monorepo.
+- Run `pnpm dev` at that top level to build everything in watch mode
+- Run `pnpm build` and `pnpm test` to make sure the changes work
 - Check your work and PR
 
-# Testing combinations
+# Testing Add-ons and Starters
 
-These must all product running applications that can be built (`pnpm build`) and tested (`pnpm test`).
+Create the add-on or starter using the CLI. Then serve it locally from the project directory using `npx static-server`.
 
-| Command                                                  | Description                                                        |
-| -------------------------------------------------------- | ------------------------------------------------------------------ |
-| `pnpm start app-js`                                      | Creates a JavaScript app                                           |
-| `pnpm start app-ts --template typescript`                | Creates a TypeScript app                                           |
-| `pnpm start app-js-tw --tailwind`                        | Creates a JavaScript app with Tailwind CSS                         |
-| `pnpm start app-ts-tw --template typescript --tailwind`  | Creates a TypeScript app with Tailwind CSS                         |
-| `pnpm start app-fr --template file-router`               | Creates a TypeScript app with File Based Routing                   |
-| `pnpm start app-fr-tw --template file-router --tailwind` | Creates a TypeScript app with File Based Routing with Tailwind CSS |
+Then, when creating apps with add-ons:
+
+```bash
+node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js app-js --add-ons http://localhost:9080/add-on.json
+```
+
+And when creating apps with a starter:
+
+```bash
+node [root of the monorepo]/cli/create-tsrouter-app/dist/index.js app-js --starter http://localhost:9080/starter.json
+```
+
+# Developing on the CTA UI
+
+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.
+
+## Starting the API Server
+
+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.
+
+```bash
+CTA_DISABLE_UI=true node ../create-tsrouter-app/cli/create-tsrouter-app/dist/index.js --ui
+```
+
+If this is working you will see the following output:
+
+```
+Create TanStack API is running on http://localhost:8080
+```
+
+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.
+
+Here is the same command for the `add` mode:
+
+```bash
+CTA_DISABLE_UI=true node ../create-tsrouter-app/cli/create-tsrouter-app/dist/index.js add --ui
+```
+
+## Starting the React App
+
+Now that we have the API server running, we can start the React app in dev mode.
+
+```bash
+cd packages/cta-ui
+pnpm dev:ui
+```
+
+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`.
+
+## Running the Monorepo in Watch Mode
+
+At the top level of the monorepo, run the following command to start the build in watch mode.
+
+```bash
+pnpm dev
+```
+
+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.)
+
+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

@@ -1,6 +1,6 @@
 {
   "name": "create-start-app",
-  "version": "0.10.0-alpha.25",
+  "version": "0.10.0-alpha.31",
   "description": "Tanstack Start Builder",
   "bin": "./dist/index.js",
   "type": "module",
@@ -28,7 +28,9 @@
   "license": "MIT",
   "packageManager": "[email protected]",
   "dependencies": {
-    "@tanstack/cta-engine": "workspace:*"
+    "@tanstack/cta-cli": "workspace:*",
+    "@tanstack/cta-framework-react-cra": "workspace:*",
+    "@tanstack/cta-framework-solid": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^22.13.4",

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

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
-import { cli } from '@tanstack/cta-engine'
+import { cli } from '@tanstack/cta-cli'
+
+import { register as registerReactCra } from '@tanstack/cta-framework-react-cra'
+import { register as registerSolid } from '@tanstack/cta-framework-solid'
+
+registerReactCra()
+registerSolid()
 
 cli({
   name: 'create-start-app',

cli/create-tanstack/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tanstack",
-  "version": "0.10.0-alpha.25",
+  "version": "0.10.0-alpha.31",
   "description": "Tanstack Application Builder",
   "bin": "./dist/index.js",
   "type": "module",
@@ -28,7 +28,9 @@
   "license": "MIT",
   "packageManager": "[email protected]",
   "dependencies": {
-    "@tanstack/cta-engine": "workspace:*"
+    "@tanstack/cta-cli": "workspace:*",
+    "@tanstack/cta-framework-react-cra": "workspace:*",
+    "@tanstack/cta-framework-solid": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^22.13.4",

cli/create-tanstack/src/index.ts

@@ -1,7 +1,14 @@
 #!/usr/bin/env node
-import { cli } from '@tanstack/cta-engine'
+import { cli } from '@tanstack/cta-cli'
+
+import { register as registerReactCra } from '@tanstack/cta-framework-react-cra'
+import { register as registerSolid } from '@tanstack/cta-framework-solid'
+
+registerReactCra()
+registerSolid()
 
 cli({
   name: 'create-tanstack',
   appName: 'TanStack',
+  defaultTemplate: 'file-router',
 })

cli/create-tsrouter-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-tsrouter-app",
-  "version": "0.10.0-alpha.25",
+  "version": "0.10.0-alpha.31",
   "description": "Tanstack Application Builder",
   "bin": "./dist/index.js",
   "type": "module",
@@ -28,7 +28,9 @@
   "license": "MIT",
   "packageManager": "[email protected]",
   "dependencies": {
-    "@tanstack/cta-engine": "workspace:*"
+    "@tanstack/cta-cli": "workspace:*",
+    "@tanstack/cta-framework-react-cra": "workspace:*",
+    "@tanstack/cta-framework-solid": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^22.13.4",

cli/create-tsrouter-app/src/index.ts

@@ -1,5 +1,11 @@
 #!/usr/bin/env node
-import { cli } from '@tanstack/cta-engine'
+import { cli } from '@tanstack/cta-cli'
+
+import { register as registerReactCra } from '@tanstack/cta-framework-react-cra'
+import { register as registerSolid } from '@tanstack/cta-framework-solid'
+
+registerReactCra()
+registerSolid()
 
 cli({
   name: 'create-tsrouter-app',

examples/react-cra/blog-starter/.cta.json

@@ -0,0 +1,12 @@
+{
+  "projectName": "blog-example",
+  "targetDir": "/Users/jherr/projects/cta/new-examples/blog-example",
+  "mode": "file-router",
+  "typescript": true,
+  "tailwind": true,
+  "packageManager": "pnpm",
+  "git": true,
+  "version": 1,
+  "framework": "react-cra",
+  "chosenAddOns": ["shadcn", "start"]
+}

packages/cta-engine/templates/react/add-on/shadcn/assets/_dot_cursorrules.append renamed to examples/react-cra/blog-starter/.cursorrules

@@ -0,0 +1,8 @@
+node_modules
+.DS_Store
+dist
+dist-ssr
+*.local
+.output
+.vinxi
+.content-collections