handoff-app 1.1.3 → 1.2.0-0

package/src/app-builder/config-diff/strategies/pattern.ts

@@ -0,0 +1,65 @@
+import Handoff from '../../..';
+import { buildPatterns } from '../../../pipeline/patterns';
+import processComponents, { ComponentSegment } from '../../../transformers/preview/component/builder';
+import { Logger } from '../../../utils/logger';
+import { diffMapSnapshots, MapSnapshot, stableStringify } from '../snapshot';
+import { ConfigDiffStrategy } from '../types';
+
+/**
+ * Snapshots every __pattern_{patternId}_* synthetic preview entry across all
+ * components. Outer key is component id, inner key is synthetic preview key.
+ */
+const snapshotPatternSynthetics = (handoff: Handoff, patternId: string): MapSnapshot => {
+  const components = handoff.runtimeConfig?.entries?.components ?? {};
+  const prefix = `__pattern_${patternId}_`;
+  const result: MapSnapshot = new Map();
+
+  for (const [componentId, component] of Object.entries(components)) {
+    const previews = component.internalPatternPreviews ?? {};
+    const entries = new Map<string, string>();
+    for (const [key, preview] of Object.entries(previews)) {
+      if (key.startsWith(prefix)) {
+        entries.set(key, stableStringify(preview.values));
+      }
+    }
+    if (entries.size > 0) {
+      result.set(componentId, entries);
+    }
+  }
+
+  return result;
+};
+
+export const patternDiffStrategy: ConfigDiffStrategy = {
+  kind: 'pattern',
+
+  capture(handoff, entityId) {
+    const oldSnapshot = snapshotPatternSynthetics(handoff, entityId);
+
+    return {
+      async apply(handoff, entityIdAfterReload) {
+        const newSnapshot = entityIdAfterReload
+          ? snapshotPatternSynthetics(handoff, entityIdAfterReload)
+          : new Map();
+
+        const affectedIds = diffMapSnapshots(oldSnapshot, newSnapshot);
+        const displayId = entityIdAfterReload || entityId;
+
+        if (affectedIds.length > 0) {
+          Logger.debug(
+            `Pattern "${displayId}" changed: rebuilding ${affectedIds.length} affected component(s): ${affectedIds.join(', ')}`
+          );
+          for (const componentId of affectedIds) {
+            await processComponents(handoff, componentId, ComponentSegment.Previews);
+          }
+        } else {
+          Logger.debug(`Pattern "${displayId}" changed: no synthetic previews affected, skipping component rebuild.`);
+        }
+      },
+    };
+  },
+
+  async finalize(handoff) {
+    await buildPatterns(handoff);
+  },
+};

package/src/app-builder/config-diff/types.ts

@@ -0,0 +1,21 @@
+import Handoff from '../..';
+
+/**
+ * Handle returned by ConfigDiffStrategy.capture().
+ *
+ * Captures the pre-reload state in a closure so the snapshot type stays
+ * fully encapsulated and the watcher only sees this opaque handle.
+ */
+export interface RebuildHandle {
+  apply(handoff: Handoff, entityIdAfterReload: string | undefined): Promise<void>;
+}
+
+/**
+ * Encapsulates the snapshot -> reload -> diff -> selective-rebuild protocol
+ * for a single config-file entity kind.
+ */
+export interface ConfigDiffStrategy {
+  readonly kind: string;
+  capture(handoff: Handoff, entityId: string): RebuildHandle;
+  finalize(handoff: Handoff): Promise<void>;
+}

package/src/app-builder/watchers/component.ts

@@ -0,0 +1,72 @@
+import fs from 'fs-extra';
+import path from 'path';
+import Handoff from '../..';
+import { ComponentSegment } from '../../transformers/preview/component/builder';
+import { ComponentListObject } from '../../transformers/preview/types';
+import { normalizePathForCompare } from '../../utils/path';
+
+export type RuntimeComponentEntryType = keyof ComponentListObject['entries'];
+
+/**
+ * Maps configuration entry types to component segments.
+ */
+export const mapEntryTypeToSegment = (type: RuntimeComponentEntryType): ComponentSegment | undefined => {
+  return {
+    js: ComponentSegment.JavaScript,
+    scss: ComponentSegment.Style,
+    template: ComponentSegment.Previews,
+    templates: ComponentSegment.Previews,
+    component: ComponentSegment.Previews,
+    story: ComponentSegment.Previews,
+  }[type];
+};
+
+export const resolveComponentIdForChangedFile = (
+  handoff: Handoff,
+  changedFilePath: string
+): string | undefined => {
+  const normalizedChangedPath = normalizePathForCompare(changedFilePath);
+  const runtimeComponents = handoff.runtimeConfig?.entries?.components ?? {};
+
+  for (const [componentId, componentDef] of Object.entries(runtimeComponents)) {
+    const entries = componentDef.entries ?? {};
+    for (const entryPath of Object.values(entries)) {
+      if (!entryPath) continue;
+      const normalizedEntryPath = normalizePathForCompare(entryPath as string);
+      if (normalizedEntryPath === normalizedChangedPath) {
+        return componentId;
+      }
+    }
+  }
+
+  // Fallback for legacy path conventions when exact match is unavailable.
+  return path.basename(path.dirname(changedFilePath));
+};
+
+/**
+ * Gets the paths of runtime components to watch.
+ *
+ * @returns A map of paths to watch and their entry types.
+ */
+export const getRuntimeComponentsPathsToWatch = (
+  handoff: Handoff
+): Map<string, RuntimeComponentEntryType> => {
+  const result: Map<string, RuntimeComponentEntryType> = new Map();
+
+  for (const runtimeComponentId of Object.keys(handoff.runtimeConfig?.entries.components ?? {})) {
+    const runtimeComponent = handoff.runtimeConfig.entries.components[runtimeComponentId];
+    for (const [runtimeComponentEntryType, runtimeComponentEntryPath] of Object.entries(runtimeComponent.entries ?? {})) {
+      const normalizedComponentEntryPath = runtimeComponentEntryPath as string;
+      if (fs.existsSync(normalizedComponentEntryPath)) {
+        const entryType = runtimeComponentEntryType as RuntimeComponentEntryType;
+        if (fs.statSync(normalizedComponentEntryPath).isFile()) {
+          result.set(path.resolve(normalizedComponentEntryPath), entryType);
+        } else {
+          result.set(normalizedComponentEntryPath, entryType);
+        }
+      }
+    }
+  }
+
+  return result;
+};

package/src/app-builder/watchers/utils.ts

@@ -0,0 +1,44 @@
+import chokidar from 'chokidar';
+import { Logger } from '../../utils/logger';
+
+export interface WatcherState {
+  busy: boolean;
+  pendingHandlers: Map<string, () => Promise<void>>;
+  runtimeComponentsWatcher: chokidar.FSWatcher | null;
+  runtimeConfigurationWatcher: chokidar.FSWatcher | null;
+  componentDirectoriesWatcher: chokidar.FSWatcher | null;
+}
+
+/**
+ * Schedules a handler for execution with mutual exclusion and per-source
+ * coalescing. When the lock is free the handler runs immediately. When busy,
+ * only the latest handler per source key is kept.
+ */
+export const scheduleHandler = async (
+  state: WatcherState,
+  source: string,
+  handler: () => Promise<void>
+): Promise<void> => {
+  if (state.busy) {
+    state.pendingHandlers.set(source, handler);
+    return;
+  }
+
+  state.busy = true;
+  try {
+    await handler();
+    while (state.pendingHandlers.size > 0) {
+      const entries = Array.from(state.pendingHandlers.entries());
+      state.pendingHandlers.clear();
+      for (const [pendingSource, pendingHandler] of entries) {
+        try {
+          await pendingHandler();
+        } catch (e) {
+          Logger.error(`Unhandled error in scheduled handler for source "${pendingSource}":`, e);
+        }
+      }
+    }
+  } finally {
+    state.busy = false;
+  }
+};

package/src/app-builder/watchers.ts

@@ -2,21 +2,24 @@ import chokidar from 'chokidar';
 import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '..';
+import processComponents, { ComponentSegment } from '../transformers/preview/component/builder';
 import { buildMainCss } from '../transformers/preview/component/css';
 import { buildMainJS } from '../transformers/preview/component/javascript';
-import processComponents, { ComponentSegment } from '../transformers/preview/component/builder';
-import { ComponentListObject } from '../transformers/preview/types';
 import { Logger } from '../utils/logger';
 import { isPathInside, normalizePathForCompare } from '../utils/path';
 import { persistClientConfig } from './client-config';
+import { getStrategy, runAllFinalizers } from './config-diff';
 import { syncPublicFiles } from './paths';
+import {
+  getRuntimeComponentsPathsToWatch,
+  mapEntryTypeToSegment,
+  resolveComponentIdForChangedFile,
+  RuntimeComponentEntryType,
+} from './watchers/component';
+import { scheduleHandler, WatcherState } from './watchers/utils';
 
-export interface WatcherState {
-  debounce: boolean;
-  runtimeComponentsWatcher: chokidar.FSWatcher | null;
-  runtimeConfigurationWatcher: chokidar.FSWatcher | null;
-  componentDirectoriesWatcher: chokidar.FSWatcher | null;
-}
+export { getRuntimeComponentsPathsToWatch, mapEntryTypeToSegment } from './watchers/component';
+export type { WatcherState } from './watchers/utils';
 
 /**
  * Watches the working public directory for changes and updates the app.
@@ -28,18 +31,15 @@ export const watchPublicDirectory = (handoff: Handoff, wss: (msg: string) => voi
         case 'add':
         case 'change':
         case 'unlink':
-          if (!state.debounce) {
-            state.debounce = true;
+          await scheduleHandler(state, 'publicDirectory', async () => {
             try {
               Logger.warn('Public directory changed. Handoff will ingest the new data...');
               await syncPublicFiles(handoff);
               wss(JSON.stringify({ type: 'reload' }));
             } catch (e) {
               Logger.error('Error syncing public directory:', e);
-            } finally {
-              state.debounce = false;
             }
-          }
+          });
           break;
       }
     });
@@ -122,8 +122,7 @@ export const watchGlobalEntries = (handoff: Handoff, state: WatcherState, chokid
       case 'add':
       case 'change':
       case 'unlink':
-        if (!state.debounce) {
-          state.debounce = true;
+        await scheduleHandler(state, 'globalEntries', async () => {
           try {
             Logger.warn('Global entry changed. Rebuilding bundles and components...');
 
@@ -139,62 +138,23 @@ export const watchGlobalEntries = (handoff: Handoff, state: WatcherState, chokid
             }
 
             await processComponents(handoff);
+            await runAllFinalizers(handoff);
           } catch (e) {
             Logger.error('Error rebuilding after global entry change:', e);
-          } finally {
-            state.debounce = false;
           }
-        }
+        });
         break;
     }
   });
 };
 
-/**
- * Maps configuration entry types to component segments.
- */
-export const mapEntryTypeToSegment = (type: keyof ComponentListObject['entries']): ComponentSegment | undefined => {
-  return {
-    js: ComponentSegment.JavaScript,
-    scss: ComponentSegment.Style,
-    template: ComponentSegment.Previews,
-    templates: ComponentSegment.Previews,
-  }[type];
-};
-
-/**
- * Gets the paths of runtime components to watch.
- *
- * @returns A Map of paths to watch and their entry types
- */
-export const getRuntimeComponentsPathsToWatch = (handoff: Handoff) => {
-  const result: Map<string, keyof ComponentListObject['entries']> = new Map();
-
-  for (const runtimeComponentId of Object.keys(handoff.runtimeConfig?.entries.components ?? {})) {
-    const runtimeComponent = handoff.runtimeConfig.entries.components[runtimeComponentId];
-    for (const [runtimeComponentEntryType, runtimeComponentEntryPath] of Object.entries(runtimeComponent.entries ?? {})) {
-      const normalizedComponentEntryPath = runtimeComponentEntryPath as string;
-      if (fs.existsSync(normalizedComponentEntryPath)) {
-        const entryType = runtimeComponentEntryType as keyof ComponentListObject['entries'];
-        if (fs.statSync(normalizedComponentEntryPath).isFile()) {
-          result.set(path.resolve(normalizedComponentEntryPath), entryType);
-        } else {
-          result.set(normalizedComponentEntryPath, entryType);
-        }
-      }
-    }
-  }
-
-  return result;
-};
-
 /**
  * Watches runtime components for changes.
  */
 export const watchRuntimeComponents = (
   handoff: Handoff,
   state: WatcherState,
-  runtimeComponentPathsToWatch: Map<string, keyof ComponentListObject['entries']>
+  runtimeComponentPathsToWatch: Map<string, RuntimeComponentEntryType>
 ) => {
   if (state.runtimeComponentsWatcher) {
     state.runtimeComponentsWatcher.close();
@@ -202,7 +162,7 @@ export const watchRuntimeComponents = (
 
   if (runtimeComponentPathsToWatch.size > 0) {
     const pathsToWatch = Array.from(runtimeComponentPathsToWatch.keys());
-    const runtimeComponentEntryTypeByPath = new Map<string, keyof ComponentListObject['entries']>(
+    const runtimeComponentEntryTypeByPath = new Map<string, RuntimeComponentEntryType>(
       Array.from(runtimeComponentPathsToWatch.entries()).map(([watchPath, entryType]) => [normalizePathForCompare(watchPath), entryType])
     );
     const configFileSet = new Set(handoff.getConfigFilePaths().map((configPath) => normalizePathForCompare(configPath)));
@@ -220,20 +180,17 @@ export const watchRuntimeComponents = (
         case 'add':
         case 'change':
         case 'unlink':
-          if (!state.debounce) {
-            state.debounce = true;
+          await scheduleHandler(state, `runtimeComponent:${normalizedFile}`, async () => {
             try {
               const entryType = runtimeComponentEntryTypeByPath.get(normalizedFile);
-              const segmentToUpdate: ComponentSegment = entryType ? mapEntryTypeToSegment(entryType) : undefined;
-
-              const componentDir = path.basename(path.dirname(file));
-              await processComponents(handoff, componentDir, segmentToUpdate);
+              const segmentToUpdate: ComponentSegment | undefined = entryType ? mapEntryTypeToSegment(entryType) : undefined;
+              const componentId = resolveComponentIdForChangedFile(handoff, file);
+              await processComponents(handoff, componentId, segmentToUpdate);
+              await runAllFinalizers(handoff);
             } catch (e) {
               Logger.error('Error processing component:', e);
-            } finally {
-              state.debounce = false;
             }
-          }
+          });
           break;
       }
     });
@@ -242,6 +199,11 @@ export const watchRuntimeComponents = (
 
 /**
  * Watches the runtime configuration for changes.
+ *
+ * Uses the generic {@link ConfigDiffStrategy} registry so that each entity
+ * kind (patterns today, potentially themes / slots later) supplies its own
+ * snapshot → diff → selective-rebuild logic without the watcher needing to
+ * know the details.
  */
 export const watchRuntimeConfiguration = (handoff: Handoff, state: WatcherState) => {
   if (state.runtimeConfigurationWatcher) {
@@ -251,24 +213,47 @@ export const watchRuntimeConfiguration = (handoff: Handoff, state: WatcherState)
   if (handoff.getConfigFilePaths().length > 0) {
     state.runtimeConfigurationWatcher = chokidar.watch(handoff.getConfigFilePaths(), { ignoreInitial: true });
     state.runtimeConfigurationWatcher.on('all', async (event, file) => {
+      const normalizedFile = normalizePathForCompare(file);
       switch (event) {
         case 'add':
         case 'change':
         case 'unlink':
-          if (!state.debounce) {
-            state.debounce = true;
+          await scheduleHandler(state, `runtimeConfig:${normalizedFile}`, async () => {
             try {
-              file = path.dirname(file);
+              const changedFile = file;
+
+              // Look up the entity this config file belongs to BEFORE reload.
+              const entryBefore = handoff.getConfigFileEntry(changedFile);
+              const strategy = entryBefore ? getStrategy(entryBefore.kind) : undefined;
+              const handle =
+                entryBefore && strategy ? strategy.capture(handoff, entryBefore.entityId) : undefined;
+
               handoff.reload();
               await persistClientConfig(handoff);
               watchRuntimeComponents(handoff, state, getRuntimeComponentsPathsToWatch(handoff));
-              await processComponents(handoff, path.basename(file));
+              watchRuntimeConfiguration(handoff, state);
+
+              const entryAfter = handoff.getConfigFileEntry(changedFile);
+
+              const normalizedChanged = normalizePathForCompare(changedFile);
+              const normalizedMainConfig = handoff.getMainConfigFilePath()
+                ? normalizePathForCompare(handoff.getMainConfigFilePath() as string)
+                : undefined;
+
+              if (normalizedMainConfig && normalizedChanged === normalizedMainConfig) {
+                await processComponents(handoff);
+              } else if (handle) {
+                await handle.apply(handoff, entryAfter?.entityId);
+              } else {
+                const effectiveId = entryAfter?.entityId ?? path.basename(path.dirname(changedFile));
+                await processComponents(handoff, effectiveId);
+              }
+
+              await runAllFinalizers(handoff);
             } catch (e) {
               Logger.error('Error reloading runtime configuration:', e);
-            } finally {
-              state.debounce = false;
             }
-          }
+          });
           break;
       }
     });
@@ -315,14 +300,12 @@ export const watchComponentDirectories = (handoff: Handoff, state: WatcherState,
 
     if (!isNewComponent) return;
 
-    if (!state.debounce) {
-      state.debounce = true;
+    await scheduleHandler(state, `newComponent:${dirName}`, async () => {
       try {
         Logger.warn(`New component detected: ${dirName}. Reloading configuration...`);
         handoff.reload();
         knownComponents.add(dirName);
 
-        // Update known set with all current components
         for (const id of Object.keys(handoff.runtimeConfig?.entries?.components ?? {})) {
           knownComponents.add(id);
         }
@@ -331,11 +314,10 @@ export const watchComponentDirectories = (handoff: Handoff, state: WatcherState,
         watchRuntimeComponents(handoff, state, getRuntimeComponentsPathsToWatch(handoff));
         watchRuntimeConfiguration(handoff, state);
         await processComponents(handoff, dirName);
+        await runAllFinalizers(handoff);
       } catch (e) {
         Logger.error('Error processing new component:', e);
-      } finally {
-        state.debounce = false;
       }
-    }
+    });
   });
 };

package/src/cache/build-cache.ts

@@ -176,8 +176,8 @@ export function getComponentFilePaths(handoff: Handoff, componentId: string): {
       files.push(entries.scss);
       componentDirs.add(normalizePathForCompare(path.dirname(entries.scss)));
     }
-    // Handle both 'template' (singular) and 'templates' (plural) entry types
-    const templatePath = entries.template || entries.templates;
+    // Handle template-style entries across renderer families
+    const templatePath = entries.template || entries.templates || entries.component || entries.story;
     if (templatePath) {
       try {
         const stat = fs.statSync(templatePath);
@@ -198,10 +198,19 @@ export function getComponentFilePaths(handoff: Handoff, componentId: string): {
 
   // Find the config file path for this component using exact config filename + directory matching.
   const configPaths = handoff.getConfigFilePaths();
-  const expectedConfigFileNames = new Set([`${componentId}.json`, `${componentId}.js`, `${componentId}.cjs`]);
+  const expectedConfigFileNames = new Set([
+    `${componentId}.handoff.ts`,
+    `${componentId}.handoff.js`,
+    `${componentId}.handoff.cjs`,
+    `${componentId}.handoff.json`,
+    `${componentId}.json`,
+    `${componentId}.js`,
+    `${componentId}.cjs`,
+  ]);
   const matchingConfigPath = configPaths.find((configPath) => {
     const configFileName = path.basename(configPath);
-    if (!expectedConfigFileNames.has(configFileName)) {
+    const isModernDeclaration = /\.handoff\.(ts|js|cjs|json)$/.test(configFileName);
+    if (!expectedConfigFileNames.has(configFileName) && !isModernDeclaration) {
       return false;
     }
 
@@ -240,7 +249,7 @@ export async function computeComponentFileStates(
 
   let templateDirFiles: Record<string, FileState> | undefined;
   if (templateDir) {
-    templateDirFiles = await computeDirectoryState(templateDir, ['.hbs', '.html', '.tsx', '.ts']);
+    templateDirFiles = await computeDirectoryState(templateDir, ['.hbs', '.html', '.tsx', '.ts', '.jsx', '.js']);
   }
 
   return { files, templateDirFiles };

package/src/cli/create.ts

@@ -21,7 +21,9 @@ interface CreateOptions {
   projectName: string;
   figmaProjectId: string;
   figmaAccessToken: string;
-  [key: string]: string; // Allow dynamic access for template replacement
+  languagePreference: 'typescript' | 'javascript';
+  includeExamples: boolean;
+  [key: string]: string | boolean; // Allow dynamic access for template replacement
 }
 
 class CreateError extends Error {
@@ -63,23 +65,44 @@ interface TemplateConfig {
  * Get mandatory templates based on whether examples are included
  * Uses different handoff config templates for blank vs. with-examples projects
  */
-const getMandatoryTemplates = (includeExamples: boolean): TemplateConfig[] => [
-  { source: 'package.json.tpl', destination: 'package.json' },
-  { 
-    source: includeExamples ? 'handoff.config.with-examples.js.tpl' : 'handoff.config.js.tpl', 
-    destination: 'handoff.config.js' 
-  },
-  { source: 'tsconfig.json.tpl', destination: 'tsconfig.json' },
-  { source: 'gitignore.tpl', destination: '.gitignore' },
-  { source: 'env.tpl', destination: '.env' },
-  { source: 'README.md.tpl', destination: 'README.md' },
-];
-
-// Example component files (only included when user opts for examples)
-const exampleTemplates: TemplateConfig[] = [
-  { source: 'components/button/Button.tsx.tpl', destination: 'components/button/Button.tsx', isExample: true },
-  { source: 'components/button/button.js.tpl', destination: 'components/button/button.js', isExample: true },
-];
+const getMandatoryTemplates = (
+  includeExamples: boolean,
+  languagePreference: 'typescript' | 'javascript'
+): TemplateConfig[] => {
+  const configFormat = languagePreference;
+  const configTemplateBaseName = includeExamples ? 'handoff.config.with-examples' : 'handoff.config';
+  const configTemplateSource = `${configTemplateBaseName}.${configFormat === 'typescript' ? 'ts' : 'js'}.tpl`;
+  const configDestination = `handoff.config.${configFormat === 'typescript' ? 'ts' : 'js'}`;
+
+  const templates: TemplateConfig[] = [
+    { source: 'package.json.tpl', destination: 'package.json' },
+    {
+      source: configTemplateSource,
+      destination: configDestination,
+    },
+    { source: 'gitignore.tpl', destination: '.gitignore' },
+    { source: 'env.tpl', destination: '.env' },
+    { source: 'README.md.tpl', destination: 'README.md' },
+  ];
+
+  if (languagePreference === 'typescript') {
+    templates.push({ source: 'tsconfig.json.tpl', destination: 'tsconfig.json' });
+  }
+
+  return templates;
+};
+
+const getExampleTemplates = (languagePreference: 'typescript' | 'javascript'): TemplateConfig[] => {
+  const declarationSuffix = languagePreference === 'typescript' ? 'ts' : 'js';
+  const declarationFile = `components/button/button.react.handoff.${declarationSuffix}.tpl`;
+  const componentFile =
+    languagePreference === 'typescript' ? 'components/button/Button.tsx.tpl' : 'components/button/Button.jsx.tpl';
+
+  return [
+    { source: declarationFile, destination: `components/button/button.handoff.${languagePreference === 'typescript' ? 'ts' : 'js'}`, isExample: true },
+    { source: componentFile, destination: `components/button/Button.${languagePreference === 'typescript' ? 'tsx' : 'jsx'}`, isExample: true },
+  ];
+};
 
 /**
  * Render a template string by replacing placeholders with values
@@ -89,19 +112,39 @@ const renderTemplate = (content: string, data: CreateOptions): string => {
     if (!(key in data)) {
       console.warn(chalk.yellow(`Warning: Unknown template placeholder '{{${key}}}'`));
     }
-    return data[key] || '';
+    const value = data[key];
+    return typeof value === 'string' ? value : '';
   });
 };
 
+const getDependenciesToInstall = (options: CreateOptions): { dependencies: string[]; devDependencies: string[] } => {
+  const dependencies = ['handoff-app@latest'];
+  const devDependencies: string[] = [];
+
+  if (options.includeExamples) {
+    dependencies.push('react', 'react-dom');
+    if (options.languagePreference === 'typescript') {
+      devDependencies.push('@types/react', '@types/react-dom');
+    }
+  }
+
+  return { dependencies, devDependencies };
+};
+
 /**
- * Execute npm install
+ * Execute npm install for required dependencies.
  */
-const runNpmInstall = async (projectPath: string): Promise<void> => {
+const installDependencies = async (projectPath: string, options: CreateOptions): Promise<void> => {
+  const { dependencies, devDependencies } = getDependenciesToInstall(options);
   const spinner = p.spinner();
   spinner.start('Installing dependencies...');
 
   return new Promise((resolve, reject) => {
-    const npmProcess = spawn('npm', ['install'], {
+    const installCommand = devDependencies.length
+      ? `npm install --save-prefix="^" ${dependencies.join(' ')} && npm install --save-dev --save-prefix="^" ${devDependencies.join(' ')}`
+      : `npm install --save-prefix="^" ${dependencies.join(' ')}`;
+
+    const npmProcess = spawn(installCommand, {
       cwd: projectPath,
       stdio: 'pipe',
       shell: true,
@@ -204,6 +247,22 @@ const create = async (): Promise<void> => {
 
     const includeExamples = projectType === 'with-examples';
 
+    const languagePreferenceSelection = await p.select({
+      message: 'Preferred project language (declarations, examples, and handoff.config)?',
+      options: [
+        { value: 'typescript', label: 'TypeScript', hint: 'Uses .handoff.ts and handoff.config.ts' },
+        { value: 'javascript', label: 'JavaScript', hint: 'Uses .handoff.js and handoff.config.js' },
+      ],
+      initialValue: 'typescript',
+    });
+
+    if (p.isCancel(languagePreferenceSelection)) {
+      p.cancel('Project creation cancelled.');
+      process.exit(0);
+    }
+
+    const languagePreference = languagePreferenceSelection as 'typescript' | 'javascript';
+
     // Get Figma project ID
     p.log.step(chalk.blue('Figma Configuration'));
     const figmaProjectId = await p.text({
@@ -234,6 +293,8 @@ const create = async (): Promise<void> => {
       projectName: projectName as string,
       figmaProjectId: ((figmaProjectId as string) || '').trim(),
       figmaAccessToken: ((figmaAccessToken as string) || '').trim(),
+      languagePreference,
+      includeExamples,
     };
 
     // Create files
@@ -248,8 +309,8 @@ const create = async (): Promise<void> => {
 
     // Combine mandatory templates with example templates based on user choice
     const templates = [
-      ...getMandatoryTemplates(includeExamples),
-      ...(includeExamples ? exampleTemplates : []),
+      ...getMandatoryTemplates(includeExamples, languagePreference),
+      ...(includeExamples ? getExampleTemplates(languagePreference) : []),
     ];
 
     try {
@@ -273,7 +334,7 @@ const create = async (): Promise<void> => {
     }
 
     // Install dependencies
-    await runNpmInstall(projectPath);
+    await installDependencies(projectPath, options);
 
     // Success message
     const nextSteps = [`cd ${projectName}`];