feat: Adding option for toolchain (#37)

Co-authored-by: Iain McHugh <[email protected]>

Author: jherr

README.md

@@ -30,6 +30,7 @@ This will start an interactive CLI that guides you through the setup process, al
 - TypeScript support
 - Tailwind CSS integration
 - Package manager
+- Toolchain
 - Git initialization
 
 ## Command Line Options
@@ -45,6 +46,7 @@ Available options:
 - `--template <type>`: Choose between `file-router`, `typescript`, or `javascript`
 - `--tailwind`: Enable Tailwind CSS
 - `--package-manager`: Specify your preferred package manager (`npm`, `yarn`, `pnpm`, `bun`, or `deno`)
+- `--toolchain`: Specify your toolchain solution for formatting/linting (`biome`)
 - `--no-git`: Do not initialize a git repository
 - `--add-ons`: Enable add-on selection or specify add-ons to install
 
@@ -94,6 +96,12 @@ Choose your preferred package manager (`npm`, `bun`, `yarn`, `pnpm`, or `deno`)
 
 Extensive documentation on using the TanStack Router, migrating to a File Base Routing approach, as well as integrating [@tanstack/react-query](https://tanstack.com/query/latest) and [@tanstack/store](https://tanstack.com/store/latest) can be found in the generated `README.md` for your project.
 
+### Toolchain
+
+Choose your preferred solution for formatting and linting either through the interactive CLI or using the `--toolchain` flag.
+
+Setting this flag to `biome` will configure it as your toolchain of choice, adding a `biome.json` to the root of the project. Consult the [biome documentation](https://biomejs.dev/guides/getting-started/) for further customization.
+
 ## Add-ons (experimental)
 
 You can enable add-on selection:

src/cli.ts

@@ -4,12 +4,14 @@ import { intro, log } from '@clack/prompts'
 import { createApp } from './create-app.js'
 import { normalizeOptions, promptForOptions } from './options.js'
 import { SUPPORTED_PACKAGE_MANAGERS } from './package-manager.js'
+import { SUPPORTED_TOOLCHAINS } from './toolchain.js'
 
 import runServer from './mcp.js'
 import { listAddOns } from './add-ons.js'
 import { DEFAULT_FRAMEWORK, SUPPORTED_FRAMEWORKS } from './constants.js'
 
 import type { PackageManager } from './package-manager.js'
+import type { ToolChain } from './toolchain.js'
 import type { CliOptions, Framework } from './types.js'
 
 export function cli() {
@@ -65,6 +67,20 @@ export function cli() {
         return value as PackageManager
       },
     )
+    .option<ToolChain>(
+      `--toolchain <${SUPPORTED_TOOLCHAINS.join('|')}>`,
+      `Explicitly tell the CLI to use this toolchain`,
+      (value) => {
+        if (!SUPPORTED_TOOLCHAINS.includes(value as ToolChain)) {
+          throw new InvalidArgumentError(
+            `Invalid toolchain: ${value}. The following are allowed: ${SUPPORTED_TOOLCHAINS.join(
+              ', ',
+            )}`,
+          )
+        }
+        return value as ToolChain
+      },
+    )
     .option('--tailwind', 'add Tailwind CSS', false)
     .option<Array<string> | boolean>(
       '--add-ons [...add-ons]',

src/create-app.ts

@@ -30,9 +30,18 @@ function sortObject(obj: Record<string, string>): Record<string, string> {
 }
 
 function createCopyFiles(targetDir: string) {
-  return async function copyFiles(templateDir: string, files: Array<string>) {
+  return async function copyFiles(
+    templateDir: string,
+    files: Array<string>,
+    // optionally copy files from a folder to the root
+    toRoot?: boolean,
+  ) {
     for (const file of files) {
-      const targetFileName = file.replace('.tw', '')
+      let targetFileName = file.replace('.tw', '')
+      if (toRoot) {
+        const fileNoPath = targetFileName.split('/').pop()
+        targetFileName = fileNoPath ? `./${fileNoPath}` : targetFileName
+      }
       await copyFile(
         resolve(templateDir, file),
         resolve(targetDir, targetFileName),
@@ -64,6 +73,7 @@ function createTemplateFile(
       projectName: projectName,
       typescript: options.typescript,
       tailwind: options.tailwind,
+      toolchain: options.toolchain,
       js: options.typescript ? 'ts' : 'js',
       jsx: options.typescript ? 'tsx' : 'jsx',
       fileRouter: options.mode === FILE_ROUTER,
@@ -147,6 +157,22 @@ async function createPackageJSON(
       },
     }
   }
+  if (options.toolchain === 'biome') {
+    const biomePackageJSON = JSON.parse(
+      await readFile(resolve(templateDir, 'package.biome.json'), 'utf8'),
+    )
+    packageJSON = {
+      ...packageJSON,
+      scripts: {
+        ...packageJSON.scripts,
+        ...biomePackageJSON.scripts,
+      },
+      devDependencies: {
+        ...packageJSON.devDependencies,
+        ...biomePackageJSON.devDependencies,
+      },
+    }
+  }
   if (options.mode === FILE_ROUTER) {
     const frPackageJSON = JSON.parse(
       await readFile(resolve(routerDir, 'package.fr.json'), 'utf8'),
@@ -282,10 +308,20 @@ export async function createApp(
 
   // Setup the .vscode directory
   await mkdir(resolve(targetDir, '.vscode'), { recursive: true })
-  await copyFile(
-    resolve(templateDirBase, '_dot_vscode/settings.json'),
-    resolve(targetDir, '.vscode/settings.json'),
-  )
+  switch (options.toolchain) {
+    case 'biome':
+      await copyFile(
+        resolve(templateDirBase, '_dot_vscode/settings.biome.json'),
+        resolve(targetDir, '.vscode/settings.json'),
+      )
+      break
+    case 'none':
+    default:
+      await copyFile(
+        resolve(templateDirBase, '_dot_vscode/settings.json'),
+        resolve(targetDir, '.vscode/settings.json'),
+      )
+  }
 
   // Fill the public directory
   await mkdir(resolve(targetDir, 'public'), { recursive: true })
@@ -321,6 +357,10 @@ export async function createApp(
 
   copyFiles(templateDirBase, ['./src/logo.svg'])
 
+  if (options.toolchain === 'biome') {
+    copyFiles(templateDirBase, ['./toolchain/biome.json'], true)
+  }
+
   // Setup the main, reportWebVitals and index.html files
   if (!isAddOnEnabled('start') && options.framework === 'react') {
     if (options.typescript) {
@@ -346,7 +386,7 @@ export async function createApp(
     )
   }
 
-  // Setup the package.json file, optionally with typescript and tailwind
+  // Setup the package.json file, optionally with typescript, tailwind and biome
   await createPackageJSON(
     options.projectName,
     options,
@@ -567,6 +607,24 @@ export async function createApp(
     }
   }
 
+  if (options.toolchain === 'biome') {
+    s?.start(`Applying toolchain ${options.toolchain}...`)
+    switch (options.packageManager) {
+      case 'pnpm':
+        // pnpm automatically forwards extra arguments
+        await execa(options.packageManager, ['run', 'check', '--fix'], {
+          cwd: targetDir,
+        })
+        break
+      default:
+        await execa(options.packageManager, ['run', 'check', '--', '--fix'], {
+          cwd: targetDir,
+        })
+        break
+    }
+    s?.stop(`Applied toolchain ${options.toolchain}...`)
+  }
+
   if (options.git) {
     s?.start(`Initializing git repository...`)
     await execa('git', ['init'], { cwd: targetDir })

src/mcp.ts

@@ -50,6 +50,10 @@ const tanStackReactAddOns = [
     id: 'store',
     description: 'Enable the TanStack Store state management library',
   },
+  {
+    id: 'tanchat',
+    description: 'Add an AI chatbot example to the application',
+  },
 ]
 
 server.tool('listTanStackReactAddOns', {}, () => {
@@ -98,6 +102,7 @@ server.tool(
           typescript: true,
           tailwind: true,
           packageManager: 'pnpm',
+          toolchain: 'none',
           mode: 'file-router',
           addOns: true,
           chosenAddOns,
@@ -142,6 +147,10 @@ const tanStackSolidAddOns = [
     id: 'tanstack-query',
     description: 'Enable TanStack Query for data fetching',
   },
+  {
+    id: 'tanchat',
+    description: 'Add an AI chatbot example to the application',
+  },
 ]
 
 server.tool('listTanStackSolidAddOns', {}, () => {
@@ -178,6 +187,7 @@ server.tool(
           typescript: true,
           tailwind: true,
           packageManager: 'pnpm',
+          toolchain: 'none',
           mode: 'file-router',
           addOns: true,
           chosenAddOns,

src/options.ts

@@ -12,6 +12,7 @@ import {
   SUPPORTED_PACKAGE_MANAGERS,
   getPackageManager,
 } from './package-manager.js'
+import { DEFAULT_TOOLCHAIN, SUPPORTED_TOOLCHAINS } from './toolchain.js'
 import { CODE_ROUTER, DEFAULT_FRAMEWORK, FILE_ROUTER } from './constants.js'
 import { finalizeAddOns, getAllAddOns } from './add-ons.js'
 import type { AddOn, Variable } from './add-ons.js'
@@ -52,6 +53,7 @@ export async function normalizeOptions(
       typescript,
       tailwind,
       packageManager: cliOptions.packageManager || DEFAULT_PACKAGE_MANAGER,
+      toolchain: cliOptions.toolchain || DEFAULT_TOOLCHAIN,
       mode: cliOptions.template === 'file-router' ? FILE_ROUTER : CODE_ROUTER,
       git: !!cliOptions.git,
       addOns,
@@ -181,7 +183,7 @@ export async function promptForOptions(
   }
 
   // Tailwind selection
-  if (cliOptions.tailwind === undefined && options.framework === 'react') {
+  if (!cliOptions.tailwind && options.framework === 'react') {
     const tailwind = await confirm({
       message: 'Would you like to use Tailwind CSS?',
       initialValue: true,
@@ -219,6 +221,25 @@ export async function promptForOptions(
     options.packageManager = cliOptions.packageManager
   }
 
+  // Toolchain selection
+  if (cliOptions.toolchain === undefined) {
+    const tc = await select({
+      message: 'Select toolchain',
+      options: SUPPORTED_TOOLCHAINS.map((tc) => ({
+        value: tc,
+        label: tc,
+      })),
+      initialValue: DEFAULT_TOOLCHAIN,
+    })
+    if (isCancel(tc)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+    options.toolchain = tc
+  } else {
+    options.toolchain = cliOptions.toolchain
+  }
+
   options.chosenAddOns = []
   if (Array.isArray(cliOptions.addOns)) {
     options.chosenAddOns = await finalizeAddOns(

src/toolchain.ts

@@ -0,0 +1,3 @@
+export const SUPPORTED_TOOLCHAINS = ['none', 'biome'] as const
+export type ToolChain = (typeof SUPPORTED_TOOLCHAINS)[number]
+export const DEFAULT_TOOLCHAIN: ToolChain = 'none'

src/types.ts

@@ -1,6 +1,7 @@
 import type { AddOn } from './add-ons.js'
 import type { CODE_ROUTER, FILE_ROUTER } from './constants.js'
 import type { PackageManager } from './package-manager.js'
+import type { ToolChain } from './toolchain.js'
 
 export type Framework = 'solid' | 'react'
 
@@ -10,6 +11,7 @@ export interface Options {
   typescript: boolean
   tailwind: boolean
   packageManager: PackageManager
+  toolchain: ToolChain
   mode: typeof CODE_ROUTER | typeof FILE_ROUTER
   addOns: boolean
   chosenAddOns: Array<AddOn>
@@ -22,6 +24,7 @@ export interface CliOptions {
   framework?: Framework
   tailwind?: boolean
   packageManager?: PackageManager
+  toolchain?: ToolChain
   projectName?: string
   git?: boolean
   addOns?: Array<string> | boolean

templates/react/base/README.md.ejs

@@ -31,6 +31,16 @@ This project uses [Tailwind CSS](https://tailwindcss.com/) for styling.
 <% } else { %>
 This project uses CSS for styling.
 <% } %>
+<% if (toolchain && toolchain === 'biome') { %>
+## Linting & Formatting
+This project uses [Biome](https://biomejs.dev/) for linting and formatting. The following scripts are available:
+
+```bash
+<%= packageManager %> run lint
+<%= packageManager %> run format
+<%= packageManager %> run check # runs both lint and format together
+```
+<% } %>
 
 <% for(const addon of addOns.filter(addon => addon.readme)) { %>
 <%- addon.readme %>

templates/react/base/_dot_vscode/settings.biome.json

@@ -0,0 +1,38 @@
+{
+  "files.watcherExclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "search.exclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "files.readonlyInclude": {
+    "**/routeTree.gen.ts": true
+  },
+  "[javascript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[javascriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescript]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[typescriptreact]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[json]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[jsonc]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[html]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "[css]": {
+    "editor.defaultFormatter": "biomejs.biome"
+  },
+  "editor.codeActionsOnSave": {
+    "source.organizeImports.biome": "explicit"
+  }
+}

templates/react/base/package.biome.json

@@ -0,0 +1,10 @@
+{
+  "scripts": {
+    "format": "biome format",
+    "lint": "biome lint",
+    "check": "biome check"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4"
+  }
+}