Open History to see the last commit
1# Custom Properties Design for CTA Framework
2
3## Overview
4
5This document outlines the design for replacing the hardcoded routes and integrations system with a generic `customProperties` approach using Zod schemas. This will allow framework definitions to declare their own custom properties that can be added to add-ons, providing a more flexible and extensible system.
6
7## Current System Analysis
8
9### Current Implementation
10- **Routes**: Hardcoded array of route objects in `AddOnBaseSchema`
11- **Integrations**: Hardcoded array of integration objects in `AddOnInfoSchema`
12- **Template Processing**: Direct access to `routes` and `integrations` arrays in templates
13- **Type Safety**: Fixed TypeScript types for routes and integrations
14
15### Limitations
161. Framework-specific concepts (routes/integrations) are baked into the core engine
172. No flexibility for frameworks to define their own custom properties
183. All frameworks must use the same structure for routes and integrations
194. Cannot easily add new property types without modifying core engine
20
21## Proposed Design
22
23### Core Concept
24
25Replace hardcoded `routes` and `integrations` with a generic `customProperties` system where:
261. Frameworks define their own custom property schemas using Zod
272. Add-ons provide values matching these schemas
283. Templates access properties through a unified interface
294. Type safety is maintained through Zod inference
30
31### Framework Definition Structure
32
33```typescript
34// Example: React framework definition
35export function createFrameworkDefinition(): FrameworkDefinition {
36 return {
37 id: 'react-cra',
38 name: 'React',
39 customProperties: {
40 routes: z.array(
41 z.object({
42 url: z.string().optional(),
43 name: z.string().optional(),
44 path: z.string(),
45 jsName: z.string(),
46 })
47 ).optional(),
48 integrations: z.array(
49 z.object({
50 type: z.enum(['provider', 'root-provider', 'layout', 'header-user']),
51 path: z.string(),
52 jsName: z.string(),
53 })
54 ).optional(),
55 },
56 // ... rest of definition
57 }
58}
59```
60
61### Type Updates
62
63```typescript
64// packages/cta-engine/src/types.ts
65
66import type { ZodTypeAny } from 'zod'
67
68// Update FrameworkDefinition to include customProperties
69export type FrameworkDefinition = {
70 id: string
71 name: string
72 description: string
73 version: string
75 // New field for custom property schemas
76 customProperties?: Record<string, ZodTypeAny>
78 base: Record<string, string>
79 addOns: Array<AddOn>
80 basePackageJSON: Record<string, any>
81 optionalPackages: Record<string, any>
83 supportedModes: Record<
84 string,
85 {
86 displayName: string
87 description: string
88 forceTypescript: boolean
89 }
90 >
91}
92
93// Remove routes from AddOnBaseSchema
94export const AddOnBaseSchema = z.object({
95 id: z.string(),
96 name: z.string(),
97 description: z.string(),
98 author: z.string().optional(),
99 version: z.string().optional(),
100 link: z.string().optional(),
101 license: z.string().optional(),
102 warning: z.string().optional(),
103 type: z.enum(['add-on', 'example', 'starter', 'toolchain']),
104 command: z
105 .object({
106 command: z.string(),
107 args: z.array(z.string()).optional(),
108 })
109 .optional(),
110 // Remove routes - it will be in customProperties
111 packageAdditions: z
112 .object({
113 dependencies: z.record(z.string(), z.string()).optional(),
114 devDependencies: z.record(z.string(), z.string()).optional(),
115 scripts: z.record(z.string(), z.string()).optional(),
116 })
117 .optional(),
118 shadcnComponents: z.array(z.string()).optional(),
119 dependsOn: z.array(z.string()).optional(),
120 smallLogo: z.string().optional(),
121 logo: z.string().optional(),
122 addOnSpecialSteps: z.array(z.string()).optional(),
123 createSpecialSteps: z.array(z.string()).optional(),
124})
125
126// Update AddOnInfoSchema to remove integrations
127export const AddOnInfoSchema = AddOnBaseSchema.extend({
128 modes: z.array(z.string()),
129 phase: z.enum(['setup', 'add-on']),
130 readme: z.string().optional(),
131 // Add customProperties field
132 customProperties: z.record(z.string(), z.unknown()).optional(),
133})
134
135// Remove the separate Integration schema as it will be framework-specific
136// export const IntegrationSchema = z.object({...}) - REMOVE
137```
138
139### Add-on Loading and Validation
140
141```typescript
142// packages/cta-engine/src/add-on-loader.ts
143
144export async function loadAddOn(
145 addOnPath: string,
146 framework: Framework
147): Promise<AddOn> {
148 const info = await loadAddOnInfo(addOnPath)
150 // Validate custom properties against framework schema
151 if (framework.customProperties && info.customProperties) {
152 const validatedProperties: Record<string, unknown> = {}
154 for (const [key, schema] of Object.entries(framework.customProperties)) {
155 if (key in info.customProperties) {
156 try {
157 validatedProperties[key] = schema.parse(info.customProperties[key])
158 } catch (error) {
159 throw new Error(
160 `Invalid custom property "${key}" in add-on "${info.id}": ${error.message}`
161 )
162 }
163 }
164 }
166 info.customProperties = validatedProperties
167 }
169 return {
170 ...info,
171 getFiles,
172 getFileContents,
173 getDeletedFiles,
174 }
175}
176```
177
178### Template Processing Updates
179
180```typescript
181// packages/cta-engine/src/template-file.ts
182
183export function createTemplateFile(environment: Environment, options: Options) {
184 // Collect all custom properties from add-ons
185 const customProperties: Record<string, Array<unknown>> = {}
187 // Initialize arrays for all framework custom properties
188 if (options.framework.customProperties) {
189 for (const key of Object.keys(options.framework.customProperties)) {
190 customProperties[key] = []
191 }
192 }
194 // Collect custom properties from each add-on
195 for (const addOn of options.chosenAddOns) {
196 if (addOn.customProperties) {
197 for (const [key, values] of Object.entries(addOn.customProperties)) {
198 if (customProperties[key] && Array.isArray(values)) {
199 customProperties[key].push(...values)
200 } else if (customProperties[key] && !Array.isArray(values)) {
201 customProperties[key].push(values)
202 }
203 }
204 }
205 }
207 return async function templateFile(file: string, content: string) {
208 const templateValues = {
209 // ... existing values
210 packageManager: options.packageManager,
211 projectName: options.projectName,
212 typescript: options.typescript,
213 tailwind: options.tailwind,
214 js: options.typescript ? 'ts' : 'js',
215 jsx: options.typescript ? 'tsx' : 'jsx',
216 fileRouter: options.mode === 'file-router',
217 codeRouter: options.mode === 'code-router',
218 addOnEnabled,
219 addOns: options.chosenAddOns,
221 // Add custom properties dynamically
222 ...customProperties,
224 // Helper functions
225 getPackageManagerAddScript,
226 getPackageManagerRunScript,
227 relativePath: (path: string) => relativePath(file, path),
228 ignoreFile: () => {
229 throw new IgnoreFileError()
230 },
231 }
233 // ... rest of template processing
234 }
235}
236```
237
238## Implementation Plan
239
240### 1. Core Engine Updates
241- [ ] Add `customProperties` to `FrameworkDefinition` type
242- [ ] Remove `routes` from `AddOnBaseSchema`
243- [ ] Remove `integrations` and `IntegrationSchema` from types
244- [ ] Add `customProperties` field to `AddOnInfoSchema`
245- [ ] Update add-on loader to validate custom properties
246- [ ] Update template processor to expose custom properties
247
248### 2. Framework Updates
249- [ ] Update React framework to define routes/integrations schemas
250- [ ] Update Solid framework similarly
251- [ ] Update all framework templates to use customProperties
252
253### 3. Add-on Updates
254- [ ] Update all add-on info.json files to use customProperties
255- [ ] Update add-on documentation
256- [ ] Remove routes/integrations from root level
257
258### 4. Template Updates
259- [ ] Update all EJS templates to access properties from customProperties
260- [ ] Update navigation generation to use customProperties.routes
261- [ ] Update integration rendering to use customProperties.integrations
262
263## Benefits
264
2651. **Extensibility**: Frameworks can define any custom properties they need
2662. **Type Safety**: Zod schemas provide runtime validation and TypeScript types
2673. **Flexibility**: Different frameworks can have different property structures
2684. **Future-Proof**: New property types can be added without core engine changes
2695. **Framework-Specific**: Each framework can have its own domain-specific concepts
2706. **Clean Architecture**: No framework-specific concepts in core engine
271
272## Example: Framework-Specific Properties
273
274### React Framework
275```typescript
276customProperties: {
277 routes: z.array(
278 z.object({
279 url: z.string().optional(),
280 name: z.string().optional(),
281 path: z.string(),
282 jsName: z.string(),
283 })
284 ).optional(),
285 integrations: z.array(
286 z.object({
287 type: z.enum(['provider', 'root-provider', 'layout', 'header-user']),
288 path: z.string(),
289 jsName: z.string(),
290 })
291 ).optional(),
292 contextProviders: z.array(
293 z.object({
294 name: z.string(),
295 path: z.string(),
296 wrapperComponent: z.string(),
297 })
298 ).optional(),
299 hooks: z.array(
300 z.object({
301 name: z.string(),
302 path: z.string(),
303 category: z.enum(['state', 'effect', 'context', 'custom']),
304 })
305 ).optional(),
306}
307```
308
309### Solid Framework
310```typescript
311customProperties: {
312 routes: z.array(
313 z.object({
314 url: z.string().optional(),
315 name: z.string().optional(),
316 path: z.string(),
317 jsName: z.string(),
318 })
319 ).optional(),
320 integrations: z.array(
321 z.object({
322 type: z.enum(['provider', 'root-provider', 'layout', 'header-user']),
323 path: z.string(),
324 jsName: z.string(),
325 })
326 ).optional(),
327 signals: z.array(
328 z.object({
329 name: z.string(),
330 path: z.string(),
331 global: z.boolean(),
332 })
333 ).optional(),
334 stores: z.array(
335 z.object({
336 name: z.string(),
337 path: z.string(),
338 type: z.enum(['store', 'mutable']),
339 })
340 ).optional(),
341}
342```
343
344### Vue Framework (hypothetical)
345```typescript
346customProperties: {
347 routes: z.array(
348 z.object({
349 url: z.string().optional(),
350 name: z.string().optional(),
351 path: z.string(),
352 jsName: z.string(),
353 })
354 ).optional(),
355 components: z.array(
356 z.object({
357 name: z.string(),
358 path: z.string(),
359 global: z.boolean(),
360 })
361 ).optional(),
362 composables: z.array(
363 z.object({
364 name: z.string(),
365 path: z.string(),
366 autoImport: z.boolean(),
367 })
368 ).optional(),
369 plugins: z.array(
370 z.object({
371 name: z.string(),
372 path: z.string(),
373 options: z.record(z.string(), z.unknown()).optional(),
374 })
375 ).optional(),
376}
377```
378
379## Add-on info.json Structure
380
381### Before
382```json
383{
384 "id": "tanstack-query",
385 "name": "Query",
386 "description": "Integrate TanStack Query into your application.",
387 "routes": [
388 {
389 "url": "/demo/tanstack-query",
390 "name": "TanStack Query",
391 "path": "src/routes/demo.tanstack-query.tsx",
392 "jsName": "TanStackQueryDemo"
393 }
394 ],
395 "integrations": [
396 {
397 "type": "root-provider",
398 "path": "src/integrations/tanstack-query/root-provider.tsx",
399 "jsName": "TanStackQueryProvider"
400 }
401 ]
402}
403```
404
405### After
406```json
407{
408 "id": "tanstack-query",
409 "name": "Query",
410 "description": "Integrate TanStack Query into your application.",
411 "customProperties": {
412 "routes": [
413 {
414 "url": "/demo/tanstack-query",
415 "name": "TanStack Query",
416 "path": "src/routes/demo.tanstack-query.tsx",
417 "jsName": "TanStackQueryDemo"
418 }
419 ],
420 "integrations": [
421 {
422 "type": "root-provider",
423 "path": "src/integrations/tanstack-query/root-provider.tsx",
424 "jsName": "TanStackQueryProvider"
425 }
426 ]
427 }
428}
429```
430
431## Template Access Pattern
432
433### Before
434```ejs
435<% for(const route of routes) { %>
436 <Link to="<%= route.url %>"><%= route.name %></Link>
437<% } %>
438
439<% for(const integration of integrations.filter(i => i.type === 'provider')) { %>
440 <<%= integration.jsName %>>
441<% } %>
442```
443
444### After
445```ejs
446<% for(const route of routes) { %>
447 <Link to="<%= route.url %>"><%= route.name %></Link>
448<% } %>
449
450<% for(const integration of integrations.filter(i => i.type === 'provider')) { %>
451 <<%= integration.jsName %>>
452<% } %>
453```
454
455The template access remains the same because `customProperties` are spread into the template values, making `routes` and `integrations` available at the top level.
456
457## Testing Strategy
458
4591. **Unit Tests**: Test custom property validation and merging
4602. **Integration Tests**: Test full app generation with custom properties
4613. **Framework Tests**: Test each framework's custom properties
4624. **Template Tests**: Verify templates render correctly with new system
4635. **Add-on Tests**: Test all add-ons work with new structure
464
465## Conclusion
466
467The custom properties system provides a flexible, type-safe way for frameworks to extend the add-on system with their own domain-specific concepts. By removing hardcoded framework-specific properties from the core engine, we create a truly extensible system that can adapt to any framework's needs.