feat: priority order for add-ons

jherr · jherr · commit a5d90d94bbb2 · 2025-10-11T16:26:42.000-07:00
diff --git a/frameworks/react-cra/add-ons/clerk/info.json b/frameworks/react-cra/add-ons/clerk/info.json
@@ -4,6 +4,7 @@
   "phase": "add-on",
   "modes": ["file-router"],
   "type": "add-on",
+  "priority": 150,
   "link": "https://clerk.com",
   "tailwind": true,
   "routes": [
diff --git a/frameworks/react-cra/add-ons/convex/info.json b/frameworks/react-cra/add-ons/convex/info.json
@@ -4,6 +4,7 @@
   "link": "https://convex.dev",
   "phase": "add-on",
   "type": "add-on",
+  "priority": 140,
   "modes": ["file-router"],
   "routes": [
     {
diff --git a/frameworks/react-cra/add-ons/db/info.json b/frameworks/react-cra/add-ons/db/info.json
@@ -3,6 +3,7 @@
   "description": "TanStack DB",
   "phase": "add-on",
   "type": "add-on",
+  "priority": 50,
   "modes": ["file-router"],
   "link": "https://tanstack.com/db/latest",
   "dependsOn": ["tanstack-query", "start"],
diff --git a/frameworks/react-cra/add-ons/form/info.json b/frameworks/react-cra/add-ons/form/info.json
@@ -3,6 +3,7 @@
   "description": "TanStack Form",
   "phase": "add-on",
   "type": "add-on",
+  "priority": 46,
   "modes": ["file-router", "code-router"],
   "link": "https://tanstack.com/form/latest",
   "routes": [
diff --git a/frameworks/react-cra/add-ons/mcp/info.json b/frameworks/react-cra/add-ons/mcp/info.json
@@ -5,6 +5,7 @@
   "link": "https://mcp.dev",
   "modes": ["file-router"],
   "type": "add-on",
+  "priority": 42,
   "warning": "MCP is still in development and may change significantly or not be compatible with other add-ons.\nThe MCP implementation does not support authentication.",
   "routes": [
     {
diff --git a/frameworks/react-cra/add-ons/module-federation/info.json b/frameworks/react-cra/add-ons/module-federation/info.json
@@ -4,5 +4,6 @@
   "phase": "add-on",
   "modes": ["code-router"],
   "link": "https://module-federation.io/",
-  "type": "add-on"
+  "type": "add-on",
+  "priority": 38
 }
diff --git a/frameworks/react-cra/add-ons/neon/info.json b/frameworks/react-cra/add-ons/neon/info.json
@@ -4,6 +4,7 @@
   "link": "https://neon.com",
   "phase": "add-on",
   "type": "add-on",
+  "priority": 170,
   "modes": ["file-router"],
   "routes": [
     {
diff --git a/frameworks/react-cra/add-ons/oRPC/info.json b/frameworks/react-cra/add-ons/oRPC/info.json
@@ -6,6 +6,7 @@
   "link": "https://orpc.unnoq.com/",
   "dependsOn": ["tanstack-query", "start"],
   "type": "add-on",
+  "priority": 34,
   "routes": [
     {
       "icon": "Network",
diff --git a/frameworks/react-cra/add-ons/prisma/info.json b/frameworks/react-cra/add-ons/prisma/info.json
@@ -3,6 +3,7 @@
   "description": "Add Prisma Postgres, or Prisma ORM with other DBs to your application.",
   "phase": "add-on",
   "type": "add-on",
+  "priority": 120,
   "link": "https://www.prisma.io/",
   "modes": ["file-router"],
   "dependsOn": ["start"],
diff --git a/frameworks/react-cra/add-ons/sentry/info.json b/frameworks/react-cra/add-ons/sentry/info.json
@@ -5,6 +5,7 @@
   "link": "https://sentry.com/",
   "modes": ["file-router"],
   "type": "add-on",
+  "priority": 130,
   "routes": [
     {
       "url": "/demo/sentry/testing",
diff --git a/frameworks/react-cra/add-ons/shadcn/info.json b/frameworks/react-cra/add-ons/shadcn/info.json
@@ -4,5 +4,6 @@
   "phase": "add-on",
   "modes": ["file-router", "code-router"],
   "link": "https://ui.shadcn.com/",
-  "type": "add-on"
+  "type": "add-on",
+  "priority": 30
 }
diff --git a/frameworks/react-cra/add-ons/start/info.json b/frameworks/react-cra/add-ons/start/info.json
@@ -5,6 +5,7 @@
   "link": "https://tanstack.com/start/latest",
   "modes": ["file-router"],
   "type": "add-on",
+  "priority": 26,
   "routes": [
     {
       "icon": "SquareFunction",
diff --git a/frameworks/react-cra/add-ons/store/info.json b/frameworks/react-cra/add-ons/store/info.json
@@ -4,6 +4,7 @@
   "phase": "add-on",
   "link": "https://tanstack.com/store/latest",
   "type": "add-on",
+  "priority": 22,
   "modes": ["file-router", "code-router"],
   "routes": [
     {
diff --git a/frameworks/react-cra/add-ons/storybook/info.json b/frameworks/react-cra/add-ons/storybook/info.json
@@ -5,6 +5,7 @@
   "modes": ["file-router"],
   "link": "https://storybook.js.org/",
   "type": "add-on",
+  "priority": 18,
   "routes": [
     {
       "icon": "BookOpen",
diff --git a/frameworks/react-cra/add-ons/strapi/info.json b/frameworks/react-cra/add-ons/strapi/info.json
@@ -4,9 +4,8 @@
   "link": "https://strapi.io/",
   "phase": "add-on",
   "type": "add-on",
-  "modes": [
-    "file-router"
-  ],
+  "priority": 110,
+  "modes": ["file-router"],
   "routes": [
     {
       "url": "/demo/strapi",
@@ -15,4 +14,4 @@
       "jsName": "StrapiDemo"
     }
   ]
-}
+}
diff --git a/frameworks/react-cra/add-ons/t3env/info.json b/frameworks/react-cra/add-ons/t3env/info.json
@@ -3,6 +3,7 @@
   "description": "Add type safety to your environment variables",
   "phase": "add-on",
   "type": "add-on",
+  "priority": 29,
   "link": "https://github.com/t3-oss/t3-env",
   "modes": ["file-router", "code-router"]
 }
diff --git a/frameworks/react-cra/add-ons/tRPC/info.json b/frameworks/react-cra/add-ons/tRPC/info.json
@@ -6,6 +6,7 @@
   "link": "https://trpc.io/",
   "dependsOn": ["tanstack-query", "start"],
   "type": "add-on",
+  "priority": 27,
   "routes": [
     {
       "icon": "Network",
diff --git a/frameworks/react-cra/add-ons/table/info.json b/frameworks/react-cra/add-ons/table/info.json
@@ -5,6 +5,7 @@
   "modes": ["file-router", "code-router"],
   "link": "https://tanstack.com/table/latest",
   "type": "add-on",
+  "priority": 28,
   "routes": [
     {
       "icon": "Table",
diff --git a/frameworks/react-cra/add-ons/tanstack-query/info.json b/frameworks/react-cra/add-ons/tanstack-query/info.json
@@ -4,6 +4,7 @@
   "phase": "add-on",
   "modes": ["file-router", "code-router"],
   "type": "add-on",
+  "priority": 10,
   "link": "https://tanstack.com/query/latest",
   "routes": [
     {
diff --git a/frameworks/react-cra/add-ons/workos/info.json b/frameworks/react-cra/add-ons/workos/info.json
@@ -4,6 +4,7 @@
   "phase": "add-on",
   "modes": ["file-router"],
   "type": "add-on",
+  "priority": 160,
   "link": "https://workos.com",
   "tailwind": true,
   "routes": [
diff --git a/frameworks/react-cra/examples/tanchat/info.json b/frameworks/react-cra/examples/tanchat/info.json
@@ -4,6 +4,7 @@
   "phase": "example",
   "modes": ["file-router"],
   "type": "example",
+  "priority": 10,
   "link": "",
   "routes": [
     {
diff --git a/frameworks/react-cra/hosts/cloudflare/info.json b/frameworks/react-cra/hosts/cloudflare/info.json
@@ -5,6 +5,7 @@
   "phase": "add-on",
   "modes": ["file-router", "code-router"],
   "type": "host",
+  "priority": 200,
   "integrations": [
     {
       "type": "vite-plugin",
diff --git a/frameworks/react-cra/hosts/netlify/info.json b/frameworks/react-cra/hosts/netlify/info.json
@@ -5,6 +5,7 @@
   "phase": "add-on",
   "modes": ["file-router", "code-router"],
   "type": "host",
+  "priority": 180,
   "integrations": [
     {
       "type": "vite-plugin",
diff --git a/frameworks/react-cra/hosts/nitro/info.json b/frameworks/react-cra/hosts/nitro/info.json
@@ -5,6 +5,7 @@
   "phase": "add-on",
   "modes": ["file-router", "code-router"],
   "type": "host",
+  "priority": 0,
   "integrations": [
     {
       "type": "vite-plugin",
diff --git a/frameworks/react-cra/toolchains/biome/info.json b/frameworks/react-cra/toolchains/biome/info.json
@@ -3,6 +3,7 @@
   "description": "Biome toolchain support.",
   "phase": "setup",
   "type": "toolchain",
+  "priority": 2,
   "modes": ["code-router", "file-router"],
   "link": "https://biomejs.dev"
 }
diff --git a/frameworks/react-cra/toolchains/eslint/info.json b/frameworks/react-cra/toolchains/eslint/info.json
@@ -3,6 +3,7 @@
   "description": "ESLint + Prettier toolchain support.",
   "phase": "setup",
   "type": "toolchain",
+  "priority": 0,
   "modes": ["code-router", "file-router"],
   "link": "https://eslint.org"
 }
diff --git a/packages/cta-engine/src/add-ons.ts b/packages/cta-engine/src/add-ons.ts
@@ -3,7 +3,14 @@ import { loadRemoteAddOn } from './custom-add-ons/add-on.js'
 import type { AddOn, Framework } from './types.js'
 
 export function getAllAddOns(framework: Framework, mode: string): Array<AddOn> {
-  return framework.getAddOns().filter((a) => a.modes.includes(mode))
+  return framework
+    .getAddOns()
+    .filter((a) => a.modes.includes(mode))
+    .sort((a, b) => {
+      const aPriority = a.priority ?? 0
+      const bPriority = b.priority ?? 0
+      return bPriority - aPriority // Higher priority first
+    })
 }
 
 // Turn the list of chosen add-on IDs into a final list of add-ons by resolving dependencies
@@ -49,10 +56,10 @@ function loadAddOn(addOn: AddOn): AddOn {
 }
 
 export function populateAddOnOptionsDefaults(
-  chosenAddOns: Array<AddOn>
+  chosenAddOns: Array<AddOn>,
 ): Record<string, Record<string, any>> {
   const addOnOptions: Record<string, Record<string, any>> = {}
-  
+
   for (const addOn of chosenAddOns) {
     if (addOn.options) {
       const defaults: Record<string, any> = {}
@@ -62,6 +69,6 @@ export function populateAddOnOptionsDefaults(
       addOnOptions[addOn.id] = defaults
     }
   }
-  
+
   return addOnOptions
 }
diff --git a/packages/cta-engine/src/types.ts b/packages/cta-engine/src/types.ts
@@ -38,6 +38,7 @@ export const AddOnBaseSchema = z.object({
   license: z.string().optional(),
   warning: z.string().optional(),
   type: z.enum(['add-on', 'example', 'starter', 'toolchain', 'host']),
+  priority: z.number().optional(),
   command: z
     .object({
       command: z.string(),
diff --git a/packages/cta-engine/tests/add-ons.test.ts b/packages/cta-engine/tests/add-ons.test.ts
@@ -28,6 +28,79 @@ describe('getAllAddOns', () => {
     expect(addOns.length).toEqual(1)
     expect(addOns[0].id).toEqual('add-on-1')
   })
+
+  it('should sort add-ons by priority (higher priority first)', () => {
+    const addOns = getAllAddOns(
+      {
+        id: 'react-cra',
+        getAddOns: () => [
+          {
+            id: 'low-priority',
+            description: 'Low Priority',
+            modes: ['file-router'],
+            priority: 10,
+          } as AddOn,
+          {
+            id: 'high-priority',
+            description: 'High Priority',
+            modes: ['file-router'],
+            priority: 100,
+          } as AddOn,
+          {
+            id: 'no-priority',
+            description: 'No Priority (defaults to 0)',
+            modes: ['file-router'],
+          } as AddOn,
+          {
+            id: 'medium-priority',
+            description: 'Medium Priority',
+            modes: ['file-router'],
+            priority: 50,
+          } as AddOn,
+        ],
+      } as Framework,
+      'file-router',
+    )
+
+    expect(addOns.length).toEqual(4)
+    expect(addOns[0].id).toEqual('high-priority')
+    expect(addOns[1].id).toEqual('medium-priority')
+    expect(addOns[2].id).toEqual('low-priority')
+    expect(addOns[3].id).toEqual('no-priority')
+  })
+
+  it('should filter by mode and then sort by priority', () => {
+    const addOns = getAllAddOns(
+      {
+        id: 'react-cra',
+        getAddOns: () => [
+          {
+            id: 'file-router-low',
+            description: 'File Router Low',
+            modes: ['file-router'],
+            priority: 20,
+          } as AddOn,
+          {
+            id: 'code-router-high',
+            description: 'Code Router High (should be filtered out)',
+            modes: ['code-router'],
+            priority: 200,
+          } as AddOn,
+          {
+            id: 'file-router-high',
+            description: 'File Router High',
+            modes: ['file-router'],
+            priority: 100,
+          } as AddOn,
+        ],
+      } as Framework,
+      'file-router',
+    )
+
+    expect(addOns.length).toEqual(2)
+    expect(addOns[0].id).toEqual('file-router-high')
+    expect(addOns[1].id).toEqual('file-router-low')
+  })
 })
 
 describe('finalizeAddOns', () => {
diff --git a/packages/cta-ui-base/src/components/sidebar-items/add-ons.tsx b/packages/cta-ui-base/src/components/sidebar-items/add-ons.tsx
@@ -27,7 +27,12 @@ export default function SelectedAddOns() {
 
   const sortedAddOns = useMemo(() => {
     return availableAddOns.sort((a, b) => {
-      return a.name.localeCompare(b.name)
+      const aPriority = a.priority ?? 0
+      const bPriority = b.priority ?? 0
+      if (bPriority !== aPriority) {
+        return bPriority - aPriority // Higher priority first
+      }
+      return a.name.localeCompare(b.name) // Fallback to alphabetical
     })
   }, [availableAddOns])
 
diff --git a/packages/cta-ui-base/src/types.d.ts b/packages/cta-ui-base/src/types.d.ts
@@ -1,4 +1,8 @@
-import type { StatusStepType, AddOnOption, AddOnOptions } from '@tanstack/cta-engine'
+import type {
+  StatusStepType,
+  AddOnOption,
+  AddOnOptions,
+} from '@tanstack/cta-engine'
 
 export type ApplicationMode = 'add' | 'setup' | 'none'
 
@@ -35,6 +39,7 @@ export type AddOnInfo = {
   type: 'add-on' | 'example' | 'starter' | 'toolchain' | 'host'
   modes: Array<string>
   smallLogo?: string
+  priority?: number
   logo?: string
   link: string
   dependsOn?: Array<string>
diff --git a/packages/cta-ui/lib/engine-handling/generate-initial-payload.ts b/packages/cta-ui/lib/engine-handling/generate-initial-payload.ts
@@ -28,6 +28,7 @@ function convertAddOnToAddOnInfo(addOn: AddOn): AddOnInfo {
   return {
     id: addOn.id,
     name: addOn.name,
+    priority: addOn.priority,
     description: addOn.description,
     modes: addOn.modes as Array<'code-router' | 'file-router'>,
     type: addOn.type,
diff --git a/packages/cta-ui/lib/types.d.ts b/packages/cta-ui/lib/types.d.ts
@@ -11,6 +11,7 @@ export type AddOnInfo = {
   id: string
   name: string
   description: string
+  priority?: number
   type: 'add-on' | 'example' | 'starter' | 'toolchain' | 'host'
   modes: Array<'code-router' | 'file-router'>
   smallLogo?: string

Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@`
`4`	`4`	`"link": "https://convex.dev",`
`5`	`5`	`"phase": "add-on",`
`6`	`6`	`"type": "add-on",`
	`7`	`+ "priority": 140,`
`7`	`8`	`"modes": ["file-router"],`
`8`	`9`	`"routes": [`
`9`	`10`	`{`
Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@`
`5`	`5`	`"link": "https://mcp.dev",`
`6`	`6`	`"modes": ["file-router"],`
`7`	`7`	`"type": "add-on",`
	`8`	`+ "priority": 42,`
`8`	`9`	`"warning": "MCP is still in development and may change significantly or not be compatible with other add-ons.\nThe MCP implementation does not support authentication.",`
`9`	`10`	`"routes": [`
`10`	`11`	`{`
Original file line number	Diff line number	Diff line change
`@@ -4,5 +4,6 @@`
`4`	`4`	`"phase": "add-on",`
`5`	`5`	`"modes": ["code-router"],`
`6`	`6`	`"link": "https://module-federation.io/",`
`7`		`- "type": "add-on"`
	`7`	`+ "type": "add-on",`
	`8`	`+ "priority": 38`
`8`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -4,6 +4,7 @@`
`4`	`4`	`"link": "https://neon.com",`
`5`	`5`	`"phase": "add-on",`
`6`	`6`	`"type": "add-on",`
	`7`	`+ "priority": 170,`
`7`	`8`	`"modes": ["file-router"],`
`8`	`9`	`"routes": [`
`9`	`10`	`{`
Original file line number	Diff line number	Diff line change
`@@ -6,6 +6,7 @@`
`6`	`6`	`"link": "https://orpc.unnoq.com/",`
`7`	`7`	`"dependsOn": ["tanstack-query", "start"],`
`8`	`8`	`"type": "add-on",`
	`9`	`+ "priority": 34,`
`9`	`10`	`"routes": [`
`10`	`11`	`{`
`11`	`12`	`"icon": "Network",`
Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@`
`5`	`5`	`"link": "https://sentry.com/",`
`6`	`6`	`"modes": ["file-router"],`
`7`	`7`	`"type": "add-on",`
	`8`	`+ "priority": 130,`
`8`	`9`	`"routes": [`
`9`	`10`	`{`
`10`	`11`	`"url": "/demo/sentry/testing",`