@tanstack/create 0.61.4 → 0.61.5

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @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

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.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/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';

package/dist/types/types.d.ts

@@ -198,6 +198,28 @@ export declare const AddOnBaseSchema: z.ZodObject<{
         default: string;
         description?: string | undefined;
     }>]>>>;
+    envVars: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodString>;
+        secret: z.ZodOptional<z.ZodBoolean>;
+        file: z.ZodOptional<z.ZodEnum<[".env", ".env.local"]>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }>, "many">>;
     default: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     type: "add-on" | "example" | "starter" | "toolchain" | "deployment";
@@ -247,6 +269,14 @@ export declare const AddOnBaseSchema: z.ZodObject<{
     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;
 }, {
     type: "add-on" | "example" | "starter" | "toolchain" | "deployment";
     description: string;
@@ -295,6 +325,14 @@ export declare const AddOnBaseSchema: z.ZodObject<{
     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;
 }>;
 export declare const StarterSchema: z.ZodObject<{
     id: z.ZodString;
@@ -391,6 +429,28 @@ export declare const StarterSchema: z.ZodObject<{
         default: string;
         description?: string | undefined;
     }>]>>>;
+    envVars: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodString>;
+        secret: z.ZodOptional<z.ZodBoolean>;
+        file: z.ZodOptional<z.ZodEnum<[".env", ".env.local"]>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }>, "many">>;
     default: z.ZodOptional<z.ZodBoolean>;
 } & {
     framework: z.ZodString;
@@ -448,6 +508,14 @@ export declare const StarterSchema: z.ZodObject<{
     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;
     banner?: string | undefined;
 }, {
     type: "add-on" | "example" | "starter" | "toolchain" | "deployment";
@@ -500,6 +568,14 @@ export declare const StarterSchema: z.ZodObject<{
     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;
     banner?: string | undefined;
 }>;
 export declare const StarterCompiledSchema: z.ZodObject<{
@@ -597,6 +673,28 @@ export declare const StarterCompiledSchema: z.ZodObject<{
         default: string;
         description?: string | undefined;
     }>]>>>;
+    envVars: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodString>;
+        secret: z.ZodOptional<z.ZodBoolean>;
+        file: z.ZodOptional<z.ZodEnum<[".env", ".env.local"]>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }>, "many">>;
     default: z.ZodOptional<z.ZodBoolean>;
 } & {
     framework: z.ZodString;
@@ -659,6 +757,14 @@ export declare const StarterCompiledSchema: z.ZodObject<{
     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;
     banner?: string | undefined;
 }, {
     type: "add-on" | "example" | "starter" | "toolchain" | "deployment";
@@ -713,6 +819,14 @@ export declare const StarterCompiledSchema: z.ZodObject<{
     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;
     banner?: string | undefined;
 }>;
 export declare const IntegrationSchema: z.ZodObject<{
@@ -829,6 +943,28 @@ export declare const AddOnInfoSchema: z.ZodObject<{
         default: string;
         description?: string | undefined;
     }>]>>>;
+    envVars: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodString>;
+        secret: z.ZodOptional<z.ZodBoolean>;
+        file: z.ZodOptional<z.ZodEnum<[".env", ".env.local"]>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }>, "many">>;
     default: z.ZodOptional<z.ZodBoolean>;
 } & {
     modes: z.ZodArray<z.ZodString, "many">;
@@ -904,6 +1040,14 @@ export declare const AddOnInfoSchema: z.ZodObject<{
     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;
@@ -963,6 +1107,14 @@ export declare const AddOnInfoSchema: z.ZodObject<{
     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;
@@ -1068,6 +1220,28 @@ export declare const AddOnCompiledSchema: z.ZodObject<{
         default: string;
         description?: string | undefined;
     }>]>>>;
+    envVars: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        required: z.ZodOptional<z.ZodBoolean>;
+        default: z.ZodOptional<z.ZodString>;
+        secret: z.ZodOptional<z.ZodBoolean>;
+        file: z.ZodOptional<z.ZodEnum<[".env", ".env.local"]>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }, {
+        name: string;
+        file?: ".env" | ".env.local" | undefined;
+        description?: string | undefined;
+        default?: string | undefined;
+        required?: boolean | undefined;
+        secret?: boolean | undefined;
+    }>, "many">>;
     default: z.ZodOptional<z.ZodBoolean>;
 } & {
     modes: z.ZodArray<z.ZodString, "many">;
@@ -1149,6 +1323,14 @@ export declare const AddOnCompiledSchema: z.ZodObject<{
     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;
@@ -1211,6 +1393,14 @@ export declare const AddOnCompiledSchema: z.ZodObject<{
     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;
@@ -1275,6 +1465,8 @@ export interface Options {
     addOnOptions: Record<string, Record<string, any>>;
     starter?: Starter | undefined;
     routerOnly?: boolean;
+    includeExamples?: boolean;
+    envVarValues?: Record<string, string>;
 }
 export type SerializedOptions = Omit<Options, 'chosenAddOns' | 'starter' | 'framework'> & {
     chosenAddOns: Array<string>;

package/dist/types.js

@@ -75,6 +75,16 @@ export const AddOnBaseSchema = z.object({
     createSpecialSteps: z.array(z.string()).optional(),
     postInitSpecialSteps: z.array(z.string()).optional(),
     options: AddOnOptionsSchema.optional(),
+    envVars: z
+        .array(z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        required: z.boolean().optional(),
+        default: z.string().optional(),
+        secret: z.boolean().optional(),
+        file: z.enum(['.env', '.env.local']).optional(),
+    }))
+        .optional(),
     default: z.boolean().optional(),
 });
 export const StarterSchema = AddOnBaseSchema.extend({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/create",
-  "version": "0.61.4",
+  "version": "0.61.5",
   "description": "TanStack Application Builder Engine",
   "type": "module",
   "main": "./dist/index.js",

package/src/create-app.ts

@@ -16,6 +16,51 @@ import { runSpecialSteps } from './special-steps/index.js'
 
 import type { Environment, FileBundleHandler, Options } from './types.js'
 
+function isDemoRoutePath(path?: string) {
+  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: Options): 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: Environment, options: Options) {
   const templateFileFromContent = createTemplateFile(environment, options)
 
@@ -235,6 +280,32 @@ async function runCommandsAndInstallDependencies(
   await installShadcnComponents(environment, options.targetDir, options)
 }
 
+async function seedEnvValues(environment: Environment, options: 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: Environment, options: Options) {
   const warnings: Array<string> = []
   for (const addOn of options.chosenAddOns) {
@@ -282,10 +353,13 @@ Please read the README.md file for information on testing, styling, adding route
 }
 
 export async function createApp(environment: Environment, options: 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/src/custom-add-ons/add-on.ts

@@ -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'
 
@@ -36,6 +36,22 @@ 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: string) {
+  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: string) {
   return str
     .split(/(\.|-|\/)/)
@@ -122,6 +138,11 @@ export async function readOrGenerateAddOnInfo(
         },
         dependsOn: options.chosenAddOns,
       } as AddOnInfo)
+
+  if (!info.version) {
+    info.version = '0.0.1'
+  }
+
   return info
 }
 
@@ -213,6 +234,56 @@ export async function initAddOn(environment: Environment) {
   await compileAddOn(environment)
 }
 
+export async function devAddOn(environment: 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: ReturnType<typeof setTimeout> | undefined
+
+  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: string): Promise<AddOn> {
   const response = await fetch(url)
   const jsonContent = await response.json()

package/src/custom-add-ons/starter.ts

@@ -27,7 +27,7 @@ const COMPILED_FILE = 'starter.json'
 export async function readOrGenerateStarterInfo(
   options: PersistedOptions,
 ): Promise<StarterInfo> {
-  return existsSync(INFO_FILE)
+  const info = existsSync(INFO_FILE)
     ? JSON.parse((await readFile(INFO_FILE)).toString())
     : {
         id: `${options.projectName}-starter`,
@@ -51,6 +51,12 @@ export async function readOrGenerateStarterInfo(
         dependsOn: options.chosenAddOns,
         typescript: true,
       }
+
+  if (!info.version) {
+    info.version = '0.0.1'
+  }
+
+  return info
 }
 
 async function loadCurrentStarterInfo(environment: Environment) {

package/src/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/src/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/src/frameworks.ts

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

package/src/index.ts

@@ -61,7 +61,7 @@ export {
 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,

package/src/types.ts

@@ -92,6 +92,18 @@ export const AddOnBaseSchema = z.object({
   createSpecialSteps: z.array(z.string()).optional(),
   postInitSpecialSteps: z.array(z.string()).optional(),
   options: AddOnOptionsSchema.optional(),
+  envVars: z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string().optional(),
+        required: z.boolean().optional(),
+        default: z.string().optional(),
+        secret: z.boolean().optional(),
+        file: z.enum(['.env', '.env.local']).optional(),
+      }),
+    )
+    .optional(),
   default: z.boolean().optional(),
 })
 
@@ -207,6 +219,8 @@ export interface Options {
   addOnOptions: Record<string, Record<string, any>>
   starter?: Starter | undefined
   routerOnly?: boolean
+  includeExamples?: boolean
+  envVarValues?: Record<string, string>
 }
 
 export type SerializedOptions = Omit<

package/tests/custom-add-ons/starter.test.ts

@@ -55,4 +55,33 @@ describe('readOrGenerateStarterInfo', () => {
     })
     expect(starterInfo.name).toEqual('test-starter')
   })
+
+  it('should backfill version when missing', async () => {
+    fs.mkdirSync(process.cwd(), { recursive: true })
+    fs.writeFileSync(
+      'starter-info.json',
+      JSON.stringify({
+        framework: 'test',
+        chosenAddOns: [],
+        starter: undefined,
+        name: 'test-starter',
+        mode: 'code-router',
+        typescript: true,
+        tailwind: true,
+        git: true,
+      }),
+    )
+    const starterInfo = await readOrGenerateStarterInfo({
+      framework: 'test',
+      version: 1,
+      chosenAddOns: [],
+      starter: undefined,
+      projectName: 'test',
+      mode: 'code-router',
+      typescript: true,
+      tailwind: true,
+      git: true,
+    })
+    expect(starterInfo.version).toEqual('0.0.1')
+  })
 })