component-generator

A small, config-driven CLI that scaffolds new code for any project. The exact layout, naming, and file contents are driven by a per-project config file, so you never edit the tool itself.

Out of the box (no config) it scaffolds a whole feature folder — an empty components/ dir plus boilerplate for constants, hooks, page, queries, services, and types (one file per sub-folder):

delegate-id/
  components/                      (empty)
  constants/delegate-id.constants.ts
  hooks/useDelegateIdForm.ts
  page.tsx
  queries/delegate-id.queries.ts
  services/delegate-id.service.ts
  types/delegate-id.types.ts

Prefer a single-component-per-folder layout instead? Drop in the examples/component-generator.config.mjs config.

Install

The package is published on npm. The easiest way is npx (no install needed):

npx @mais_ghaith/component-generator UserCard

Or install it into a project / globally:

npm i -D @mais_ghaith/component-generator   # per-project (recommended)
# or
npm i -g @mais_ghaith/component-generator   # global

Both expose the generate-component (and gen-component) commands.

Quick start — km team

Zero setup. The default already targets the km monorepo layout (packages/core/src/features), so anyone on the team scaffolds a feature with a single, easy-to-remember command — no config file, no flags:

npx generate-component delegate-id

→ creates packages/core/src/features/delegate-id/…

Add -y to skip the interactive prompts entirely:

npx generate-component delegate-id -y

Working in a project with a different layout? Drop a component-generator.config.mjs at its root to override the base dir — see Configuration.

Usage

generate-component [name] [options]

Options:
  -d, --dir <path>       components base dir, relative to project root (overrides config)
  -p, --path <subpath>   sub-path under the base dir (e.g. a feature folder)
  -c, --config <file>    explicit config file to use
  -P, --preset <name>    use a bundled preset (e.g. km-identity)
  -f, --force            overwrite existing files
      --dry-run          show what would be created without writing
  -y, --yes              skip interactive prompts; use args/config only
  -h, --help             show help

Run with no name to go fully interactive:

generate-component

Preview without writing:

generate-component UserCard --dry-run

Names can be given in any case — UserCard, user-card, user card all normalise to the same set of variables.

Configuration

The tool looks for one of these in the current project (via cosmiconfig):

• component-generator.config.{js,cjs,mjs,json}
• .componentgeneratorrc[.json|.js|.cjs|.mjs]
• a "component-generator" key in package.json

If none is found, the built-in defaults (the four-file layout above) are used. See examples/ for ready-to-copy configs.

Presets

Presets are named partial configs bundled with the tool — pick one with -P, --preset <name> for a known layout without adding any file to your project:

| Preset | componentsDir | | ------------- | ------------------------------- | | km-identity | packages/core/src/features |

generate-component delegate-id -P km-identity

Precedence (low → high): built-in defaults → preset → project config file. So a project's own component-generator.config.* always wins over a preset. New presets are added in the PRESETS map in src/config.js.

Config keys

| Key | Type | Default | Description | | -------------- | --------- | ------------------ | ---------------------------------------------------------------- | | componentsDir| string | "packages/core/src/features" | Base dir, relative to the config's location. | | naming | string | "kebab" | Case for the folder/file base: pascal, kebab, camel, snake. | | folder | boolean | true | Wrap generated files in a folder named after the target. | | templatesDir | string | null | Project-local template dir; .hbs files here override bundled ones by name. | | dirs | array | ["components"] | Empty directories to create (Handlebars patterns). | | files | array | feature set | Each { output, template }. output is a filename pattern and may contain sub-directories (e.g. "hooks/use{{pascalCase}}.ts"); template is a template filename. | | vars | object | { useClient:false } | Extra variables passed to every template. |

output patterns can nest paths, and dirs lets you create folders that stay empty (handy when their contents differ every time). Together they can scaffold a whole feature folder, not just a single component — see the feature example below.

Template variables

Both the output filename pattern and template bodies are Handlebars. Available variables:

| Variable | Example (user card) | | ---------------- | --------------------- | | {{name}} | user card (raw) | | {{pascalCase}} | UserCard | | {{camelCase}} | userCard | | {{kebabCase}} | user-card | | {{snakeCase}} | user_card | | {{titleCase}} | User Card | | {{upperCase}} | USER_CARD | | {{componentName}} | the base name in the configured naming case | | any key in vars | e.g. {{useClient}} |

Helpers: {{#if (eq a b)}}, {{upper x}}, {{lower x}}.

Custom templates per project

Point templatesDir at a folder in your project and drop .hbs files there named to match your files[].template entries. Any template not found in your templatesDir falls back to the tool's bundled templates.

// component-generator.config.mjs
export default {
  componentsDir: "src/features",
  templatesDir: "tools/component-templates",
  files: [{ output: "{{componentName}}.tsx", template: "component.hbs" }],
  vars: { useClient: true },
};

Examples

• examples/component-generator.config.mjs — the default four-file component layout.
• examples/km-identity.config.mjs — scaffolds a whole feature folder (page/types/services/queries/constants/hooks + an empty components/ dir), matching the km-identity-enforcement-fe project.

Feature-folder output (from the km example):

delegate-id/
  components/                      (empty)
  constants/delegate-id.constants.ts
  hooks/useDelegateIdForm.ts
  page.tsx
  queries/delegate-id.queries.ts
  services/delegate-id.service.ts
  types/delegate-id.types.ts

Debugging

Set DEBUG=1 to see full stack traces on error.