@tanstack/create 0.61.3 → 0.61.5

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @tanstack/create
 
+## 0.61.5
+
+### Patch Changes
+
+- Add a continuous development workflow for custom add-on authors. ([`b3cc585`](https://github.com/TanStack/cli/commit/b3cc5851d2b81613e3b024eb7981c440ee5183af))
+
+  - Add `tanstack add-on dev` to watch project files and continuously refresh `.add-on` outputs.
+  - Rebuild `.add-on` assets and `add-on.json` automatically when source files change.
+  - Document the new add-on development loop in the custom add-on guide.
+
+- Improve scaffold customization and custom add-on authoring flow. ([`5fbf262`](https://github.com/TanStack/cli/commit/5fbf262fe3a0d070e6a78fa2f2a920b176b84480))
+
+  - Add `--examples` / `--no-examples` support to include or omit demo/example pages during app creation.
+  - Prompt for add-on-declared environment variables during interactive create and seed entered values into generated `.env.local`.
+  - Ensure custom add-on/starter metadata consistently includes a `version`, with safe backfill for older metadata files.
+  - Align bundled starter/example metadata and docs with current Start/file-router behavior.
+
+## 0.61.4
+
+### Patch Changes
+
+- Update the React Paraglide Vite plugin strategy to include `baseLocale` alongside `url`, preventing missing-locale routing/rendering errors in generated apps. ([`164522e`](https://github.com/TanStack/cli/commit/164522e444188e83710fc599304132de8cb379e6))
+
+- Improve CLI compatibility and scaffold behavior for legacy router-first workflows. ([`2949819`](https://github.com/TanStack/cli/commit/2949819058b4d4b1760be683ef29bfd459ddb28b))
+
+  - Add safer target directory handling by warning before creating into non-empty folders.
+  - Support explicit git initialization control via `--git` and `--no-git`.
+  - Restore router-only compatibility mode with file-based routing templates (without Start-dependent add-ons/deployments/starters), while still allowing toolchains.
+  - Default `create-tsrouter-app` to router-only compatibility mode.
+  - Remove stale `count.txt` ignore entries from base templates.
+
+  Also expands starter documentation with clearer creation, maintenance, UI usage, and banner guidance.
+
 ## 0.61.3
 
 ### Patch Changes

package/dist/create-app.js

@@ -8,6 +8,42 @@ import { createTemplateFile } from './template-file.js';
 import { installShadcnComponents } from './integrations/shadcn.js';
 import { setupGit } from './integrations/git.js';
 import { runSpecialSteps } from './special-steps/index.js';
+function isDemoRoutePath(path) {
+    if (!path)
+        return false;
+    const normalized = path.replace(/\\/g, '/');
+    return (normalized.includes('/routes/demo/') ||
+        normalized.includes('/routes/demo.') ||
+        normalized.includes('/routes/example/') ||
+        normalized.includes('/routes/example.'));
+}
+function stripExamplesFromOptions(options) {
+    if (options.includeExamples !== false) {
+        return options;
+    }
+    const chosenAddOns = options.chosenAddOns
+        .filter((addOn) => addOn.type !== 'example')
+        .map((addOn) => {
+        const filteredRoutes = (addOn.routes || []).filter((route) => !isDemoRoutePath(route.path) &&
+            !(route.url && route.url.startsWith('/demo')));
+        return {
+            ...addOn,
+            routes: filteredRoutes,
+            getFiles: async () => {
+                const files = await addOn.getFiles();
+                return files.filter((file) => !isDemoRoutePath(file));
+            },
+            getDeletedFiles: async () => {
+                const deletedFiles = await addOn.getDeletedFiles();
+                return deletedFiles.filter((file) => !isDemoRoutePath(file));
+            },
+        };
+    });
+    return {
+        ...options,
+        chosenAddOns,
+    };
+}
 async function writeFiles(environment, options) {
     const templateFileFromContent = createTemplateFile(environment, options);
     async function writeFileBundle(bundle) {
@@ -170,6 +206,29 @@ async function runCommandsAndInstallDependencies(environment, options) {
     }
     await installShadcnComponents(environment, options.targetDir, options);
 }
+async function seedEnvValues(environment, options) {
+    const envVarValues = options.envVarValues || {};
+    const entries = Object.entries(envVarValues);
+    if (entries.length === 0)
+        return;
+    const envLocalPath = resolve(options.targetDir, '.env.local');
+    if (!environment.exists(envLocalPath)) {
+        return;
+    }
+    let envContents = await environment.readFile(envLocalPath);
+    for (const [key, value] of entries) {
+        const escapedValue = value.replace(/\n/g, '\\n');
+        const nextLine = `${key}=${escapedValue}`;
+        const pattern = new RegExp(`^${key}=.*$`, 'm');
+        if (pattern.test(envContents)) {
+            envContents = envContents.replace(pattern, nextLine);
+        }
+        else {
+            envContents += `${envContents.endsWith('\n') ? '' : '\n'}${nextLine}\n`;
+        }
+    }
+    await environment.writeFile(envLocalPath, envContents);
+}
 function report(environment, options) {
     const warnings = [];
     for (const addOn of options.chosenAddOns) {
@@ -207,9 +266,11 @@ ${cdInstruction}% ${formatCommand(getPackageManagerScriptCommand(options.package
 Please read the README.md file for information on testing, styling, adding routes, etc.${errorStatement}`);
 }
 export async function createApp(environment, options) {
+    const effectiveOptions = stripExamplesFromOptions(options);
     environment.startRun();
-    await writeFiles(environment, options);
-    await runCommandsAndInstallDependencies(environment, options);
+    await writeFiles(environment, effectiveOptions);
+    await seedEnvValues(environment, effectiveOptions);
+    await runCommandsAndInstallDependencies(environment, effectiveOptions);
     environment.finishRun();
-    report(environment, options);
+    report(environment, effectiveOptions);
 }

package/dist/custom-add-ons/add-on.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, watch } from 'node:fs/promises';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, resolve } from 'node:path';
 import { AddOnCompiledSchema } from '../types.js';
@@ -15,6 +15,19 @@ export const ADD_ON_IGNORE_FILES = [
 const INFO_FILE = '.add-on/info.json';
 const COMPILED_FILE = 'add-on.json';
 const ASSETS_DIR = 'assets';
+const ADD_ON_DEV_IGNORE_PREFIXES = [
+    '.add-on/',
+    '.git/',
+    'node_modules/',
+    '.turbo/',
+    'dist/',
+];
+function shouldIgnoreDevPath(path) {
+    const normalized = path.replace(/\\/g, '/');
+    if (normalized === COMPILED_FILE)
+        return true;
+    return ADD_ON_DEV_IGNORE_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
 export function camelCase(str) {
     return str
         .split(/(\.|-|\/)/)
@@ -78,6 +91,9 @@ export async function readOrGenerateAddOnInfo(options) {
             },
             dependsOn: options.chosenAddOns,
         };
+    if (!info.version) {
+        info.version = '0.0.1';
+    }
     return info;
 }
 export async function generateProject(persistedOptions) {
@@ -136,6 +152,48 @@ export async function initAddOn(environment) {
     await updateAddOnInfo(environment);
     await compileAddOn(environment);
 }
+export async function devAddOn(environment) {
+    await initAddOn(environment);
+    environment.info('Add-on dev mode is running.', 'Watching project files and recompiling add-on output on changes. Press Ctrl+C to stop.');
+    const abortController = new AbortController();
+    let debounceTimeout;
+    const rerun = async () => {
+        try {
+            await updateAddOnInfo(environment);
+            await compileAddOn(environment);
+            environment.info('Add-on updated.', 'Compiled add-on.json and refreshed .add-on');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            environment.error('Failed to rebuild add-on.', message);
+        }
+    };
+    process.once('SIGINT', () => {
+        abortController.abort();
+    });
+    try {
+        for await (const event of watch(process.cwd(), {
+            recursive: true,
+            signal: abortController.signal,
+        })) {
+            const file = event.filename?.toString();
+            if (!file || shouldIgnoreDevPath(file))
+                continue;
+            if (debounceTimeout) {
+                clearTimeout(debounceTimeout);
+            }
+            debounceTimeout = setTimeout(() => {
+                void rerun();
+            }, 200);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (!message.includes('aborted')) {
+            throw error;
+        }
+    }
+}
 export async function loadRemoteAddOn(url) {
     const response = await fetch(url);
     const jsonContent = await response.json();

package/dist/custom-add-ons/starter.js

@@ -7,7 +7,7 @@ import { compareFilesRecursively, createAppOptionsFromPersisted, createPackageAd
 const INFO_FILE = 'starter-info.json';
 const COMPILED_FILE = 'starter.json';
 export async function readOrGenerateStarterInfo(options) {
-    return existsSync(INFO_FILE)
+    const info = existsSync(INFO_FILE)
         ? JSON.parse((await readFile(INFO_FILE)).toString())
         : {
             id: `${options.projectName}-starter`,
@@ -31,6 +31,10 @@ export async function readOrGenerateStarterInfo(options) {
             dependsOn: options.chosenAddOns,
             typescript: true,
         };
+    if (!info.version) {
+        info.version = '0.0.1';
+    }
+    return info;
 }
 async function loadCurrentStarterInfo(environment) {
     const persistedOptions = await readCurrentProjectOptions(environment);

package/dist/frameworks/react/add-ons/clerk/info.json

@@ -28,5 +28,14 @@
       "jsName": "ClerkProvider",
       "path": "src/integrations/clerk/provider.tsx"
     }
+  ],
+  "envVars": [
+    {
+      "name": "VITE_CLERK_PUBLISHABLE_KEY",
+      "description": "Clerk publishable key",
+      "required": true,
+      "secret": false,
+      "file": ".env.local"
+    }
   ]
 }

package/dist/frameworks/react/add-ons/convex/info.json

@@ -23,5 +23,21 @@
       "path": "src/integrations/convex/provider.tsx",
       "jsName": "ConvexProvider"
     }
+  ],
+  "envVars": [
+    {
+      "name": "CONVEX_DEPLOYMENT",
+      "description": "Convex deployment name",
+      "required": false,
+      "secret": false,
+      "file": ".env.local"
+    },
+    {
+      "name": "VITE_CONVEX_URL",
+      "description": "Convex deployment URL",
+      "required": true,
+      "secret": false,
+      "file": ".env.local"
+    }
   ]
 }

package/dist/frameworks/react/project/base/_dot_gitignore

@@ -3,7 +3,6 @@ node_modules
 dist
 dist-ssr
 *.local
-count.txt
 .env
 .nitro
 .tanstack

package/dist/frameworks/react/project/base/index.html.ejs

@@ -0,0 +1,13 @@
+<% if (!routerOnly) { ignoreFile() } %>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= projectName %></title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/dist/frameworks/react/project/base/src/main.tsx.ejs

@@ -0,0 +1,24 @@
+<% if (!routerOnly) { ignoreFile() } %>
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { RouterProvider, createRouter } from '@tanstack/react-router'
+import { routeTree } from './routeTree.gen'
+
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',
+  scrollRestoration: true,
+})
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+
+const rootElement = document.getElementById('app')!
+
+if (!rootElement.innerHTML) {
+  const root = ReactDOM.createRoot(rootElement)
+  root.render(<RouterProvider router={router} />)
+}

package/dist/frameworks/react/project/base/src/routes/__root.tsx.ejs

@@ -1,3 +1,33 @@
+<% if (routerOnly) { %>
+import { Outlet, createRootRoute } from '@tanstack/react-router'
+import { TanStackRouterDevtoolsPanel } from '@tanstack/react-router-devtools'
+import { TanStackDevtools } from '@tanstack/react-devtools'
+
+import '../styles.css'
+
+export const Route = createRootRoute({
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <>
+      <Outlet />
+      <TanStackDevtools
+        config={{
+          position: 'bottom-right',
+        }}
+        plugins={[
+          {
+            name: 'TanStack Router',
+            render: <TanStackRouterDevtoolsPanel />,
+          },
+        ]}
+      />
+    </>
+  )
+}
+<% } else { %>
 <% let hasContext = addOnEnabled["apollo-client"] || addOnEnabled["tanstack-query"]; %>
 import {
   HeadContent, Scripts, <% if (hasContext) { %>createRootRouteWithContext<% } else { %>createRootRoute<% } %> } from '@tanstack/react-router'
@@ -93,3 +123,4 @@ function RootDocument({ children }: { children: React.ReactNode }) {
     </html>
   )
 }
+<% } %>

package/dist/frameworks/react/project/base/vite.config.ts.ejs

@@ -4,7 +4,11 @@ import tsconfigPaths from 'vite-tsconfig-paths'
 <% if (addOnEnabled.paraglide) { -%>
 import { paraglideVitePlugin } from "@inlang/paraglide-js"
 <% } -%>
+<% if (routerOnly) { %>
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
+<% } else { %>
 import { tanstackStart } from '@tanstack/react-start/plugin/vite';
+<% } %>
 import viteReact from '@vitejs/plugin-react'
 import tailwindcss from "@tailwindcss/vite"
 <% for(const integration of integrations.filter(i => i.type === 'vite-plugin')) { %><%- integrationImportContent(integration) %>
@@ -14,11 +18,11 @@ const config = defineConfig({
   plugins: [devtools(), <% if (addOnEnabled.paraglide) { %>paraglideVitePlugin({
     project: './project.inlang',
     outdir: './src/paraglide',
-    strategy: ['url'],
+    strategy: ['url', "baseLocale"],
   }), <% } %><% for(const integration of integrations.filter(i => i.type === 'vite-plugin')) { %><%- integrationImportCode(integration) %>,<% } %>
     tsconfigPaths({ projects: ['./tsconfig.json'] }),
     tailwindcss(),
-    tanstackStart(),
+    <% if (routerOnly) { %>tanstackRouter({ target: 'react', autoCodeSplitting: true }),<% } else { %>tanstackStart(),<% } %>
     viteReact(<% if (addOnEnabled.compiler) { %>{
       babel: {
         plugins: ["babel-plugin-react-compiler"],

package/dist/frameworks/solid/project/base/_dot_gitignore

@@ -10,4 +10,3 @@ dist-ssr
 .output
 .vinxi
 __unconfig*
-count.txt

package/dist/frameworks/solid/project/base/index.html.ejs

@@ -0,0 +1,13 @@
+<% if (!routerOnly) { ignoreFile() } %>
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title><%= projectName %></title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/dist/frameworks/solid/project/base/src/main.tsx.ejs

@@ -0,0 +1,23 @@
+<% if (!routerOnly) { ignoreFile() } %>
+import { render } from 'solid-js/web'
+import { RouterProvider, createRouter } from '@tanstack/solid-router'
+import { routeTree } from './routeTree.gen'
+
+const router = createRouter({
+  routeTree,
+  defaultPreload: 'intent',
+  defaultPreloadStaleTime: 0,
+  scrollRestoration: true,
+})
+
+declare module '@tanstack/solid-router' {
+  interface Register {
+    router: typeof router
+  }
+}
+
+const rootElement = document.getElementById('app')!
+
+if (!rootElement.innerHTML) {
+  render(() => <RouterProvider router={router} />, rootElement)
+}

package/dist/frameworks/solid/project/base/src/routes/__root.tsx.ejs

@@ -1,3 +1,22 @@
+<% if (routerOnly) { %>
+import { Outlet, createRootRoute } from '@tanstack/solid-router'
+import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools'
+
+import '../styles.css'
+
+export const Route = createRootRoute({
+  component: RootComponent,
+})
+
+function RootComponent() {
+  return (
+    <>
+      <Outlet />
+      <TanStackRouterDevtools position="bottom-right" />
+    </>
+  )
+}
+<% } else { %>
 import { HeadContent, Outlet, Scripts, createRootRouteWithContext } from '@tanstack/solid-router'
 import { TanStackRouterDevtools } from '@tanstack/solid-router-devtools'
 
@@ -47,3 +66,4 @@ function RootComponent() {
       </html>
     );
 }
+<% } %>

package/dist/frameworks/solid/project/base/vite.config.ts.ejs

@@ -2,7 +2,11 @@ import { defineConfig } from "vite";
 import { devtools } from '@tanstack/devtools-vite'
 import viteTsConfigPaths from 'vite-tsconfig-paths'
 import tailwindcss from "@tailwindcss/vite"
+<% if (routerOnly) { %>
+import { tanstackRouter } from '@tanstack/router-plugin/vite'
+<% } else { %>
 import { tanstackStart } from "@tanstack/solid-start/plugin/vite";
+<% } %>
 import solidPlugin from 'vite-plugin-solid';
 <% for(const integration of integrations.filter(i => i.type === 'vite-plugin')) { %><%- integrationImportContent(integration) %>
 <% } %>
@@ -15,7 +19,7 @@ export default defineConfig({
       projects: ['./tsconfig.json'],
     }),
     tailwindcss(),
-    tanstackStart(),
-    solidPlugin({ ssr: true }),
+    <% if (routerOnly) { %>tanstackRouter({ target: 'solid', autoCodeSplitting: true }),<% } else { %>tanstackStart(),<% } %>
+    solidPlugin(<% if (!routerOnly) { %>{ ssr: true }<% } %>),
   ],
 })

package/dist/frameworks.js

@@ -67,6 +67,7 @@ export function scanAddOnDirectories(addOnsDirectories) {
             addOns.push({
                 ...info,
                 id: dir,
+                version: info.version ?? '0.0.0',
                 packageAdditions,
                 packageTemplate,
                 readme,

package/dist/index.js

@@ -17,7 +17,7 @@ export { writeConfigFileToEnvironment, readConfigFileFromEnvironment, readConfig
 export { cleanUpFiles, cleanUpFileArray, readFileHelper, getBinaryFile, recursivelyGatherFiles, relativePath, toCleanPath, } from './file-helpers.js';
 export { formatCommand, handleSpecialURL } from './utils.js';
 export { initStarter, compileStarter } from './custom-add-ons/starter.js';
-export { initAddOn, compileAddOn } from './custom-add-ons/add-on.js';
+export { initAddOn, compileAddOn, devAddOn } from './custom-add-ons/add-on.js';
 export { createAppOptionsFromPersisted, createSerializedOptionsFromPersisted, } from './custom-add-ons/shared.js';
 export { createSerializedOptions } from './options.js';
 export { getRawRegistry, getRegistry, getRegistryAddOns, getRegistryStarters, } from './registry.js';

package/dist/package-json.js

@@ -49,6 +49,7 @@ export function createPackageJSON(options) {
                 jsx: 'tsx',
                 fileRouter: options.mode === 'file-router',
                 codeRouter: options.mode === 'code-router',
+                routerOnly: options.routerOnly === true,
                 addOnEnabled: options.chosenAddOns.reduce((acc, addon) => {
                     acc[addon.id] = true;
                     return acc;
@@ -71,6 +72,25 @@ export function createPackageJSON(options) {
     if (options.starter) {
         packageJSON = mergePackageJSON(packageJSON, options.starter.packageAdditions);
     }
+    if (options.routerOnly) {
+        if (options.framework.id === 'react-cra') {
+            delete packageJSON.dependencies?.['@tanstack/react-start'];
+            delete packageJSON.dependencies?.['@tanstack/react-router-ssr-query'];
+            packageJSON.devDependencies = {
+                ...(packageJSON.devDependencies ?? {}),
+                '@tanstack/router-plugin': packageJSON.devDependencies?.['@tanstack/router-plugin'] ?? '^1.132.0',
+            };
+        }
+        if (options.framework.id === 'solid') {
+            delete packageJSON.dependencies?.['@tanstack/solid-start'];
+            delete packageJSON.dependencies?.['@tanstack/solid-router-ssr-query'];
+            delete packageJSON.scripts?.start;
+            packageJSON.devDependencies = {
+                ...(packageJSON.devDependencies ?? {}),
+                '@tanstack/router-plugin': packageJSON.devDependencies?.['@tanstack/router-plugin'] ?? '^1.133.20',
+            };
+        }
+    }
     packageJSON.dependencies = sortObject((packageJSON.dependencies ?? {}));
     packageJSON.devDependencies = sortObject((packageJSON.devDependencies ?? {}));
     return packageJSON;

package/dist/template-file.js

@@ -82,6 +82,7 @@ export function createTemplateFile(environment, options) {
             jsx: 'tsx',
             fileRouter: options.mode === 'file-router',
             codeRouter: options.mode === 'code-router',
+            routerOnly: options.routerOnly === true,
             addOnEnabled,
             addOnOption: options.addOnOptions,
             addOns: options.chosenAddOns,

package/dist/types/custom-add-ons/add-on.d.ts

@@ -61,6 +61,14 @@ export declare function generateProject(persistedOptions: PersistedOptions): Pro
         addOnSpecialSteps?: string[] | undefined;
         createSpecialSteps?: string[] | undefined;
         postInitSpecialSteps?: string[] | undefined;
+        envVars?: {
+            name: string;
+            file?: ".env" | ".env.local" | undefined;
+            description?: string | undefined;
+            default?: string | undefined;
+            required?: boolean | undefined;
+            secret?: boolean | undefined;
+        }[] | undefined;
         integrations?: {
             type?: string | undefined;
             code?: string | undefined;
@@ -79,4 +87,5 @@ export declare function buildAssetsDirectory(output: {
 export declare function updateAddOnInfo(environment: Environment): Promise<void>;
 export declare function compileAddOn(environment: Environment): Promise<void>;
 export declare function initAddOn(environment: Environment): Promise<void>;
+export declare function devAddOn(environment: Environment): Promise<void>;
 export declare function loadRemoteAddOn(url: string): Promise<AddOn>;

package/dist/types/index.d.ts

@@ -12,7 +12,7 @@ export { writeConfigFileToEnvironment, readConfigFileFromEnvironment, readConfig
 export { cleanUpFiles, cleanUpFileArray, readFileHelper, getBinaryFile, recursivelyGatherFiles, relativePath, toCleanPath, } from './file-helpers.js';
 export { formatCommand, handleSpecialURL } from './utils.js';
 export { initStarter, compileStarter } from './custom-add-ons/starter.js';
-export { initAddOn, compileAddOn } from './custom-add-ons/add-on.js';
+export { initAddOn, compileAddOn, devAddOn } from './custom-add-ons/add-on.js';
 export { createAppOptionsFromPersisted, createSerializedOptionsFromPersisted, } from './custom-add-ons/shared.js';
 export { createSerializedOptions } from './options.js';
 export { getRawRegistry, getRegistry, getRegistryAddOns, getRegistryStarters, } from './registry.js';