feat(create): prompt and seed add-on environment variables

Author: tannerlinsley

packages/cli/src/command-line.ts

@@ -231,6 +231,8 @@ export async function normalizeOptions(
 
   ;(normalized as Options & { includeExamples?: boolean }).includeExamples =
     includeExamples
+  ;(normalized as Options & { envVarValues?: Record<string, string> }).envVarValues =
+    {}
 
   return normalized
 }

packages/cli/src/options.ts

@@ -11,6 +11,7 @@ import {
 import {
   getProjectName,
   promptForAddOnOptions,
+  promptForEnvVars,
   selectAddOns,
   selectDeployment,
   selectExamples,
@@ -169,6 +170,13 @@ export async function promptForCreateOptions(
     options.addOnOptions = { ...defaultOptions, ...userOptions }
   }
 
+  // Prompt for env vars exposed by selected add-ons in interactive mode
+  const envVarValues = Array.isArray(cliOptions.addOns)
+    ? {}
+    : await promptForEnvVars(options.chosenAddOns)
+  ;(options as Required<Options> & { envVarValues?: Record<string, string> }).envVarValues =
+    envVarValues
+
   options.git = cliOptions.git ?? (await selectGit())
   if (cliOptions.install === false) {
     options.install = false

packages/cli/src/ui-prompts.ts

@@ -4,6 +4,7 @@ import {
   isCancel,
   multiselect,
   note,
+  password,
   select,
   text,
 } from '@clack/prompts'
@@ -251,6 +252,69 @@ export async function promptForAddOnOptions(
   return addOnOptions
 }
 
+export async function promptForEnvVars(
+  addOns: Array<AddOn>,
+): Promise<Record<string, string>> {
+  const envVars = new Map<
+    string,
+    {
+      name: string
+      description?: string
+      required?: boolean
+      default?: string
+      secret?: boolean
+    }
+  >()
+
+  for (const addOn of addOns as Array<any>) {
+    for (const envVar of addOn.envVars || []) {
+      if (!envVars.has(envVar.name)) {
+        envVars.set(envVar.name, envVar)
+      }
+    }
+  }
+
+  const result: Record<string, string> = {}
+
+  for (const envVar of envVars.values()) {
+    const label = envVar.description
+      ? `${envVar.name} (${envVar.description})`
+      : envVar.name
+
+    const value = envVar.secret
+      ? await password({
+          message: `Enter ${label}`,
+          validate: envVar.required
+            ? (v) =>
+                v && v.trim().length > 0
+                  ? undefined
+                  : `${envVar.name} is required`
+            : undefined,
+        })
+      : await text({
+          message: `Enter ${label}`,
+          defaultValue: envVar.default,
+          validate: envVar.required
+            ? (v) =>
+                v && v.trim().length > 0
+                  ? undefined
+                  : `${envVar.name} is required`
+            : undefined,
+        })
+
+    if (isCancel(value)) {
+      cancel('Operation cancelled.')
+      process.exit(0)
+    }
+
+    if (value && value.trim()) {
+      result[envVar.name] = value.trim()
+    }
+  }
+
+  return result
+}
+
 export async function selectDeployment(
   framework: Framework,
   deployment?: string,

packages/create/src/create-app.ts

@@ -280,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) {
@@ -331,6 +357,7 @@ export async function createApp(environment: Environment, options: Options) {
 
   environment.startRun()
   await writeFiles(environment, effectiveOptions)
+  await seedEnvValues(environment, effectiveOptions)
   await runCommandsAndInstallDependencies(environment, effectiveOptions)
   environment.finishRun()
 

packages/create/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"
+    }
   ]
 }

packages/create/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"
+    }
   ]
 }

packages/create/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(),
 })
 
@@ -208,6 +220,7 @@ export interface Options {
   starter?: Starter | undefined
   routerOnly?: boolean
   includeExamples?: boolean
+  envVarValues?: Record<string, string>
 }
 
 export type SerializedOptions = Omit<