@tanstack/cta-framework-react-cra 0.27.1 → 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/add-ons/strapi/README.md

@@ -0,0 +1,14 @@
+## Setting up Strapi
+
+The current setup shows an example of how to use Strapi with an articles collection which is part of the example structure & data.
+
+- Create a local running copy of the strapi admin
+
+```bash
+pnpx create-strapi@latest my-strapi-project
+cd my-strapi-project
+pnpm dev
+```
+
+- Login and publish the example articles to see them on the strapi demo page.
+- Set the `VITE_STRAPI_URL` environment variable in your `.env.local`. (For local it should be http://localhost:1337/api)

package/add-ons/strapi/assets/_dot_env.local.append

@@ -0,0 +1,2 @@
+# Strapi configuration
+VITE_STRAPI_URL="http://localhost:1337/api"

package/add-ons/strapi/assets/src/lib/strapiClient.ts

@@ -0,0 +1,7 @@
+import { strapi } from "@strapi/client";
+
+export const strapiClient = strapi({
+  baseURL: import.meta.env.VITE_STRAPI_URL,
+});
+
+export const articles = strapiClient.collection("articles");

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

@@ -0,0 +1,66 @@
+import { articles } from '@/lib/strapiClient'
+import { createFileRoute, Link } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/demo/strapi')({
+  component: RouteComponent,
+  loader: async () => {
+    const { data: strapiArticles } = await articles.find()
+    return strapiArticles
+  },
+})
+
+function RouteComponent() {
+  const strapiArticles = Route.useLoaderData()
+
+  return (
+    <div className="min-h-screen bg-gradient-to-b from-slate-900 via-slate-800 to-slate-900 p-8">
+      <div className="max-w-7xl mx-auto">
+        <h1 className="text-4xl font-bold mb-8 text-white">
+          <span className="bg-gradient-to-r from-cyan-400 to-blue-400 bg-clip-text text-transparent">
+            Strapi
+          </span>{' '}
+          <span className="text-gray-300">Articles</span>
+        </h1>
+
+        {strapiArticles && strapiArticles.length > 0 ? (
+          <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
+            {strapiArticles.map((article) => (
+              <Link
+                key={article.id}
+                to="/demo/strapi/$articleId"
+                params={{ articleId: article.documentId }}
+                className="block"
+              >
+                <article className="bg-slate-800/50 backdrop-blur-sm border border-slate-700 rounded-xl p-6 hover:border-cyan-500/50 transition-all duration-300 hover:shadow-lg hover:shadow-cyan-500/10 cursor-pointer h-full">
+                  <h2 className="text-xl font-semibold text-white mb-3">
+                    {article.title || 'Untitled'}
+                  </h2>
+
+                  {article.description && (
+                    <p className="text-gray-400 mb-4 leading-relaxed">
+                      {article.description}
+                    </p>
+                  )}
+
+                  {article.content && (
+                    <p className="text-gray-400 line-clamp-3 leading-relaxed">
+                      {article.content}
+                    </p>
+                  )}
+
+                  {article.createdAt && (
+                    <p className="text-sm text-cyan-400/70 mt-4">
+                      {new Date(article.createdAt).toLocaleDateString()}
+                    </p>
+                  )}
+                </article>
+              </Link>
+            ))}
+          </div>
+        ) : (
+          <p className="text-gray-400">No articles found.</p>
+        )}
+      </div>
+    </div>
+  )
+}

package/add-ons/strapi/assets/src/routes/demo/strapi_.$articleId.tsx

@@ -0,0 +1,78 @@
+import { articles } from '@/lib/strapiClient'
+import { createFileRoute, Link } from '@tanstack/react-router'
+
+export const Route = createFileRoute('/demo/strapi_/$articleId')({
+  component: RouteComponent,
+  loader: async ({ params }) => {
+    const { data: article } = await articles.findOne(params.articleId)
+    return article
+  },
+})
+
+function RouteComponent() {
+  const article = Route.useLoaderData()
+
+  return (
+    <div className="min-h-screen bg-gradient-to-b from-slate-900 via-slate-800 to-slate-900 p-8">
+      <div className="max-w-4xl mx-auto">
+        <Link
+          to="/demo/strapi"
+          className="inline-flex items-center text-cyan-400 hover:text-cyan-300 mb-6 transition-colors"
+        >
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            className="h-5 w-5 mr-2"
+            viewBox="0 0 20 20"
+            fill="currentColor"
+          >
+            <path
+              fillRule="evenodd"
+              d="M9.707 16.707a1 1 0 01-1.414 0l-6-6a1 1 0 010-1.414l6-6a1 1 0 011.414 1.414L5.414 9H17a1 1 0 110 2H5.414l4.293 4.293a1 1 0 010 1.414z"
+              clipRule="evenodd"
+            />
+          </svg>
+          Back to Articles
+        </Link>
+
+        <article className="bg-slate-800/50 backdrop-blur-sm border border-slate-700 rounded-xl p-8">
+          <h1 className="text-4xl font-bold text-white mb-4">
+            {article?.title || 'Untitled'}
+          </h1>
+
+          {article?.createdAt && (
+            <p className="text-sm text-cyan-400/70 mb-6">
+              Published on{' '}
+              {new Date(article?.createdAt).toLocaleDateString('en-US', {
+                year: 'numeric',
+                month: 'long',
+                day: 'numeric',
+              })}
+            </p>
+          )}
+
+          {article?.description && (
+            <div className="mb-6">
+              <h2 className="text-xl font-semibold text-gray-300 mb-3">
+                Description
+              </h2>
+              <p className="text-gray-400 leading-relaxed">
+                {article?.description}
+              </p>
+            </div>
+          )}
+
+          {article?.content && (
+            <div>
+              <h2 className="text-xl font-semibold text-gray-300 mb-3">
+                Content
+              </h2>
+              <div className="text-gray-400 leading-relaxed whitespace-pre-wrap">
+                {article?.content}
+              </div>
+            </div>
+          )}
+        </article>
+      </div>
+    </div>
+  )
+}

package/add-ons/strapi/info.json

@@ -0,0 +1,18 @@
+{
+  "name": "Strapi",
+  "description": "Use the Strapi CMS to manage your content.",
+  "link": "https://strapi.io/",
+  "phase": "add-on",
+  "type": "add-on",
+  "modes": [
+    "file-router"
+  ],
+  "routes": [
+    {
+      "url": "/demo/strapi",
+      "name": "Strapi",
+      "path": "src/routes/demo.strapi.tsx",
+      "jsName": "StrapiDemo"
+    }
+  ]
+}

package/add-ons/strapi/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@strapi/client": "^1.5.0"
+  }
+}

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

@@ -0,0 +1,8 @@
+<svg width="600" height="600" viewBox="0 0 600 600" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0 208C0 109.948 0 60.9218 30.4609 30.4609C60.9218 0 109.948 0 208 0H392C490.052 0 539.078 0 569.539 30.4609C600 60.9218 600 109.948 600 208V392C600 490.052 600 539.078 569.539 569.539C539.078 600 490.052 600 392 600H208C109.948 600 60.9218 600 30.4609 569.539C0 539.078 0 490.052 0 392V208Z" fill="#4945FF"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M414 182H212V285H315V388H418V186C418 183.791 416.209 182 414 182Z" fill="white"/>
+<rect x="311" y="285" width="4" height="4" fill="white"/>
+<path d="M212 285H311C313.209 285 315 286.791 315 289V388H216C213.791 388 212 386.209 212 384V285Z" fill="#9593FF"/>
+<path d="M315 388H418L318.414 487.586C317.154 488.846 315 487.953 315 486.172V388Z" fill="#9593FF"/>
+<path d="M212 285H113.828C112.046 285 111.154 282.846 112.414 281.586L212 182V285Z" fill="#9593FF"/>
+</svg>

package/add-ons/workos/README.md

@@ -0,0 +1,3 @@
+## Setting up WorkOS
+
+- Set the `VITE_WORKOS_CLIENT_ID` in your `.env.local`.

package/add-ons/workos/assets/_dot_env.local.append

@@ -0,0 +1,4 @@
+VITE_WORKOS_CLIENT_ID=
+
+# This should be your Custom Authentication Domain in production
+VITE_WORKOS_API_HOSTNAME=api.workos.com

package/add-ons/workos/assets/src/components/workos-user.tsx

@@ -0,0 +1,41 @@
+import { useAuth } from '@workos-inc/authkit-react'
+
+export default function SignInButton({ large }: { large?: boolean }) {
+  const { user, isLoading, signIn, signOut } = useAuth()
+
+  const buttonClasses = `${
+    large ? 'px-6 py-3 text-base' : 'px-4 py-2 text-sm'
+  } bg-blue-600 hover:bg-blue-700 text-white font-medium rounded transition-colors disabled:opacity-50 disabled:cursor-not-allowed`
+
+  if (user) {
+    return (
+      <div className="flex flex-col gap-3">
+        <div className="flex items-center gap-2">
+          {user.profilePictureUrl && (
+            <img
+              src={user.profilePictureUrl}
+              alt={`Avatar of ${user.firstName} ${user.lastName}`}
+              className="w-10 h-10 rounded-full"
+            />
+          )}
+          {user.firstName} {user.lastName}
+        </div>
+        <button onClick={() => signOut()} className={buttonClasses}>
+          Sign Out
+        </button>
+      </div>
+    )
+  }
+
+  return (
+    <button
+      onClick={() => {
+        signIn()
+      }}
+      className={buttonClasses}
+      disabled={isLoading}
+    >
+      Sign In {large && 'with AuthKit'}
+    </button>
+  )
+}

package/add-ons/workos/assets/src/hooks/useUser.tsx

@@ -0,0 +1,23 @@
+import { useEffect } from "react";
+import { useAuth } from "@workos-inc/authkit-react";
+import { useLocation } from "@tanstack/react-router";
+
+type UserOrNull = ReturnType<typeof useAuth>["user"];
+
+// redirects to the sign-in page if the user is not signed in
+export const useUser = (): UserOrNull => {
+  const { user, isLoading, signIn } = useAuth();
+  const location = useLocation();
+
+  useEffect(() => {
+    if (!isLoading && !user) {
+      signIn({
+        state: { returnTo: location.pathname },
+      });
+    } else {
+      console.log(user);
+    }
+  }, [isLoading, user]);
+
+  return user;
+};

package/add-ons/workos/assets/src/integrations/workos/provider.tsx

@@ -0,0 +1,34 @@
+import { AuthKitProvider } from '@workos-inc/authkit-react'
+import { useNavigate } from '@tanstack/react-router'
+
+const VITE_WORKOS_CLIENT_ID = import.meta.env.VITE_WORKOS_CLIENT_ID
+if (!VITE_WORKOS_CLIENT_ID) {
+  throw new Error('Add your WorkOS Client ID to the .env.local file')
+}
+
+const VITE_WORKOS_API_HOSTNAME = import.meta.env.VITE_WORKOS_API_HOSTNAME
+if (!VITE_WORKOS_API_HOSTNAME) {
+  throw new Error('Add your WorkOS API Hostname to the .env.local file')
+}
+
+export default function AppWorkOSProvider({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const navigate = useNavigate()
+
+  return (
+    <AuthKitProvider
+      clientId={VITE_WORKOS_CLIENT_ID}
+      apiHostname={VITE_WORKOS_API_HOSTNAME}
+      onRedirectCallback={({ state }) => {
+        if (state?.returnTo) {
+          navigate(state.returnTo)
+        }
+      }}
+    >
+      {children}
+    </AuthKitProvider>
+  )
+}

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

@@ -0,0 +1,109 @@
+import { createFileRoute } from '@tanstack/react-router'
+import { useAuth } from '@workos-inc/authkit-react'
+
+export const Route = createFileRoute('/demo/workos')({
+  ssr: false,
+  component: App,
+})
+
+function App() {
+  const { user, isLoading, signIn, signOut } = useAuth()
+
+  if (isLoading) {
+    return (
+      <div className="min-h-screen bg-gradient-to-br from-gray-900 via-gray-800 to-gray-900 flex items-center justify-center p-4">
+        <div className="bg-gray-800/50 backdrop-blur-sm rounded-2xl shadow-2xl p-8 w-full max-w-md border border-gray-700/50">
+          <p className="text-gray-400 text-center">Loading...</p>
+        </div>
+      </div>
+    )
+  }
+
+  if (user) {
+    return (
+      <div className="min-h-screen bg-gradient-to-br from-gray-900 via-gray-800 to-gray-900 flex items-center justify-center p-4">
+        <div className="bg-gray-800/50 backdrop-blur-sm rounded-2xl shadow-2xl p-8 w-full max-w-md border border-gray-700/50">
+          <h1 className="text-2xl font-bold text-white mb-6 text-center">
+            User Profile
+          </h1>
+
+          <div className="space-y-6">
+            {/* Profile Picture */}
+            {user.profilePictureUrl && (
+              <div className="flex justify-center">
+                <img
+                  src={user.profilePictureUrl}
+                  alt={`Avatar of ${user.firstName} ${user.lastName}`}
+                  className="w-24 h-24 rounded-full border-4 border-gray-700 shadow-lg"
+                />
+              </div>
+            )}
+
+            {/* User Information */}
+            <div className="space-y-4">
+              <div className="bg-gray-700/30 rounded-lg p-4 border border-gray-600/30">
+                <label className="text-gray-400 text-sm font-medium block mb-1">
+                  First Name
+                </label>
+                <p className="text-white text-lg">{user.firstName || 'N/A'}</p>
+              </div>
+
+              <div className="bg-gray-700/30 rounded-lg p-4 border border-gray-600/30">
+                <label className="text-gray-400 text-sm font-medium block mb-1">
+                  Last Name
+                </label>
+                <p className="text-white text-lg">{user.lastName || 'N/A'}</p>
+              </div>
+
+              <div className="bg-gray-700/30 rounded-lg p-4 border border-gray-600/30">
+                <label className="text-gray-400 text-sm font-medium block mb-1">
+                  Email
+                </label>
+                <p className="text-white text-lg break-all">
+                  {user.email || 'N/A'}
+                </p>
+              </div>
+
+              <div className="bg-gray-700/30 rounded-lg p-4 border border-gray-600/30">
+                <label className="text-gray-400 text-sm font-medium block mb-1">
+                  User ID
+                </label>
+                <p className="text-gray-300 text-sm font-mono break-all">
+                  {user.id || 'N/A'}
+                </p>
+              </div>
+            </div>
+
+            {/* Sign Out Button */}
+            <button
+              onClick={() => signOut()}
+              className="w-full bg-blue-600 hover:bg-blue-700 text-white font-medium py-3 px-6 rounded-lg transition-colors shadow-lg hover:shadow-xl"
+            >
+              Sign Out
+            </button>
+          </div>
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="min-h-screen bg-gradient-to-br from-gray-900 via-gray-800 to-gray-900 flex items-center justify-center p-4">
+      <div className="bg-gray-800/50 backdrop-blur-sm rounded-2xl shadow-2xl p-8 w-full max-w-md border border-gray-700/50">
+        <h1 className="text-2xl font-bold text-white mb-6 text-center">
+          WorkOS Authentication
+        </h1>
+        <p className="text-gray-400 text-center mb-6">
+          Sign in to view your profile information
+        </p>
+        <button
+          onClick={() => signIn()}
+          disabled={isLoading}
+          className="w-full bg-blue-600 hover:bg-blue-700 text-white font-medium py-3 px-6 rounded-lg transition-colors shadow-lg hover:shadow-xl disabled:opacity-50 disabled:cursor-not-allowed"
+        >
+          Sign In with AuthKit
+        </button>
+      </div>
+    </div>
+  )
+}

package/add-ons/workos/info.json

@@ -0,0 +1,30 @@
+{
+  "name": "WorkOS",
+  "description": "Add WorkOS authentication to your application.",
+  "phase": "add-on",
+  "modes": ["file-router"],
+  "type": "add-on",
+  "link": "https://workos.com",
+  "tailwind": true,
+  "routes": [
+    {
+      "icon": "CircleUserRound",
+      "url": "/demo/workos",
+      "name": "WorkOS",
+      "path": "src/routes/demo.workos.tsx",
+      "jsName": "WorkOSDemo"
+    }
+  ],
+  "integrations": [
+    {
+      "type": "header-user",
+      "jsName": "WorkOSHeader",
+      "path": "src/components/workos-user.tsx"
+    },
+    {
+      "type": "provider",
+      "jsName": "WorkOSProvider",
+      "path": "src/integrations/workos/provider.tsx"
+    }
+  ]
+}

package/add-ons/workos/package.json

@@ -0,0 +1,6 @@
+{
+  "dependencies": {
+    "@workos-inc/authkit-react": "^0.13.0",
+    "zod": "^4.1.11"
+  }
+}

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

@@ -0,0 +1,5 @@
+<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+<ellipse cx="16.0003" cy="16" rx="4.99998" ry="5" fill="#9785FF" style="fill:#9785FF;fill:color(display-p3 0.5922 0.5216 1.0000);fill-opacity:1;"/>
+<path d="M25.0091 27.8382C25.4345 28.2636 25.3918 28.9679 24.8919 29.3027C22.3488 31.0062 19.2899 31.9997 15.9991 31.9997C12.7082 31.9997 9.64935 31.0062 7.10616 29.3027C6.60633 28.9679 6.56361 28.2636 6.98901 27.8382L10.6429 24.1843C10.9732 23.854 11.4855 23.8019 11.9012 24.0148C13.1303 24.6445 14.5232 24.9997 15.9991 24.9997C17.4749 24.9997 18.8678 24.6445 20.0969 24.0148C20.5126 23.8019 21.0249 23.854 21.3552 24.1843L25.0091 27.8382Z" fill="#9785FF" style="fill:#9785FF;fill:color(display-p3 0.5922 0.5216 1.0000);fill-opacity:1;"/>
+<path opacity="0.6" d="M24.8928 2.697C25.3926 3.0318 25.4353 3.73609 25.0099 4.16149L21.356 7.81544C21.0258 8.14569 20.5134 8.19785 20.0978 7.98491C18.8687 7.35525 17.4758 7 15.9999 7C11.0294 7 6.99997 11.0294 6.99997 16C6.99997 17.4759 7.35522 18.8688 7.98488 20.0979C8.19782 20.5136 8.14565 21.0259 7.81541 21.3561L4.16147 25.0101C3.73607 25.4355 3.03178 25.3927 2.69698 24.8929C0.993522 22.3497 0 19.2909 0 16C0 7.16344 7.16341 0 15.9999 0C19.2908 0 22.3496 0.993529 24.8928 2.697Z" fill="#9785FF" style="fill:#9785FF;fill:color(display-p3 0.5922 0.5216 1.0000);fill-opacity:1;"/>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/cta-framework-react-cra",
-  "version": "0.27.1",
+  "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.27.1"
+    "@tanstack/cta-engine": "0.29.0"
   },
   "devDependencies": {
     "@types/node": "^24.6.0",