handoff-app 1.1.3 → 1.2.0-0

package/src/cli/eject.ts

@@ -1,3 +1,4 @@
+import * as p from '@clack/prompts';
 import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '../index';
@@ -8,14 +9,35 @@ import { Logger } from '../utils/logger';
  * @param handoff
  */
 export const ejectConfig = async (handoff: Handoff) => {
-  const configPath = path.resolve(path.join(handoff.workingPath, 'handoff.config.js'));
-  if (fs.existsSync(configPath)) {
-    if (!handoff.force) {
-      Logger.error(`Config file already exists. Use "--force" to overwrite.`);
-    }
+  const existingConfigNames = ['handoff.config.ts', 'handoff.config.js', 'handoff.config.cjs', 'handoff.config.json'];
+  const existingConfigPaths = existingConfigNames
+    .map((name) => path.resolve(path.join(handoff.workingPath, name)))
+    .filter((filePath) => fs.existsSync(filePath));
+  if (existingConfigPaths.length > 0 && !handoff.force) {
+    Logger.error(`Config file already exists. Use "--force" to overwrite.`);
+    return handoff;
   }
-  // load the template as a string
-  const template = fs.readFileSync(path.resolve(handoff.modulePath, 'config/config.template.js'), 'utf8');
+
+  const defaultFormat = fs.existsSync(path.resolve(handoff.workingPath, 'tsconfig.json')) ? 'typescript' : 'javascript';
+  const formatSelection = await p.select({
+    message: 'Which config format would you like to eject?',
+    options: [
+      { value: 'typescript', label: 'TypeScript', hint: 'Generates handoff.config.ts' },
+      { value: 'javascript', label: 'JavaScript', hint: 'Generates handoff.config.js' },
+    ],
+    initialValue: defaultFormat,
+  });
+
+  if (p.isCancel(formatSelection)) {
+    Logger.warn('Config eject cancelled.');
+    return handoff;
+  }
+
+  const useTypeScript = formatSelection === 'typescript';
+  const configPath = path.resolve(path.join(handoff.workingPath, useTypeScript ? 'handoff.config.ts' : 'handoff.config.js'));
+  const templatePath = path.resolve(handoff.modulePath, useTypeScript ? 'config/config.template.ts' : 'config/config.template.js');
+
+  const template = fs.readFileSync(templatePath, 'utf8');
   fs.writeFileSync(configPath, template);
   Logger.success(`Config ejected to ${configPath}`);
   return handoff;

package/src/cli/make.ts

@@ -123,7 +123,7 @@ export const makeComponent = async (handoff: Handoff, name: string) => {
   } else {
     componentsRoot = path.resolve(handoff.workingPath, DEFAULT_COMPONENTS_DIR);
     Logger.warn(
-      `No entries.components configured in handoff.config.js. ` +
+      `No entries.components configured in handoff.config.*. ` +
       `Scaffolding into "${DEFAULT_COMPONENTS_DIR}/". ` +
       `Add this path to entries.components in your config so the build picks it up.`
     );
@@ -146,10 +146,6 @@ export const makeComponent = async (handoff: Handoff, name: string) => {
   fs.writeFileSync(targetHtml, htmlTemplate);
   Logger.success(`New component ${name}.hbs was created in ${workingPath}`);
 
-  const jsonpath = path.resolve(templatePath, 'template.json');
-  const jsonTemplate = fs.readFileSync(jsonpath, 'utf8');
-  fs.writeFileSync(path.resolve(workingPath, `${name}.json`), jsonTemplate);
-
   const writeJSFile = await p.confirm({
     message: `Generate a supporting javascript file ${name}.js?`,
     initialValue: false,
@@ -172,5 +168,36 @@ export const makeComponent = async (handoff: Handoff, name: string) => {
     fs.writeFileSync(path.resolve(workingPath, `${name}.scss`), scssTemplate);
   }
 
+  const declarationEntries = [`template: './${name}.hbs'`];
+  if (writeJSFile === true) {
+    declarationEntries.push(`js: './${name}.js'`);
+  }
+  if (writeSassFile === true) {
+    declarationEntries.push(`scss: './${name}.scss'`);
+  }
+
+  const declarationContent = `const { defineHandlebarsComponent } = require('handoff-app');
+
+module.exports = defineHandlebarsComponent({
+  id: '${name}',
+  name: '',
+  description: '',
+  group: '',
+  type: 'element',
+  entries: {
+    ${declarationEntries.join(',\n    ')}
+  },
+  previews: {
+    default: {
+      title: 'Default',
+      args: {}
+    }
+  }
+});
+`;
+
+  fs.writeFileSync(path.resolve(workingPath, `${name}.handoff.js`), declarationContent);
+  Logger.success(`New component declaration ${name}.handoff.js was created in ${workingPath}`);
+
   return handoff;
 };

package/src/cli/scaffold.ts

@@ -5,9 +5,8 @@ import path from 'path';
 import Handoff from '../index';
 
 // Constants
-const CONFIG_FILES = ['handoff.config.json', 'handoff.config.js', 'handoff.config.cjs'] as const;
+const CONFIG_FILES = ['handoff.config.ts', 'handoff.config.js', 'handoff.config.cjs', 'handoff.config.json'] as const;
 const COMPONENTS_DIR = 'components';
-const DEFAULT_VERSION = '1.0.0';
 const DEFAULT_GROUPS = [
   { value: 'Atomic Elements', label: 'Atomic Elements' },
   { value: 'Forms', label: 'Forms' },
@@ -47,27 +46,50 @@ const toTitleCase = (str: string): string => {
  * Generate the component JS stub content
  */
 const generateComponentStub = (config: ComponentConfig): string => {
-  // Build entries object with relative paths to generated files
   const entriesLines: string[] = [];
   if (config.generateTsx) {
-    entriesLines.push(`    template: './${config.name}.tsx',`);
+    entriesLines.push(`    component: './${config.name}.tsx',`);
+  } else {
+    entriesLines.push(`    template: './${config.name}.hbs',`);
   }
   if (config.generateScss) {
     entriesLines.push(`    scss: './${config.name}.scss',`);
   }
 
-  const entriesBlock = entriesLines.length > 0
-    ? `  entries: {\n${entriesLines.join('\n')}\n  },\n`
-    : '';
-
-  return `/** @type {import('handoff-app').Component} */
-module.exports = {
-  title: "${config.title}",
+  const commonMetadata = `  id: "${config.name}",
+  name: "${config.title}",
   description: "${config.description}",
   group: "${config.group}",
   type: "element",
-  figmaComponentId: "${config.name}",
-${entriesBlock}};
+  figmaComponentId: "${config.name}",`;
+
+  if (config.generateTsx) {
+    return `const { defineReactComponent } = require('handoff-app');
+const ${toTitleCase(config.name).replace(/\s/g, '')} = require('./${config.name}').default;
+
+module.exports = defineReactComponent(${toTitleCase(config.name).replace(/\s/g, '')}, {
+${commonMetadata}
+  entries: {
+${entriesLines.join('\n')}
+  },
+  previews: {
+    default: { title: "Default", args: {} }
+  }
+});
+`;
+  }
+
+  return `const { defineHandlebarsComponent } = require('handoff-app');
+
+module.exports = defineHandlebarsComponent({
+${commonMetadata}
+  entries: {
+${entriesLines.join('\n')}
+  },
+  previews: {
+    default: { title: "Default", args: {} }
+  }
+});
 `;
 };
 
@@ -252,8 +274,8 @@ const updateConfigFile = async (
     return { success: true, isJsConfig: false, configPath, skipped: false };
   }
 
-  // For JS/CJS config files, try to update them programmatically
-  if (configFile.endsWith('.js') || configFile.endsWith('.cjs')) {
+  // For code config files, try to update them programmatically
+  if (configFile.endsWith('.ts') || configFile.endsWith('.js') || configFile.endsWith('.cjs')) {
     try {
       let content = await fs.readFile(configPath, 'utf8');
 
@@ -309,7 +331,7 @@ const updateConfigFile = async (
         return { success: true, isJsConfig: true, configPath, skipped: false };
       }
       
-      // No entries object, try to add it before the closing of module.exports
+      // No entries object, try to add it before the closing of exported object
       const formattedArray = formatComponentsArray(newComponentPaths);
       const entriesBlock = `  entries: {\n    components: ${formattedArray},\n  },\n`;
       
@@ -322,6 +344,26 @@ const updateConfigFile = async (
         await fs.writeFile(configPath, content, 'utf8');
         return { success: true, isJsConfig: true, configPath, skipped: false };
       }
+
+      // Try to insert after export default {
+      if (/export\s+default\s+\{/.test(content)) {
+        content = content.replace(
+          /(export\s+default\s+\{)/,
+          `$1\n${entriesBlock}`
+        );
+        await fs.writeFile(configPath, content, 'utf8');
+        return { success: true, isJsConfig: true, configPath, skipped: false };
+      }
+
+      // Try to insert into defineConfig({ ... })
+      if (/defineConfig\s*\(\s*\{/.test(content)) {
+        content = content.replace(
+          /(defineConfig\s*\(\s*\{)/,
+          `$1\n${entriesBlock}`
+        );
+        await fs.writeFile(configPath, content, 'utf8');
+        return { success: true, isJsConfig: true, configPath, skipped: false };
+      }
       
       // Fallback: couldn't parse the JS config
       return { success: false, isJsConfig: true, configPath, skipped: false };
@@ -344,15 +386,14 @@ const createComponentFiles = async (
   const componentDir = path.resolve(
     handoff.workingPath,
     COMPONENTS_DIR,
-    config.name,
-    DEFAULT_VERSION
+    config.name
   );
 
   // Ensure directory exists
   await fs.ensureDir(componentDir);
 
-  // Create the main component JS file
-  const jsPath = path.join(componentDir, `${config.name}.js`);
+  // Create the main component declaration file
+  const jsPath = path.join(componentDir, `${config.name}.handoff.js`);
   await fs.writeFile(jsPath, generateComponentStub(config));
   createdFiles.push(jsPath);
 
@@ -361,6 +402,12 @@ const createComponentFiles = async (
     const tsxPath = path.join(componentDir, `${config.name}.tsx`);
     await fs.writeFile(tsxPath, generateReactComponentStub(config.name, config.variantProps));
     createdFiles.push(tsxPath);
+  } else {
+    const hbsTemplatePath = path.resolve(handoff.modulePath, 'config/templates/component/template.hbs');
+    const hbsTemplate = await fs.readFile(hbsTemplatePath, 'utf8');
+    const hbsPath = path.join(componentDir, `${config.name}.hbs`);
+    await fs.writeFile(hbsPath, hbsTemplate);
+    createdFiles.push(hbsPath);
   }
 
   // Optionally create SCSS file
@@ -380,7 +427,7 @@ const displayComponentPreview = (config: ComponentConfig): void => {
   const stub = generateComponentStub(config);
   const lines = stub.split('\n');
   const preview = lines.slice(0, 12).join('\n') + '\n  ...\n};';
-  p.note(preview, `Preview: ${config.name}.js`);
+  p.note(preview, `Preview: ${config.name}.handoff.js`);
 };
 
 /**

package/src/cli.ts

@@ -19,7 +19,7 @@ class HandoffCliError extends Error {
  * Show the help message
  */
 const showVersion = () => {
-  return 'Handoff App - 1.1.3';
+  return 'Handoff App - 1.2.0-0';
 };
 
 /**

package/src/config/README.md

@@ -7,7 +7,7 @@ Handles loading, validation, and resolution of handoff configuration.
 | File | Purpose |
 |------|---------|
 | `defaults.ts` | Default config values and `getClientConfig()` for the Next.js app |
-| `loader.ts` | `initConfig()` — reads `handoff.config.json/.js/.cjs` and merges overrides |
+| `loader.ts` | `initConfig()` — reads `handoff.config.ts/.js/.cjs/.json` (in that order), warns on conflicts, and merges overrides |
 | `runtime.ts` | `initRuntimeConfig()` — resolves component entries, SCSS/JS paths, transformer options |
 | `validator.ts` | `validateConfig()` — ensures required Figma credentials are present |
 | `index.ts` | Barrel re-exports |
@@ -21,3 +21,12 @@ const config = initConfig(overrides);
 const [runtimeConfig, configPaths] = initRuntimeConfig({ config, workingPath });
 const validated = validateConfig(config);
 ```
+
+## Main Config Precedence
+
+When multiple main config files exist in the project root, Handoff picks the first match in this order and warns about ignored files:
+
+1. `handoff.config.ts`
+2. `handoff.config.js`
+3. `handoff.config.cjs`
+4. `handoff.config.json`

package/src/config/helpers.ts

@@ -0,0 +1,43 @@
+import { Config } from '../types/config';
+
+const normalizeAppConfig = (app?: Config['app']): Config['app'] => {
+  if (!app) return app;
+
+  const {
+    googleTagManager,
+    typeCopy,
+    typeSort,
+    colorSort,
+    componentSort,
+    basePath,
+    ...rest
+  } = app;
+
+  return {
+    ...rest,
+    google_tag_manager: googleTagManager ?? app.google_tag_manager,
+    type_copy: typeCopy ?? app.type_copy,
+    type_sort: typeSort ?? app.type_sort,
+    color_sort: colorSort ?? app.color_sort,
+    component_sort: componentSort ?? app.component_sort,
+    base_path: basePath ?? app.base_path,
+  };
+};
+
+export const normalizeConfig = (config: Config): Config => {
+  const { devAccessToken, figmaProjectId, assetsZipLinks, app, ...rest } = config;
+
+  return {
+    ...(rest as Config),
+    dev_access_token: devAccessToken ?? config.dev_access_token,
+    figma_project_id: figmaProjectId ?? config.figma_project_id,
+    assets_zip_links: assetsZipLinks ?? config.assets_zip_links,
+    app: normalizeAppConfig(app),
+  };
+};
+
+/**
+ * Optional helper for strongly-typed config authoring.
+ * It normalizes modern camelCase keys to legacy runtime keys.
+ */
+export const defineConfig = (config: Config): Config => normalizeConfig(config);

package/src/config/index.ts

@@ -3,7 +3,10 @@ export { defaultConfig, getClientConfig } from './defaults';
 export type { ImageStyle } from './defaults';
 
 // Config file loading
-export { initConfig } from './loader';
+export { initConfig, initConfigWithMetadata } from './loader';
+
+// Config helpers
+export { defineConfig } from './helpers';
 
 // Runtime config resolution
 export { initRuntimeConfig } from './runtime';

package/src/config/loader.ts

@@ -1,48 +1,127 @@
+import esbuild from 'esbuild';
 import fs from 'fs-extra';
+import { createRequire } from 'module';
 import path from 'path';
 import { Config } from '../types/config';
+import { Logger } from '../utils/logger';
 import { defaultConfig } from './defaults';
 
+const CONFIG_FILE_PREFERENCE = [
+  'handoff.config.ts',
+  'handoff.config.js',
+  'handoff.config.cjs',
+  'handoff.config.json',
+] as const;
+
+type ConfigLoadResult = {
+  config: Config;
+  configPath?: string;
+};
+
+const evaluateTypeScriptConfig = (filePath: string, handoffModulePath: string): any => {
+  const buildResult = esbuild.buildSync({
+    entryPoints: [filePath],
+    bundle: true,
+    write: false,
+    platform: 'node',
+    format: 'cjs',
+    target: 'node16',
+    logLevel: 'silent',
+    external: ['handoff-app'],
+  });
+
+  const code = buildResult.outputFiles?.[0]?.text;
+  if (!code) {
+    throw new Error(`Unable to compile config file "${filePath}"`);
+  }
+
+  const mod: any = { exports: {} };
+  const localRequire = createRequire(filePath);
+  const handoffRequire = createRequire(path.resolve(handoffModulePath, 'package.json'));
+  const runtimeRequire = (id: string) => {
+    try {
+      return localRequire(id);
+    } catch {
+      return handoffRequire(id);
+    }
+  };
+  const evaluator = new Function('require', 'module', 'exports', '__filename', '__dirname', code);
+  evaluator(runtimeRequire, mod, mod.exports, filePath, path.dirname(filePath));
+  return mod.exports;
+};
+
+const loadConfigFile = (configPath: string): Config => {
+  if (configPath.endsWith('.json')) {
+    const buffer = fs.readFileSync(configPath);
+    return JSON.parse(buffer.toString()) as Config;
+  }
+
+  if (configPath.endsWith('.ts')) {
+    const handoffModulePath = path.resolve(__dirname, '../..');
+    const importedConfig = evaluateTypeScriptConfig(configPath, handoffModulePath);
+    return (importedConfig.default || importedConfig) as Config;
+  }
+
+  // Invalidate require cache to ensure fresh read
+  delete require.cache[require.resolve(configPath)];
+  const importedConfig = require(configPath);
+  return (importedConfig.default || importedConfig) as Config;
+};
+
+const resolveConfigFilePath = (): { selected?: string; ignored: string[] } => {
+  const existing = CONFIG_FILE_PREFERENCE
+    .map((fileName) => path.resolve(process.cwd(), fileName))
+    .filter((filePath) => fs.existsSync(filePath));
+
+  if (!existing.length) {
+    return { selected: undefined, ignored: [] };
+  }
+
+  const [selected, ...ignored] = existing;
+  return { selected, ignored };
+};
+
 /**
- * Loads the handoff configuration from the project root.
- *
- * Searches for config files in order: handoff.config.json, handoff.config.js, handoff.config.cjs.
- * Merges file config with any provided overrides, then applies defaults for missing values.
- *
- * @param configOverride - Optional partial config to override file-loaded values.
- * @returns The fully resolved Config object.
+ * Loads the handoff configuration from the project root and returns metadata.
  */
-export const initConfig = (configOverride?: Partial<Config>): Config => {
-  let config = {};
-
-  const possibleConfigFiles = ['handoff.config.json', 'handoff.config.js', 'handoff.config.cjs'];
-
-  // Find the first existing config file
-  const configFile = possibleConfigFiles.find((file) => fs.existsSync(path.resolve(process.cwd(), file)));
-
-  if (configFile) {
-    const configPath = path.resolve(process.cwd(), configFile);
-    if (configFile.endsWith('.json')) {
-      const defBuffer = fs.readFileSync(configPath);
-      config = JSON.parse(defBuffer.toString()) as Config;
-    } else if (configFile.endsWith('.js') || configFile.endsWith('.cjs')) {
-      // Invalidate require cache to ensure fresh read
-      delete require.cache[require.resolve(configPath)];
-      const importedConfig = require(configPath);
-      config = importedConfig.default || importedConfig;
-    }
+export const initConfigWithMetadata = (configOverride?: Partial<Config>): ConfigLoadResult => {
+  let config: Partial<Config> = {};
+  const { selected: configPath, ignored } = resolveConfigFilePath();
+
+  if (ignored.length > 0 && configPath) {
+    Logger.warn(
+      `Multiple config files found. Using "${path.basename(configPath)}" and ignoring: ${ignored
+        .map((filePath) => `"${path.basename(filePath)}"`)
+        .join(', ')}.`
+    );
+  }
+
+  if (configPath) {
+    config = loadConfigFile(configPath);
   }
 
   // Apply overrides if provided
   if (configOverride) {
-    Object.keys(configOverride).forEach((key) => {
-      const value = configOverride[key as keyof Config];
+    (Object.entries(configOverride) as [keyof Config, Config[keyof Config]][]).forEach(([key, value]) => {
       if (value !== undefined) {
-        config[key as keyof Config] = value;
+        (config as Record<string, unknown>)[key as string] = value;
       }
     });
   }
 
-  const returnConfig = { ...defaultConfig(), ...config } as unknown as Config;
-  return returnConfig;
+  const resolvedConfig = { ...defaultConfig(), ...config } as Config;
+  return { config: resolvedConfig, configPath };
+};
+
+/**
+ * Loads the handoff configuration from the project root.
+ *
+ * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json.
+ * Merges file config with any provided overrides, then applies defaults for missing values.
+ *
+ * @param configOverride - Optional partial config to override file-loaded values.
+ * @returns The fully resolved Config object.
+ */
+export const initConfig = (configOverride?: Partial<Config>): Config => {
+  return initConfigWithMetadata(configOverride).config;
 };