Routes and Integrations in CTA Engine#
This document explains how the routes and integrations systems work in the Create TanStack Application (CTA) engine. These two concepts are fundamental to how add-ons extend and enhance generated applications.
Table of Contents#
- Overview
- Routes System
- Integrations System
- Implementation Details
- Add-on Examples
- Creating Custom Add-ons
Overview#
The CTA engine uses two primary mechanisms for add-ons to extend applications:
- Routes: Demo pages and API endpoints that showcase add-on functionality
- Integrations: Components and providers that integrate into the application's structure
Both systems work together to provide a seamless way for add-ons to enhance applications without manual configuration.
Routes System#
What are Routes?#
Routes are demo pages or API endpoints that add-ons provide to showcase their functionality. They are automatically registered with the TanStack Router when an add-on is selected during app creation.
Route Structure#
Routes are defined in an add-on's info.json file:
{
"routes": [
{
"url": "/demo/tanstack-query",
"name": "TanStack Query",
"path": "src/routes/demo.tanstack-query.tsx",
"jsName": "TanStackQueryDemo"
}
]
}
Route Properties#
- url (optional): The URL path where the route will be accessible
- name (optional): Display name for navigation links
- path: File path relative to the add-on's assets directory
- jsName: JavaScript/TypeScript identifier used when importing the route
How Routes are Processed#
- Collection Phase: During app generation, the template engine collects all routes from selected add-ons:
// From template-file.ts
const routes: Array<Required<AddOn>['routes'][number]> = []
for (const addOn of options.chosenAddOns) {
if (addOn.routes) {
routes.push(...addOn.routes)
}
}
Template Processing: Routes are made available to EJS templates via the
routesvariableRouter Integration: Routes are integrated differently based on the routing mode:
Code Router Mode#
In code router mode, routes are imported and registered directly in main.tsx:
// Import route components
<% for(const route of routes) { %>
import <%= route.jsName %> from "<%= relativePath(route.path) %>";
<% } %>
// Register routes with the router
const routeTree = rootRoute.addChildren([
indexRoute<%= routes.map(route => `, ${route.jsName}(rootRoute)`).join('') %>
]);
File Router Mode#
In file router mode, route files are copied to the appropriate location in the routes directory, and the TanStack Router file-based routing system automatically discovers them.
Route File Format#
Route files use the TanStack Router format and are automatically templatized to work in both routing modes:
// Original route file
import { createFileRoute } from '@tanstack/react-router'
export const Route = createFileRoute('/demo/my-feature')({
component: MyFeatureDemo,
})
// After templatization (EJS)
import { <% if (fileRouter) { %>createFileRoute<% } else { %>createRoute<% } %> } from '@tanstack/react-router'
<% if (codeRouter) { %>
import type { RootRoute } from '@tanstack/react-router'
export default (parentRoute: RootRoute) => createRoute({
path: '/demo/my-feature',
component: MyFeatureDemo,
getParentRoute: () => parentRoute,
})
<% } else { %>
export const Route = createFileRoute('/demo/my-feature')({
component: MyFeatureDemo,
})
<% } %>
Integrations System#
What are Integrations?#
Integrations are components and providers that need to be injected into specific locations within the application structure. They allow add-ons to wrap the application with providers, add layout components, or inject UI elements into the header.
Integration Types#
The CTA engine supports four types of integrations:
1. Provider Integration#
Wraps the application or router with a context provider:
{
"type": "provider",
"jsName": "ClerkProvider",
"path": "src/integrations/clerk/provider.tsx"
}
Providers are rendered in the root layout, wrapping the router outlet:
<% for(const integration of integrations.filter(i => i.type === 'provider')) { %>
<<%= integration.jsName %>>
<% } %>
<Outlet />
<% for(const integration of integrations.filter(i => i.type === 'provider').reverse()) { %>
</<%= integration.jsName %>>
<% } %>
2. Root Provider Integration#
Special providers that wrap the entire application and provide context to the router:
{
"type": "root-provider",
"path": "src/integrations/tanstack-query/root-provider.tsx",
"jsName": "TanStackQueryProvider"
}
Root providers must export:
Provider: React component that wraps the appgetContext(): Function that returns context for the router
// Import root providers
<% for(const integration of integrations.filter(i => i.type === 'root-provider')) { %>
import * as <%= integration.jsName %> from "<%= relativePath(integration.path) %>";
<% } %>
// Add context to router
const router = createRouter({
routeTree,
context: {
<% for(const integration of integrations.filter(i => i.type === 'root-provider')) { %>
...<%= integration.jsName %>.getContext(),
<% } %>
},
})
// Wrap the application
<% for(const integration of integrations.filter(i => i.type === 'root-provider')) { %>
<<%= integration.jsName %>.Provider>
<% } %>
<RouterProvider router={router} />
<% for(const integration of integrations.filter(i => i.type === 'root-provider').reverse()) { %>
</<%= integration.jsName %>.Provider>
<% } %>
3. Layout Integration#
Components that are rendered alongside the router outlet (e.g., devtools):
{
"type": "layout",
"path": "src/integrations/tanstack-query/layout.tsx",
"jsName": "TanStackQueryLayout"
}
Layout components are rendered after the outlet:
<Outlet />
<% for(const integration of integrations.filter(i => i.type === 'layout')) { %>
<<%= integration.jsName %> />
<% } %>
4. Header User Integration#
Components that are injected into the application header (e.g., user menus):
{
"type": "header-user",
"jsName": "ClerkHeader",
"path": "src/integrations/clerk/header-user.tsx"
}
Header user components are rendered in the header component:
<% if (integrations.filter(i => i.type === 'header-user').length > 0) { %>
<div>
<% for(const integration of integrations.filter(i => i.type === 'header-user')) { %>
<<%= integration.jsName %> />
<% } %>
</div>
<% } %>
Implementation Details#
Type Definitions#
The TypeScript types for routes and integrations are defined in types.ts:
// Integration type definition
export const IntegrationSchema = z.object({
type: z.string(),
path: z.string(),
jsName: z.string(),
})
// Add-on schema includes both routes and integrations
export const AddOnInfoSchema = AddOnBaseSchema.extend({
routes: z.array(
z.object({
url: z.string().optional(),
name: z.string().optional(),
path: z.string(),
jsName: z.string(),
}),
).optional(),
integrations: z.array(IntegrationSchema).optional(),
// ... other properties
})
Template Processing#
The template engine (template-file.ts) makes routes and integrations available to all EJS templates:
// Collect integrations from all add-ons
const integrations: Array<Required<AddOn>['integrations'][number]> = []
for (const addOn of options.chosenAddOns) {
if (addOn.integrations) {
for (const integration of addOn.integrations) {
integrations.push(integration)
}
}
}
// Collect routes from all add-ons
const routes: Array<Required<AddOn>['routes'][number]> = []
for (const addOn of options.chosenAddOns) {
if (addOn.routes) {
routes.push(...addOn.routes)
}
}
// Make available to templates
const templateValues = {
// ... other values
integrations,
routes,
// ... other values
}
Navigation Generation#
The Header component automatically generates navigation links for all routes that have both url and name properties:
<% for(const addOn of addOns) {
for(const route of (addOn?.routes||[])?.filter(r => r.url && r.name)) { %>
<div className="px-2 font-bold">
<Link to="<%= route.url %>"><%= route.name %></Link>
</div>
<% } } %>
Add-on Examples#
TanStack Query Add-on#
This add-on demonstrates both routes and integrations:
{
"name": "Query",
"description": "Integrate TanStack Query into your application.",
"routes": [
{
"url": "/demo/tanstack-query",
"name": "TanStack Query",
"path": "src/routes/demo.tanstack-query.tsx",
"jsName": "TanStackQueryDemo"
}
],
"integrations": [
{
"type": "root-provider",
"path": "src/integrations/tanstack-query/root-provider.tsx",
"jsName": "TanStackQueryProvider"
},
{
"type": "layout",
"path": "src/integrations/tanstack-query/layout.tsx",
"jsName": "TanStackQueryLayout"
}
]
}
Clerk Authentication Add-on#
This add-on uses provider and header integrations:
{
"name": "Clerk",
"description": "Add Clerk authentication to your application.",
"routes": [
{
"url": "/demo/clerk",
"name": "Clerk",
"path": "src/routes/demo.clerk.tsx",
"jsName": "ClerkDemo"
}
],
"integrations": [
{
"type": "header-user",
"jsName": "ClerkHeader",
"path": "src/integrations/clerk/header-user.tsx"
},
{
"type": "provider",
"jsName": "ClerkProvider",
"path": "src/integrations/clerk/provider.tsx"
}
]
}
Creating Custom Add-ons#
Best Practices for Routes#
- Naming Convention: Use descriptive names prefixed with
demo.for demo routes - Path Structure: Place route files in
assets/src/routes/ - Component Naming: Use PascalCase for
jsName(e.g.,MyFeatureDemo) - URL Pattern: Use
/demo/feature-namefor demo routes
Best Practices for Integrations#
Provider Integrations:
- Use for wrapping parts of the app with context
- Keep providers focused on a single concern
- Don't add UI elements in providers
Root Provider Integrations:
- Use when you need to provide context to the router
- Always export both
ProviderandgetContext() - Initialize any required clients or stores
Layout Integrations:
- Use for developer tools or persistent UI elements
- Keep layout components lightweight
- Position them appropriately (devtools, tooltips, etc.)
Header User Integrations:
- Use for user-specific UI in the header
- Keep components small and focused
- Consider responsive design
File Structure#
Organize your add-on files consistently:
my-addon/
├── info.json
├── package.json
├── assets/
│ ├── src/
│ │ ├── routes/
│ │ │ └── demo.my-feature.tsx
│ │ └── integrations/
│ │ └── my-feature/
│ │ ├── provider.tsx
│ │ └── layout.tsx
│ └── _dot_env.local.append
Testing Your Add-on#
- Create a test project with your add-on
- Verify routes appear in navigation
- Check that integrations are properly injected
- Test in both file-router and code-router modes
- Ensure TypeScript types work correctly
Integration Dependencies#
If your integrations depend on other add-ons, use the dependsOn field:
{
"dependsOn": ["tanstack-query", "start"]
}
This ensures required add-ons are included when your add-on is selected.