Skip to content
Source
Sign inSign up
TanStack/cli
Open History to see the last commit

CUSTOM_PROPERTIES_DESIGN.md

467 lines12.9 KB

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 }
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 >
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 }
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 }
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(),
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(),
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(),
377```
378​
379## Add-on info.json Structure
380​
381### Before
382```json
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 ]
403```
404​
405### After
406```json
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 }
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.