@tanstack/create 0.61.4 → 0.61.6

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @tanstack/create
 
+## 0.61.6
+
+### Patch Changes
+
+- Improve the Strapi add-on scaffolding for reliability. ([#323](https://github.com/TanStack/cli/pull/323))
+
+  - Remove brittle post-create shell automation that attempted to clone and bootstrap a sibling Strapi server.
+  - Fix Strapi article detail routing to use a consistent file-based route path.
+  - Update Strapi add-on guidance to document manual/hosted Strapi setup expectations.
+
+## 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/react/add-ons/strapi/README.md

@@ -1,14 +1,164 @@
-## Setting up Strapi
+## Strapi CMS Integration
 
-The current setup shows an example of how to use Strapi with an articles collection which is part of the example structure & data.
+This add-on integrates Strapi CMS with your TanStack Start application using the official Strapi Client SDK.
 
-- Create a local running copy of the strapi admin
+### Features
 
+- Article listing with search and pagination
+- Article detail pages with dynamic block rendering
+- Rich text, quotes, media, and image slider blocks
+- Markdown content rendering with GitHub Flavored Markdown
+- Responsive image handling with error fallbacks
+- URL-based search and pagination (shareable/bookmarkable)
+- Graceful error handling with helpful setup instructions
+
+### Project Structure
+
+```
+parent/
+├── client/                 # TanStack Start frontend (your project name)
+│   ├── src/
+│   │   ├── components/
+│   │   │   ├── blocks/     # Block rendering components
+│   │   │   ├── markdown-content.tsx
+│   │   │   ├── pagination.tsx
+│   │   │   ├── search.tsx
+│   │   │   └── strapi-image.tsx
+│   │   ├── data/
+│   │   │   ├── loaders/    # Server functions
+│   │   │   └── strapi-sdk.ts
+│   │   ├── lib/
+│   │   │   └── strapi-utils.ts
+│   │   ├── routes/demo/
+│   │   │   ├── strapi.tsx              # Articles list
+│   │   │   └── strapi.$articleId.tsx   # Article detail
+│   │   └── types/
+│   │       └── strapi.ts
+│   ├── .env.local
+│   └── package.json
+└── server/                 # Strapi CMS backend (create manually or use hosted Strapi)
+    ├── src/api/            # Content types
+    ├── config/             # Strapi configuration
+    └── package.json
+```
+
+### Quick Start
+
+Create your Strapi project separately (or use an existing hosted Strapi instance), then point this app to it with `VITE_STRAPI_URL`.
+
+**1. Set up Strapi:**
+
+Follow the Strapi quick-start guide to create a local project, or use your existing Strapi deployment:
+
+- https://docs.strapi.io/dev-docs/quick-start
+
+If you created a local Strapi project in a sibling `server` directory, continue with:
+
+```bash
+cd ../server
+npm install    # or pnpm install / yarn install
+```
+
+**2. Start the Strapi server:**
+
+```bash
+npm run develop    # Starts at http://localhost:1337
+```
+
+**3. Create an admin account:**
+
+Open http://localhost:1337/admin and create your first admin user.
+
+**4. Create content:**
+
+In the Strapi admin panel, go to Content Manager > Article and create some articles.
+
+**5. Start your TanStack app (in another terminal):**
+
+```bash
+cd ../client   # or your project name
+npm run dev    # Starts at http://localhost:3000
+```
+
+**6. View the demo:**
+
+Navigate to http://localhost:3000/demo/strapi to see your articles.
+
+### Environment Variables
+
+The following environment variable is pre-configured in `.env.local`:
+
+```bash
+VITE_STRAPI_URL="http://localhost:1337"
+```
+
+For production, update this to your deployed Strapi URL.
+
+### Demo Pages
+
+| URL | Description |
+|-----|-------------|
+| `/demo/strapi` | Articles list with search and pagination |
+| `/demo/strapi/:articleId` | Article detail with block rendering |
+
+### Search and Pagination
+
+- **Search**: Type in the search box to filter articles by title or description
+- **Pagination**: Navigate between pages using the pagination controls
+- **URL State**: Search and page are stored in the URL (`?query=term&page=2`)
+
+### Block Types Supported
+
+| Block | Component | Description |
+|-------|-----------|-------------|
+| `shared.rich-text` | RichText | Markdown content |
+| `shared.quote` | Quote | Blockquote with author |
+| `shared.media` | Media | Single image/video |
+| `shared.slider` | Slider | Image gallery grid |
+
+### Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@strapi/client` | Official Strapi SDK |
+| `react-markdown` | Markdown rendering |
+| `remark-gfm` | GitHub Flavored Markdown |
+| `use-debounce` | Debounced search input |
+
+### Running Both Servers
+
+Open two terminal windows from the parent directory:
+
+**Terminal 1 - Strapi:**
 ```bash
-pnpm dlx create-strapi@latest my-strapi-project
-cd my-strapi-project
-pnpm dev
+cd server && npm run develop
 ```
 
-- Login and publish the example articles to see them on the strapi demo page.
-- Set the `VITE_STRAPI_URL` environment variable in your `.env.local`. (For local it should be http://localhost:1337/api)
+**Terminal 2 - TanStack Start:**
+```bash
+cd client && npm run dev   # or your project name
+```
+
+### Customization
+
+**Change page size:**
+Edit `src/data/loaders/articles.ts` and modify `PAGE_SIZE`.
+
+**Add new block types:**
+1. Create component in `src/components/blocks/`
+2. Export from `src/components/blocks/index.ts`
+3. Add case to `block-renderer.tsx` switch statement
+4. Update populate in articles loader
+
+**Add new content types:**
+1. Add types to `src/types/strapi.ts`
+2. Create loader in `src/data/loaders/`
+3. Create route in `src/routes/demo/`
+
+### Learn More
+
+- [Strapi Documentation](https://docs.strapi.io/)
+- [Strapi Client SDK](https://www.npmjs.com/package/@strapi/client)
+- [Strapi Cloud Template Blog](https://github.com/strapi/strapi-cloud-template-blog)
+- [TanStack Start Documentation](https://tanstack.com/start/latest)
+- [TanStack Router Search Params](https://tanstack.com/router/latest/docs/framework/react/guide/search-params)

package/dist/frameworks/react/add-ons/strapi/assets/_dot_env.local.append

@@ -1,2 +1,2 @@
 # Strapi configuration
-VITE_STRAPI_URL="http://localhost:1337/api"
+VITE_STRAPI_URL="http://localhost:1337"

package/dist/frameworks/react/add-ons/strapi/assets/src/components/blocks/block-renderer.tsx

@@ -0,0 +1,55 @@
+import { RichText } from "./rich-text";
+import { Quote } from "./quote";
+import { Media } from "./media";
+import { Slider } from "./slider";
+
+import type { IRichText } from "./rich-text";
+import type { IQuote } from "./quote";
+import type { IMedia } from "./media";
+import type { ISlider } from "./slider";
+
+// Union type of all block types
+export type Block = IRichText | IQuote | IMedia | ISlider;
+
+interface BlockRendererProps {
+  blocks: Array<Block>;
+}
+
+/**
+ * BlockRenderer - Renders dynamic content blocks from Strapi
+ *
+ * Usage:
+ * ```tsx
+ * <BlockRenderer blocks={article.blocks} />
+ * ```
+ */
+export function BlockRenderer({ blocks }: Readonly<BlockRendererProps>) {
+  if (!blocks || blocks.length === 0) return null;
+
+  const renderBlock = (block: Block) => {
+    switch (block.__component) {
+      case "shared.rich-text":
+        return <RichText {...block} />;
+      case "shared.quote":
+        return <Quote {...block} />;
+      case "shared.media":
+        return <Media {...block} />;
+      case "shared.slider":
+        return <Slider {...block} />;
+      default:
+        // Log unknown block types in development
+        console.warn("Unknown block type:", (block as any).__component);
+        return null;
+    }
+  };
+
+  return (
+    <div className="space-y-6">
+      {blocks.map((block, index) => (
+        <div key={`${block.__component}-${block.id}-${index}`}>
+          {renderBlock(block)}
+        </div>
+      ))}
+    </div>
+  );
+}

package/dist/frameworks/react/add-ons/strapi/assets/src/components/blocks/index.ts

@@ -0,0 +1,14 @@
+export { BlockRenderer } from "./block-renderer";
+export type { Block } from "./block-renderer";
+
+export { RichText } from "./rich-text";
+export type { IRichText } from "./rich-text";
+
+export { Quote } from "./quote";
+export type { IQuote } from "./quote";
+
+export { Media } from "./media";
+export type { IMedia } from "./media";
+
+export { Slider } from "./slider";
+export type { ISlider } from "./slider";

package/dist/frameworks/react/add-ons/strapi/assets/src/components/blocks/media.tsx

@@ -0,0 +1,27 @@
+import { StrapiImage } from "@/components/strapi-image";
+import type { TImage } from "@/types/strapi";
+
+export interface IMedia {
+  __component: "shared.media";
+  id: number;
+  file?: TImage;
+}
+
+export function Media({ file }: Readonly<IMedia>) {
+  if (!file) return null;
+
+  return (
+    <figure className="my-8">
+      <StrapiImage
+        src={file.url}
+        alt={file.alternativeText || ""}
+        className="rounded-lg w-full"
+      />
+      {file.alternativeText && (
+        <figcaption className="mt-2 text-center text-sm text-gray-500">
+          {file.alternativeText}
+        </figcaption>
+      )}
+    </figure>
+  );
+}

package/dist/frameworks/react/add-ons/strapi/assets/src/components/blocks/quote.tsx

@@ -0,0 +1,19 @@
+export interface IQuote {
+  __component: "shared.quote";
+  id: number;
+  body: string;
+  title?: string;
+}
+
+export function Quote({ body, title }: Readonly<IQuote>) {
+  return (
+    <blockquote className="border-l-4 border-cyan-400 pl-6 py-4 my-6 bg-slate-800/30 rounded-r-lg">
+      <p className="text-xl italic text-gray-300 leading-relaxed">{body}</p>
+      {title && (
+        <cite className="block mt-4 text-cyan-400 not-italic font-medium">
+          — {title}
+        </cite>
+      )}
+    </blockquote>
+  );
+}

package/dist/frameworks/react/add-ons/strapi/assets/src/components/blocks/rich-text.tsx

@@ -0,0 +1,11 @@
+import { MarkdownContent } from "@/components/markdown-content";
+
+export interface IRichText {
+  __component: "shared.rich-text";
+  id: number;
+  body: string;
+}
+
+export function RichText({ body }: Readonly<IRichText>) {
+  return <MarkdownContent content={body} />;
+}

package/dist/frameworks/react/add-ons/strapi/assets/src/components/blocks/slider.tsx

@@ -0,0 +1,28 @@
+import { StrapiImage } from "@/components/strapi-image";
+import type { TImage } from "@/types/strapi";
+
+export interface ISlider {
+  __component: "shared.slider";
+  id: number;
+  files?: Array<TImage>;
+}
+
+export function Slider({ files }: Readonly<ISlider>) {
+  if (!files || files.length === 0) return null;
+
+  return (
+    <div className="my-8">
+      <div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
+        {files.map((file, index) => (
+          <figure key={file.id || index}>
+            <StrapiImage
+              src={file.url}
+              alt={file.alternativeText || ""}
+              className="rounded-lg w-full h-48 object-cover"
+            />
+          </figure>
+        ))}
+      </div>
+    </div>
+  );
+}

package/dist/frameworks/react/add-ons/strapi/assets/src/components/markdown-content.tsx

@@ -0,0 +1,74 @@
+import Markdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+
+interface MarkdownContentProps {
+  content: string | undefined | null;
+  className?: string;
+}
+
+const styles = {
+  h1: "text-3xl font-bold mb-6 text-white",
+  h2: "text-2xl font-bold mb-4 text-white",
+  h3: "text-xl font-bold mb-3 text-white",
+  p: "mb-4 leading-relaxed text-gray-300",
+  a: "text-cyan-400 hover:underline",
+  ul: "list-disc pl-6 mb-4 space-y-2 text-gray-300",
+  ol: "list-decimal pl-6 mb-4 space-y-2 text-gray-300",
+  li: "leading-relaxed",
+  blockquote: "border-l-4 border-cyan-400 pl-4 italic text-gray-400 my-4",
+  code: "bg-slate-800 px-2 py-1 rounded text-cyan-400 text-sm font-mono",
+  pre: "bg-slate-800 p-4 rounded-lg overflow-x-auto mb-4",
+  table: "w-full border-collapse mb-4",
+  th: "border border-slate-700 p-2 bg-slate-800 text-left text-white",
+  td: "border border-slate-700 p-2 text-gray-300",
+  img: "max-w-full h-auto rounded-lg my-4",
+  hr: "border-slate-700 my-8",
+  strong: "text-white font-semibold",
+};
+
+export function MarkdownContent({ content, className = "" }: MarkdownContentProps) {
+  if (!content) return null;
+
+  return (
+    <div className={`prose prose-invert max-w-none ${className}`}>
+      <Markdown
+        remarkPlugins={[remarkGfm]}
+        components={{
+          h1: ({ children }) => <h1 className={styles.h1}>{children}</h1>,
+          h2: ({ children }) => <h2 className={styles.h2}>{children}</h2>,
+          h3: ({ children }) => <h3 className={styles.h3}>{children}</h3>,
+          p: ({ children }) => <p className={styles.p}>{children}</p>,
+          a: ({ href, children }) => (
+            <a href={href} className={styles.a} target="_blank" rel="noopener noreferrer">
+              {children}
+            </a>
+          ),
+          ul: ({ children }) => <ul className={styles.ul}>{children}</ul>,
+          ol: ({ children }) => <ol className={styles.ol}>{children}</ol>,
+          li: ({ children }) => <li className={styles.li}>{children}</li>,
+          blockquote: ({ children }) => <blockquote className={styles.blockquote}>{children}</blockquote>,
+          code: ({ className, children }) => {
+            const isCodeBlock = className?.includes("language-");
+            if (isCodeBlock) {
+              return (
+                <pre className={styles.pre}>
+                  <code className="text-sm font-mono text-gray-300">{children}</code>
+                </pre>
+              );
+            }
+            return <code className={styles.code}>{children}</code>;
+          },
+          pre: ({ children }) => <>{children}</>,
+          table: ({ children }) => <table className={styles.table}>{children}</table>,
+          th: ({ children }) => <th className={styles.th}>{children}</th>,
+          td: ({ children }) => <td className={styles.td}>{children}</td>,
+          img: ({ src, alt }) => <img src={src} alt={alt || ""} className={styles.img} />,
+          hr: () => <hr className={styles.hr} />,
+          strong: ({ children }) => <strong className={styles.strong}>{children}</strong>,
+        }}
+      >
+        {content}
+      </Markdown>
+    </div>
+  );
+}