@tanstack/cta-framework-react-cra 0.28.0 → 0.29.0

package/ADD-ON-AUTHORING.md

@@ -193,3 +193,171 @@ If you don't want a header link you can omit the `url` and `name` properties.
 You **MUST** specify routes in the `info.json` file if your add-on supports the `code-router` mode. This is because the `code-routers` setup needs to import the routes in order to add them to the router.
 
 By convension you should prefix demo routes with `demo` to make it clear that they are demo routes so they can be easily identified and removed.
+
+# Add-on Options
+
+The CTA framework supports configurable add-ons through an options system that allows users to customize add-on behavior during creation. This enables more flexible and reusable add-ons that can adapt to different use cases.
+
+## Overview
+
+Add-on options allow developers to create configurable add-ons where users can select from predefined choices that affect:
+
+- Which files are included in the generated project
+- Template variable values used during file generation
+- Package dependencies that get installed
+- Configuration file contents
+
+## Configuration Format
+
+Options are defined in the `info.json` file using the following schema:
+
+```json
+{
+  "name": "My Add-on",
+  "description": "A configurable add-on",
+  "options": {
+    "optionName": {
+      "type": "select",
+      "label": "Display Label",
+      "description": "Optional description shown to users",
+      "default": "defaultValue",
+      "options": [
+        { "value": "option1", "label": "Option 1" },
+        { "value": "option2", "label": "Option 2" }
+      ]
+    }
+  }
+}
+```
+
+### Option Types
+
+#### Select Options
+
+The `select` type allows users to choose from a predefined list of options:
+
+```json
+"database": {
+  "type": "select",
+  "label": "Database Provider",
+  "description": "Choose your database provider",
+  "default": "postgres",
+  "options": [
+    { "value": "postgres", "label": "PostgreSQL" },
+    { "value": "mysql", "label": "MySQL" },
+    { "value": "sqlite", "label": "SQLite" }
+  ]
+}
+```
+
+**Properties:**
+
+- `type`: Must be `"select"`
+- `label`: Display text shown to users
+- `description`: Optional help text
+- `default`: Default value that must match one of the option values
+- `options`: Array of value/label pairs
+
+## Template Usage
+
+Option values are available in EJS templates through the `addOnOption` variable:
+
+```ejs
+<!-- Access option value -->
+<% if (addOnOption.myAddOnId.database === 'postgres') { %>
+  PostgreSQL specific code
+<% } %>
+
+<!-- Use option value in output -->
+const driver = '<%= addOnOption.myAddOnId.database %>'
+```
+
+The structure is: `addOnOption.{addOnId}.{optionName}`
+
+### Template Conditional Logic
+
+Within template files, use `ignoreFile()` to skip file generation:
+
+```ejs
+<% if (addOnOption.prisma.database !== 'postgres') { ignoreFile() } %>
+import { PrismaClient } from '@prisma/client'
+
+declare global {
+  var __prisma: PrismaClient | undefined
+}
+
+export const prisma = globalThis.__prisma || new PrismaClient()
+
+if (process.env.NODE_ENV !== 'production') {
+  globalThis.__prisma = prisma
+}
+```
+
+## Complete Example: Prisma Add-on
+
+Here's how the Prisma add-on implements configurable database support:
+
+### Examples
+
+Configuration in `info.json`:
+
+```json
+{
+  "name": "Prisma ORM",
+  "description": "Add Prisma ORM with configurable database support to your application.",
+  "options": {
+    "database": {
+      "type": "select",
+      "label": "Database Provider",
+      "description": "Choose your database provider",
+      "default": "postgres",
+      "options": [
+        { "value": "postgres", "label": "PostgreSQL" },
+        { "value": "mysql", "label": "MySQL" },
+        { "value": "sqlite", "label": "SQLite" }
+      ]
+    }
+  }
+}
+```
+
+Code in `package.json.ejs`:
+
+```ejs
+{
+  "prisma": "^6.16.3",
+  "@prisma/client": "^6.16.3"<% if (addOnOption.prisma.database === 'postgres') { %>,
+  "pg": "^8.11.0",
+  "@types/pg": "^8.10.0"<% } else if (addOnOption.prisma.database === 'mysql') { %>,
+  "mysql2": "^3.6.0"<% } else if (addOnOption.prisma.database === 'sqlite') { %><% } %>
+}
+```
+
+## CLI Usage
+
+### Interactive Mode
+
+When using the CLI interactively, users are prompted for each option:
+
+```bash
+create-tsrouter-app my-app
+# User selects Prisma add-on
+# CLI prompts: "Prisma ORM: Database Provider" with options
+```
+
+### Non-Interactive Mode
+
+Options can be specified via JSON configuration:
+
+```bash
+create-tsrouter-app my-app --add-ons prisma --add-on-config '{"prisma":{"database":"mysql"}}'
+```
+
+## Best Practices
+
+1. **Use descriptive labels** - Make option purposes clear to users
+2. **Provide sensible defaults** - Choose the most common use case
+3. **Group related files** - Use consistent prefixing for option-specific files
+4. **Document options** - Include descriptions to help users understand choices
+5. **Test all combinations** - Ensure each option value generates working code
+6. **Use validation** - The system validates options against the schema automatically

package/add-ons/prisma/assets/_dot_env.local.append.ejs

@@ -0,0 +1,7 @@
+<% if (addOnOption.prisma.database === 'postgres') { %>
+# Database URL for PostgreSQL
+DATABASE_URL="postgresql://username:password@localhost:5432/mydb"<% } else if (addOnOption.prisma.database === 'mysql') { %>
+# Database URL for MySQL
+DATABASE_URL="mysql://username:password@localhost:3306/mydb"<% } else if (addOnOption.prisma.database === 'sqlite') { %>
+# Database URL for SQLite
+DATABASE_URL="file:./dev.db"<% } %>

package/add-ons/prisma/assets/public/prisma.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 256 310" width="256" height="310" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path fill="#fff" d="M254.313 235.519L148 9.749A17.063 17.063 0 00133.473.037a16.87 16.87 0 00-15.533 8.052L2.633 194.848a17.465 17.465 0 00.193 18.747L59.2 300.896a18.13 18.13 0 0020.363 7.489l163.599-48.392a17.929 17.929 0 0011.26-9.722 17.542 17.542 0 00-.101-14.76l-.008.008zm-23.802 9.683l-138.823 41.05c-4.235 1.26-8.3-2.411-7.419-6.685l49.598-237.484c.927-4.443 7.063-5.147 9.003-1.035l91.814 194.973a6.63 6.63 0 01-4.18 9.18h.007z"/></svg>

package/add-ons/prisma/assets/schema.prisma.ejs

@@ -0,0 +1,14 @@
+generator client {
+  provider = "prisma-client-js"
+}
+
+datasource db {
+  provider = "<%= addOnOption.prisma.database === "postgres" ? "postgresql" : addOnOption.prisma.database %>"
+  url      = env("DATABASE_URL")
+}
+
+model Todo {
+  id        Int      @id @default(autoincrement())
+  title     String
+  createdAt DateTime @default(now())
+}

package/add-ons/prisma/assets/seed.ts

@@ -0,0 +1,30 @@
+import { PrismaClient } from '@prisma/client'
+
+const prisma = new PrismaClient()
+
+async function main() {
+  console.log('🌱 Seeding database...')
+
+  // Clear existing todos
+  await prisma.todo.deleteMany()
+
+  // Create example todos
+  const todos = await prisma.todo.createMany({
+    data: [
+      { title: 'Buy groceries' },
+      { title: 'Read a book' },
+      { title: 'Workout' },
+    ],
+  })
+
+  console.log(`✅ Created ${todos.count} todos`)
+}
+
+main()
+  .catch((e) => {
+    console.error('❌ Error seeding database:', e)
+    process.exit(1)
+  })
+  .finally(async () => {
+    await prisma.$disconnect()
+  })

package/add-ons/prisma/assets/src/db.ts

@@ -0,0 +1,11 @@
+import { PrismaClient } from '@prisma/client'
+
+declare global {
+  var __prisma: PrismaClient | undefined
+}
+
+export const prisma = globalThis.__prisma || new PrismaClient()
+
+if (process.env.NODE_ENV !== 'production') {
+  globalThis.__prisma = prisma
+}

package/add-ons/prisma/assets/src/routes/demo/prisma.tsx

@@ -0,0 +1,186 @@
+import { createFileRoute, useRouter } from '@tanstack/react-router'
+import { createServerFn } from '@tanstack/react-start'
+import { prisma } from '@/db'
+
+const getTodos = createServerFn({
+  method: 'GET',
+}).handler(async () => {
+  return await prisma.todo.findMany({
+    orderBy: { createdAt: 'desc' },
+  })
+})
+
+const createTodo = createServerFn({
+  method: 'POST',
+})
+  .inputValidator((data: { title: string }) => data)
+  .handler(async ({ data }) => {
+    return await prisma.todo.create({
+      data,
+    })
+  })
+
+export const Route = createFileRoute('/demo/prisma')({
+  component: DemoPrisma,
+  loader: async () => await getTodos(),
+})
+
+function DemoPrisma() {
+  const router = useRouter()
+  const todos = Route.useLoaderData()
+
+  const handleSubmit = async (e: React.FormEvent<HTMLFormElement>) => {
+    e.preventDefault()
+    const formData = new FormData(e.target as HTMLFormElement)
+    const title = formData.get('title') as string
+
+    if (!title) return
+
+    try {
+      await createTodo({ data: { title } })
+      router.invalidate()
+      ;(e.target as HTMLFormElement).reset()
+    } catch (error) {
+      console.error('Failed to create todo:', error)
+    }
+  }
+
+  return (
+    <div
+      className="flex items-center justify-center min-h-screen p-4 text-white"
+      style={{
+        background:
+          'linear-gradient(135deg, #0c1a2b 0%, #1a2332 50%, #16202e 100%)',
+      }}
+    >
+      <div
+        className="w-full max-w-2xl p-8 rounded-xl shadow-2xl border border-white/10"
+        style={{
+          background:
+            'linear-gradient(135deg, rgba(22, 32, 46, 0.95) 0%, rgba(12, 26, 43, 0.95) 100%)',
+          backdropFilter: 'blur(10px)',
+        }}
+      >
+        <div
+          className="flex items-center justify-center gap-4 mb-8 p-4 rounded-lg"
+          style={{
+            background:
+              'linear-gradient(90deg, rgba(93, 103, 227, 0.1) 0%, rgba(139, 92, 246, 0.1) 100%)',
+            border: '1px solid rgba(93, 103, 227, 0.2)',
+          }}
+        >
+          <div className="relative group">
+            <div className="absolute -inset-2 bg-gradient-to-r from-indigo-500 via-purple-500 to-indigo-500 rounded-lg blur-lg opacity-60 group-hover:opacity-100 transition duration-500"></div>
+            <div className="relative bg-gradient-to-br from-indigo-600 to-purple-600 p-3 rounded-lg">
+              <img
+                src="/prisma.svg"
+                alt="Prisma Logo"
+                className="w-8 h-8 transform group-hover:scale-110 transition-transform duration-300"
+              />
+            </div>
+          </div>
+          <h1 className="text-3xl font-bold bg-gradient-to-r from-indigo-300 via-purple-300 to-indigo-300 text-transparent bg-clip-text">
+            Prisma Database Demo
+          </h1>
+        </div>
+
+        <h2 className="text-2xl font-bold mb-4 text-indigo-200">Todos</h2>
+
+        <ul className="space-y-3 mb-6">
+          {todos.map((todo) => (
+            <li
+              key={todo.id}
+              className="rounded-lg p-4 shadow-md border transition-all hover:scale-[1.02] cursor-pointer group"
+              style={{
+                background:
+                  'linear-gradient(135deg, rgba(93, 103, 227, 0.15) 0%, rgba(139, 92, 246, 0.15) 100%)',
+                borderColor: 'rgba(93, 103, 227, 0.3)',
+              }}
+            >
+              <div className="flex items-center justify-between">
+                <span className="text-lg font-medium text-white group-hover:text-indigo-200 transition-colors">
+                  {todo.title}
+                </span>
+                <span className="text-xs text-indigo-300/70">#{todo.id}</span>
+              </div>
+            </li>
+          ))}
+          {todos.length === 0 && (
+            <li className="text-center py-8 text-indigo-300/70">
+              No todos yet. Create one below!
+            </li>
+          )}
+        </ul>
+
+        <form onSubmit={handleSubmit} className="flex gap-2">
+          <input
+            type="text"
+            name="title"
+            placeholder="Add a new todo..."
+            className="flex-1 px-4 py-3 rounded-lg border focus:outline-none focus:ring-2 transition-all text-white placeholder-indigo-300/50"
+            style={{
+              background: 'rgba(93, 103, 227, 0.1)',
+              borderColor: 'rgba(93, 103, 227, 0.3)',
+              focusRing: 'rgba(93, 103, 227, 0.5)',
+            }}
+          />
+          <button
+            type="submit"
+            className="px-6 py-3 font-semibold rounded-lg shadow-lg transition-all duration-200 hover:shadow-xl hover:scale-105 active:scale-95 whitespace-nowrap"
+            style={{
+              background: 'linear-gradient(135deg, #5d67e3 0%, #8b5cf6 100%)',
+              color: 'white',
+            }}
+          >
+            Add Todo
+          </button>
+        </form>
+
+        <div
+          className="mt-8 p-6 rounded-lg border"
+          style={{
+            background: 'rgba(93, 103, 227, 0.05)',
+            borderColor: 'rgba(93, 103, 227, 0.2)',
+          }}
+        >
+          <h3 className="text-lg font-semibold mb-2 text-indigo-200">
+            Powered by Prisma ORM
+          </h3>
+          <p className="text-sm text-indigo-300/80 mb-4">
+            Next-generation ORM for Node.js & TypeScript with PostgreSQL
+          </p>
+          <div className="space-y-2 text-sm">
+            <p className="text-indigo-200 font-medium">Setup Instructions:</p>
+            <ol className="list-decimal list-inside space-y-2 text-indigo-300/80">
+              <li>
+                Configure your{' '}
+                <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
+                  DATABASE_URL
+                </code>{' '}
+                in .env.local
+              </li>
+              <li>
+                Run:{' '}
+                <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
+                  npx prisma generate
+                </code>
+              </li>
+              <li>
+                Run:{' '}
+                <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
+                  npx prisma db push
+                </code>
+              </li>
+              <li>
+                Optional:{' '}
+                <code className="px-2 py-1 rounded bg-black/30 text-purple-300">
+                  npx prisma studio
+                </code>
+              </li>
+            </ol>
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/add-ons/prisma/info.json

@@ -0,0 +1,32 @@
+{
+  "name": "Prisma",
+  "description": "Add Prisma Postgres, or Prisma ORM with other DBs to your application.",
+  "phase": "add-on",
+  "type": "add-on",
+  "link": "https://www.prisma.io/",
+  "modes": ["file-router"],
+  "dependsOn": ["start"],
+  "postInitSpecialSteps": ["post-init-script"],
+  "options": {
+    "database": {
+      "type": "select",
+      "label": "Database Provider",
+      "description": "Choose your database provider",
+      "default": "postgres",
+      "options": [
+        { "value": "postgres", "label": "Prisma PostgreSQL" },
+        { "value": "sqlite", "label": "SQLite" },
+        { "value": "mysql", "label": "MySQL" }
+      ]
+    }
+  },
+  "routes": [
+    {
+      "icon": "Database",
+      "url": "/demo/prisma",
+      "name": "Prisma",
+      "path": "src/routes/demo/prisma.tsx",
+      "jsName": "DemoPrisma"
+    }
+  ]
+}

package/add-ons/prisma/package.json.ejs

@@ -0,0 +1,27 @@
+{
+  "dependencies": {
+    "prisma": "^6.16.3",
+    "@prisma/client": "^6.16.3"<% if (addOnOption.prisma.database === 'postgres') { %>,
+    "pg": "^8.11.0"<% } %><% if (addOnOption.prisma.database === 'mysql') { %>,
+    "mysql2": "^3.6.0"<% } %>
+  },
+  "devDependencies": {
+    "dotenv-cli": "^10.0.0",
+    "ts-node": "^10.9.2",
+    <% if (addOnOption.prisma.database === 'postgres') { %>
+    "@types/pg": "^8.10.0"<% } %><% if (addOnOption.prisma.database === 'mysql') { %>
+    "@types/mysql2": "^3.6.0"<% } %><% if (addOnOption.prisma.database === 'sqlite') { %>
+    "@types/better-sqlite3": "^7.6.0"<% } %>
+  },
+  "scripts": {<% if (addOnOption.prisma.database === 'postgres') { %>
+    "post-cta-init": "npx create-db@latest",<% } %>
+    "db:generate": "dotenv -e .env.local -- prisma generate",
+    "db:push": "dotenv -e .env.local -- prisma db push",
+    "db:migrate": "dotenv -e .env.local -- prisma migrate dev",
+    "db:studio": "dotenv -e .env.local -- prisma studio",
+    "db:seed": "dotenv -e .env.local -- prisma db seed"
+  },
+  "prisma": {
+    "seed": "ts-node seed.ts"
+  }
+}

package/add-ons/prisma/small-logo.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 256 310" width="256" height="310" xmlns="http://www.w3.org/2000/svg" preserveAspectRatio="xMidYMid"><path fill="#000" d="M254.313 235.519L148 9.749A17.063 17.063 0 00133.473.037a16.87 16.87 0 00-15.533 8.052L2.633 194.848a17.465 17.465 0 00.193 18.747L59.2 300.896a18.13 18.13 0 0020.363 7.489l163.599-48.392a17.929 17.929 0 0011.26-9.722 17.542 17.542 0 00-.101-14.76l-.008.008zm-23.802 9.683l-138.823 41.05c-4.235 1.26-8.3-2.411-7.419-6.685l49.598-237.484c.927-4.443 7.063-5.147 9.003-1.035l91.814 194.973a6.63 6.63 0 01-4.18 9.18h.007z"/></svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cta-framework-react-cra",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "CTA Framework for React (Create React App)",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
   "author": "Jack Herrington <jherr@pobox.com>",
   "license": "MIT",
   "dependencies": {
-    "@tanstack/cta-engine": "0.28.0"
+    "@tanstack/cta-engine": "0.29.0"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",