chore: add examples

Author: jherr

src/add-ons.ts

@@ -3,6 +3,29 @@ import { existsSync, readdirSync, statSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
+type BooleanVariable = {
+  name: string
+  default: boolean
+  description: string
+  type: 'boolean'
+}
+
+type NumberVariable = {
+  name: string
+  default: number
+  description: string
+  type: 'number'
+}
+
+type StringVariable = {
+  name: string
+  default: string
+  description: string
+  type: 'string'
+}
+
+export type Variable = BooleanVariable | NumberVariable | StringVariable
+
 export type AddOn = {
   id: string
   type: 'add-on' | 'example'
@@ -44,6 +67,7 @@ export type AddOn = {
   shadcnComponents?: Array<string>
   warning?: string
   dependsOn?: Array<string>
+  variables?: Array<Variable>
 }
 
 function isDirectory(path: string): boolean {

src/options.ts

@@ -14,6 +14,7 @@ import {
 } from './package-manager.js'
 import { CODE_ROUTER, FILE_ROUTER } from './constants.js'
 import { finalizeAddOns, getAllAddOns } from './add-ons.js'
+import type { Variable } from './add-ons.js'
 
 import type { CliOptions, Options } from './types.js'
 
@@ -35,10 +36,51 @@ export function normalizeOptions(
       git: !!cliOptions.git,
       addOns: !!cliOptions.addOns,
       chosenAddOns: [],
+      variableValues: {},
     }
   }
 }
 
+async function collectVariables(
+  variables: Array<Variable>,
+): Promise<Record<string, string | number | boolean>> {
+  const responses: Record<string, string | number | boolean> = {}
+  for (const variable of variables) {
+    if (variable.type === 'string') {
+      const response = await text({
+        message: variable.description,
+        initialValue: variable.default,
+      })
+      if (isCancel(response)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      responses[variable.name] = response
+    } else if (variable.type === 'number') {
+      const response = await text({
+        message: variable.description,
+        initialValue: variable.default.toString(),
+      })
+      if (isCancel(response)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      responses[variable.name] = Number(response)
+    } else {
+      const response = await confirm({
+        message: variable.description,
+        initialValue: variable.default === true,
+      })
+      if (isCancel(response)) {
+        cancel('Operation cancelled.')
+        process.exit(0)
+      }
+      responses[variable.name] = response
+    }
+  }
+  return responses
+}
+
 export async function promptForOptions(
   cliOptions: CliOptions,
 ): Promise<Required<Options>> {
@@ -194,6 +236,15 @@ export async function promptForOptions(
     options.chosenAddOns = []
   }
 
+  // Collect variables
+  const variables: Array<Variable> = []
+  for (const addOn of options.chosenAddOns) {
+    for (const variable of addOn.variables ?? []) {
+      variables.push(variable)
+    }
+  }
+  options.variableValues = await collectVariables(variables)
+
   // Git selection
   if (cliOptions.git === undefined) {
     const git = await confirm({

src/types.ts

@@ -11,6 +11,7 @@ export interface Options {
   addOns: boolean
   chosenAddOns: Array<AddOn>
   git: boolean
+  variableValues: Record<string, string | number | boolean>
 }
 
 export interface CliOptions {

templates/add-on/convex/assets/.cursorrules.append

@@ -0,0 +1,93 @@
+This document serves as some special instructions when working with Convex.
+
+# Schemas
+
+When designing the schema please see this page on built in System fields and data types available: https://docs.convex.dev/database/types
+
+Here are some specifics that are often mishandled:
+
+## v (https://docs.convex.dev/api/modules/values#v)
+
+The validator builder.
+
+This builder allows you to build validators for Convex values.
+
+Validators can be used in schema definitions and as input validators for Convex functions.
+
+Type declaration
+Name	Type
+id	<TableName>(tableName: TableName) => VId<GenericId<TableName>, "required">
+null	() => VNull<null, "required">
+number	() => VFloat64<number, "required">
+float64	() => VFloat64<number, "required">
+bigint	() => VInt64<bigint, "required">
+int64	() => VInt64<bigint, "required">
+boolean	() => VBoolean<boolean, "required">
+string	() => VString<string, "required">
+bytes	() => VBytes<ArrayBuffer, "required">
+literal	<T>(literal: T) => VLiteral<T, "required">
+array	<T>(element: T) => VArray<T["type"][], T, "required">
+object	<T>(fields: T) => VObject<Expand<{ [Property in string | number | symbol]?: Exclude<Infer<T[Property]>, undefined> } & { [Property in string | number | symbol]: Infer<T[Property]> }>, T, "required", { [Property in string | number | symbol]: Property | `${Property & string}.${T[Property]["fieldPaths"]}` }[keyof T] & string>
+record	<Key, Value>(keys: Key, values: Value) => VRecord<Record<Infer<Key>, Value["type"]>, Key, Value, "required", string>
+union	<T>(...members: T) => VUnion<T[number]["type"], T, "required", T[number]["fieldPaths"]>
+any	() => VAny<any, "required", string>
+optional	<T>(value: T) => VOptional<T>
+
+## System fields (https://docs.convex.dev/database/types#system-fields)
+
+Every document in Convex has two automatically-generated system fields:
+
+_id: The document ID of the document.
+_creationTime: The time this document was created, in milliseconds since the Unix epoch.
+
+You do not need to add indices as these are added automatically.
+
+## Example Schema
+
+This is an example of a well crafted schema.
+
+```ts
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema(
+  {
+    users: defineTable({
+      name: v.string(),
+    }),
+    
+    sessions: defineTable({
+      userId: v.id("users"),
+      sessionId: v.string(),
+    }).index("sessionId", ["sessionId"]),
+    
+    threads: defineTable({
+      uuid: v.string(),
+      summary: v.optional(v.string()),
+      summarizer: v.optional(v.id("_scheduled_functions")),
+    }).index("uuid", ["uuid"]),
+
+    messages: defineTable({
+      message: v.string(),
+      threadId: v.id("threads"),
+      author: v.union(
+        v.object({
+          role: v.literal("system"),
+        }),
+        v.object({
+          role: v.literal("assistant"),
+          context: v.array(v.id("messages")),
+          model: v.optional(v.string()),
+        }),
+        v.object({
+          role: v.literal("user"),
+          userId: v.id("users"),
+        }),
+      ),
+    })
+      .index("threadId", ["threadId"]),
+  },
+);
+```
+
+Sourced from: https://github.com/PatrickJS/awesome-cursorrules/blob/main/rules/convex-cursorrules-prompt-file/.cursorrules

templates/add-on/sentry/assets/.cursorrules

@@ -0,0 +1,22 @@
+We use Sentry for watching for errors in our deployed application, as well as for instrumentation of our application.
+
+## Error collection
+
+Error collection is automatic and configured in `src/router.tsx`.
+
+## Instrumentation
+
+We want our server functions intstrumented. So if you see a function name like `createServerFn`, you can instrument it with Sentry. You'll need to import `Sentry`:
+
+```tsx
+import * as Sentry from '@sentry/browser'
+```
+
+And then wrap the implementation of the server function with `Sentry.startSpan`, liks so:
+
+```tsx
+Sentry.startSpan({ name: 'Requesting all the pokemon' }, async () => {
+  // Some lengthy operation here
+  await fetch('https://api.pokemon.com/data/')
+})
+```

templates/add-on/start/assets/app.config.ts

@@ -1,7 +1,16 @@
 import { defineConfig } from '@tanstack/start/config'
+import viteTsConfigPaths from 'vite-tsconfig-paths'
 
 export default defineConfig({
   tsr: {
     appDirectory: 'src',
   },
+  vite: {
+    plugins: [
+      // this is the plugin that enables path aliases
+      viteTsConfigPaths({
+        projects: ['./tsconfig.json'],
+      }),
+    ],
+  },
 })

templates/add-on/start/package.json

@@ -8,6 +8,7 @@
     "@tailwindcss/postcss": "^4.0.7",
     "@tanstack/start": "^1.106.0",
     "postcss": "^8.5.2",
-    "vinxi": "^0.5.3"
+    "vinxi": "^0.5.3",
+    "vite-tsconfig-paths": "^5.1.4"
   }
 }

templates/example/ai-chat/assets/src/routes/example.ai-chat.tsx renamed to templates/example/ai-chat/assets/src/routes/example.ai-chat.tsx.ejs

@@ -27,6 +27,7 @@ const chat = createServerFn({ method: 'POST' })
       },
       body: JSON.stringify({
         model: 'gpt-3.5-turbo',
+        system: `<%= variables.ai_chat_system %>`,
         messages: data,
       }),
     }).then((response) => {
@@ -59,6 +60,7 @@ function AIChat() {
 
   return (
     <div className="flex flex-col py-10 px-10 text-2xl">
+      <h1><%= variables.ai_chat_title %></h1>
       {messages.map((m) => (
         <div key={m.id} className="whitespace-pre-wrap">
           {m.role === 'user' ? 'User: ' : 'AI: '}

templates/example/ai-chat/info.json

@@ -9,5 +9,19 @@
       "name": "AI Chat"
     }
   ],
-  "dependsOn": ["start"]
+  "dependsOn": ["start", "shadcn"],
+  "variables": [
+    {
+      "name": "ai_chat_title",
+      "default": "Your Amazing AI Chat",
+      "description": "The title of the AI chat.",
+      "type": "string"
+    },
+    {
+      "name": "ai_chat_system",
+      "default": "You are a helpful assistant.",
+      "description": "The system prompt of the AI chat.",
+      "type": "string"
+    }
+  ]
 }