chore: adding another example of a customized CLI

Author: jherr

examples/custom-cli/README.md

@@ -0,0 +1,21 @@
+## Scenarios
+
+There are three customizing scenarios we should support:
+
+- Augmenting an exsting CTA framework - Take an existing framework like `react-cra` then allow for base template customization, removal of add-ons, and addition of new custom add-ons.
+- Customized UI - Build up a new UI from components of the base UI.
+- New framework - Build up a new framework from with base and add-ons as well as a new CLI.
+
+## Customers
+
+There are two types of customers for this work:
+
+- Infrastructure teams - Infrastructure teams at companies who want to create a template for new applications as well as optional add-ons with a friendly CLI and UI.
+- OSS framework authors - OSS framework authors who want to build a friendly CLI and UI for their framework.
+
+## Examples
+
+| Project                                | Description                                                           |
+| -------------------------------------- | --------------------------------------------------------------------- |
+| [customized-react](./customized-react) | Shows a small customization of the existing `react-cra` framework.    |
+| [create-qwik-app](./create-qwik-app)   | Show support for an entire framework (Qwik) with a custom CLI and UI. |

examples/custom-cli/create-qwik-app/src/index.ts

@@ -2,21 +2,36 @@
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { registerFramework } from '@tanstack/cta-engine'
+import {
+  registerFramework,
+  scanAddOnDirectories,
+  scanProjectDirectory,
+} from '@tanstack/cta-engine'
 import { cli } from '@tanstack/cta-cli'
 
+const projectDirectory = join(
+  dirname(dirname(fileURLToPath(import.meta.url))),
+  'project',
+)
+
+const addOns = scanAddOnDirectories([
+  join(dirname(dirname(fileURLToPath(import.meta.url))), 'add-ons'),
+])
+
+const { files, basePackageJSON, optionalPackages } = scanProjectDirectory(
+  projectDirectory,
+  join(dirname(dirname(fileURLToPath(import.meta.url))), 'project'),
+)
+
 registerFramework({
   id: 'qwik',
   name: 'qwik',
   description: 'Templates for Qwik',
   version: '0.1.0',
-  baseDirectory: join(
-    dirname(dirname(fileURLToPath(import.meta.url))),
-    'project',
-  ),
-  addOnsDirectories: [
-    join(dirname(dirname(fileURLToPath(import.meta.url))), 'add-ons'),
-  ],
+  base: files,
+  addOns,
+  basePackageJSON,
+  optionalPackages,
   supportedModes: {
     default: {
       displayName: 'Default',

examples/custom-cli/customized-react/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "customized-react-app",
+  "version": "0.15.2",
+  "description": "CTA Qwik Builder",
+  "bin": "./dist/index.js",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TanStack/create-router-app.git"
+  },
+  "homepage": "https://tanstack.com/router",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/tannerlinsley"
+  },
+  "keywords": [
+    "qwik",
+    "create-tanstack-app",
+    "tanstack",
+    "create-qwik-app"
+  ],
+  "author": "Jack Herrington <[email protected]>",
+  "license": "MIT",
+  "packageManager": "[email protected]",
+  "dependencies": {
+    "@tanstack/cta-cli": "workspace:*",
+    "@tanstack/cta-engine": "workspace:*",
+    "@tanstack/cta-framework-react-cra": "1.96.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "typescript": "^5.6.3"
+  }
+}

examples/custom-cli/customized-react/project/base/src/App.tsx.ejs

@@ -0,0 +1,15 @@
+<% if (fileRouter) { ignoreFile() } %><% if (!tailwind) { %>import "./App.css";<% } %>
+
+function App() {
+  return (<% if (tailwind) { %>
+    <div className="text-center">
+      <h1>I'm a customized setup</h1>
+    </div>
+<% } else { %>
+    <div className="App">
+      <h1>I'm a customized setup</h1>
+    </div>
+<% } %>  );
+}
+
+export default App;

examples/custom-cli/customized-react/project/base/src/routes/index.tsx.ejs

@@ -0,0 +1,19 @@
+<% if (codeRouter) { ignoreFile() } %>
+import { createFileRoute } from "@tanstack/react-router";
+<% if (!tailwind) { %>import "../App.css";<% } %>
+
+export const Route = createFileRoute("/")({
+  component: App,
+});
+
+function App() {
+  return (<% if (tailwind) { %>
+    <div className="text-center">
+      <h1>I'm a customized setup</h1>
+    </div>
+<% } else { %>
+    <div className="App">
+      <h1>I'm a customized setup</h1>
+    </div>
+<% } %>  );
+}

examples/custom-cli/customized-react/src/index.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { cli } from '@tanstack/cta-cli'
+import { registerFramework, scanProjectDirectory } from '@tanstack/cta-engine'
+import { createFrameworkDefinition } from '@tanstack/cta-framework-react-cra'
+
+const frameworkDefinition = createFrameworkDefinition()
+
+frameworkDefinition.id = 'react'
+frameworkDefinition.name = 'react'
+frameworkDefinition.description = 'Customized React Setup'
+frameworkDefinition.version = '0.1.0'
+
+const baseDirectory = dirname(dirname(fileURLToPath(import.meta.url)))
+const { files } = scanProjectDirectory(
+  join(baseDirectory, 'project'),
+  join(baseDirectory, 'project/base'),
+)
+
+frameworkDefinition.base = {
+  ...frameworkDefinition.base,
+  ...files,
+}
+
+registerFramework(frameworkDefinition)
+
+cli({
+  name: 'customized-react-app',
+  appName: 'React',
+  defaultFramework: 'react',
+})

examples/custom-cli/customized-react/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ES2020",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "moduleResolution": "node",
+    "declaration": true,
+    "declarationDir": "./dist/types"
+  },
+  "include": ["./src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

frameworks/react-cra/src/index.ts

@@ -1,23 +1,36 @@
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { registerFramework } from '@tanstack/cta-engine'
+import {
+  registerFramework,
+  scanAddOnDirectories,
+  scanProjectDirectory,
+} from '@tanstack/cta-engine'
+import type { FrameworkDefinition } from '@tanstack/cta-engine'
 
-export function register() {
-  registerFramework({
+export function createFrameworkDefinition(): FrameworkDefinition {
+  const baseDirectory = dirname(dirname(fileURLToPath(import.meta.url)))
+
+  const addOns = scanAddOnDirectories([
+    join(baseDirectory, 'add-ons'),
+    join(baseDirectory, 'toolchains'),
+    join(baseDirectory, 'examples'),
+  ])
+
+  const { files, basePackageJSON, optionalPackages } = scanProjectDirectory(
+    join(baseDirectory, 'project'),
+    join(baseDirectory, 'project/base'),
+  )
+
+  return {
     id: 'react-cra',
     name: 'react',
     description: 'Templates for React CRA',
     version: '0.1.0',
-    baseDirectory: join(
-      dirname(dirname(fileURLToPath(import.meta.url))),
-      'project',
-    ),
-    addOnsDirectories: [
-      join(dirname(dirname(fileURLToPath(import.meta.url))), 'add-ons'),
-      join(dirname(dirname(fileURLToPath(import.meta.url))), 'toolchains'),
-      join(dirname(dirname(fileURLToPath(import.meta.url))), 'examples'),
-    ],
+    base: files,
+    addOns,
+    basePackageJSON,
+    optionalPackages,
     supportedModes: {
       'code-router': {
         displayName: 'Code Router',
@@ -30,5 +43,9 @@ export function register() {
         forceTypescript: true,
       },
     },
-  })
+  }
+}
+
+export function register() {
+  registerFramework(createFrameworkDefinition())
 }

frameworks/solid/src/index.ts

@@ -1,23 +1,36 @@
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
-import { registerFramework } from '@tanstack/cta-engine'
+import {
+  registerFramework,
+  scanAddOnDirectories,
+  scanProjectDirectory,
+} from '@tanstack/cta-engine'
+import type { FrameworkDefinition } from '@tanstack/cta-engine'
 
-export function register() {
-  registerFramework({
+export function createFrameworkDefinition(): FrameworkDefinition {
+  const baseDirectory = dirname(dirname(fileURLToPath(import.meta.url)))
+
+  const addOns = scanAddOnDirectories([
+    join(baseDirectory, 'add-ons'),
+    join(baseDirectory, 'toolchains'),
+    join(baseDirectory, 'examples'),
+  ])
+
+  const { files, basePackageJSON, optionalPackages } = scanProjectDirectory(
+    join(baseDirectory, 'project'),
+    join(baseDirectory, 'project/base'),
+  )
+
+  return {
     id: 'solid',
     name: 'solid',
     description: 'Solid templates for Tanstack Router Applications',
     version: '0.1.0',
-    baseDirectory: join(
-      dirname(dirname(fileURLToPath(import.meta.url))),
-      'project',
-    ),
-    addOnsDirectories: [
-      join(dirname(dirname(fileURLToPath(import.meta.url))), 'add-ons'),
-      join(dirname(dirname(fileURLToPath(import.meta.url))), 'toolchains'),
-      join(dirname(dirname(fileURLToPath(import.meta.url))), 'examples'),
-    ],
+    base: files,
+    addOns,
+    basePackageJSON,
+    optionalPackages,
     supportedModes: {
       'code-router': {
         displayName: 'Code Router',
@@ -30,5 +43,9 @@ export function register() {
         forceTypescript: true,
       },
     },
-  })
+  }
+}
+
+export function register() {
+  registerFramework(createFrameworkDefinition())
 }

frameworks/solid/tests/solid.test.ts

@@ -7,7 +7,7 @@ import {
   getFrameworkById,
 } from '@tanstack/cta-engine'
 
-import type { AddOn, Mode, Options } from '@tanstack/cta-engine'
+import type { AddOn, Options } from '@tanstack/cta-engine'
 
 import { cleanupOutput } from './test-utilities.js'
 
@@ -77,7 +77,7 @@ test('file router on npm', async () => {
   const { environment, output } = createMemoryEnvironment()
   const options = {
     ...(await createSolidOptions(projectName)),
-    mode: 'file-router' as Mode,
+    mode: 'file-router',
     typescript: true,
   }
   await createApp(environment, options)
@@ -92,7 +92,7 @@ test('file router with tailwind on npm', async () => {
   const { environment, output } = createMemoryEnvironment()
   const options = {
     ...(await createSolidOptions(projectName)),
-    mode: 'file-router' as Mode,
+    mode: 'file-router',
     typescript: true,
     tailwind: true,
   }