Custom Configuration

Deep dive into every configuration option and how to tailor the generator to your project's needs.

Configuration File

The generator uses hfg.config.json (or hfg.config.jsonc for comments). Place it in your project root — the CLI resolves it relative to the current working directory, so you can run npx heco from any subdirectory.

Full Schema

jsonc

{
  // Rename or add folder types
  "folderNames": {
    "components": "components",
    "hooks": "hooks",
    "services": "services",
    "types": "types",
    "validations": "validations",
    "store": "store"
  },

  // Where features are created
  "basePath": "src/features",

  // Custom generator definitions
  "generators": {
    "feature": {
      "files": [
        {
          "template": "components/Component.tsx.hbs",
          "outputPath": "components/{{PascalName}}.tsx"
        }
      ]
    }
  }
}

Configuration Options Explained

`folderNames`

Maps logical folder roles to actual directory names. The built-in keys are:

Key	Default	Purpose
`components`	`components`	React components
`hooks`	`hooks`	Custom React hooks
`services`	`services`	API service layer
`types`	`types`	TypeScript types
`validations`	`validations`	Validation schemas
`store`	`store`	State management

Rename a folder:

json

{
  "folderNames": {
    "components": "ui",
    "services": "api"
  }
}

This generates: ui/UserProfileCard.tsx and api/userProfileService.ts.

Keys not specified keep their default values.

`basePath`

The root directory where all features are created.

json

{ "basePath": "src/features" }

Generated features go to src/features/<feature-name>/. Use a relative path from your project root, or an absolute path.

Common patterns:

json

{ "basePath": "app/features" }       // Next.js app directory
{ "basePath": "lib/modules" }        // Library-style structure
{ "basePath": "packages/features" }  // Monorepo package

`generators`

Define custom file structures. The key is the generator name (used in npx heco generate <name>), and the value defines what files to create.

json

{
  "generators": {
    "page": {
      "files": [
        {
          "template": "page/Page.tsx.hbs",
          "outputPath": "{{PascalName}}Page.tsx"
        }
      ]
    }
  }
}

Now you can run npx heco generate about-us --generator page.

Each file definition has:

Field	Required	Description
`template`	Yes	Path to the `.hbs` template file (relative to templates directory)
`outputPath`	Yes	Where to write the generated file. Supports `{{PascalName}}`, `{{camelName}}`, etc.

Multiple file types

Define as many files as you need in a single generator:

json

{
  "generators": {
    "fullstack": {
      "files": [
        { "template": "api/handler.ts.hbs", "outputPath": "api/{{camelName}}.ts" },
        { "template": "api/route.ts.hbs", "outputPath": "api/{{camelName}}/route.ts" },
        { "template": "components/Component.tsx.hbs", "outputPath": "components/{{PascalName}}.tsx" },
        { "template": "hooks/useHook.ts.hbs", "outputPath": "hooks/use{{PascalName}}.ts" },
        { "template": "types/types.ts.hbs", "outputPath": "types/{{PascalName}}Types.ts" }
      ]
    }
  }
}

Complete Example: Next.js Feature

Here's a full config for a Next.js project with App Router:

json

{
  "folderNames": {
    "components": "_components",
    "hooks": "_hooks",
    "services": "_api",
    "types": "_types",
    "validations": "_schemas",
    "store": "_state"
  },
  "basePath": "src/app/features",
  "generators": {
    "feature": {
      "files": [
        { "template": "components/Component.tsx.hbs", "outputPath": "_components/{{PascalName}}.tsx" },
        { "template": "hooks/useHook.ts.hbs", "outputPath": "_hooks/use{{PascalName}}.ts" },
        { "template": "services/service.ts.hbs", "outputPath": "_api/{{camelName}}Service.ts" },
        { "template": "types/types.ts.hbs", "outputPath": "_types/{{PascalName}}Types.ts" },
        { "template": "validations/schema.ts.hbs", "outputPath": "_schemas/{{camelName}}Schema.ts" },
        { "template": "store/store.ts.hbs", "outputPath": "_state/{{camelName}}Store.ts" },
        { "template": "page/page.tsx.hbs", "outputPath": "page.tsx" },
        { "template": "layout/layout.tsx.hbs", "outputPath": "layout.tsx" }
      ]
    }
  }
}

This generates:

txt

src/app/features/blog/
├── _components/
│   └── Blog.tsx
├── _hooks/
│   └── useBlog.ts
├── _api/
│   └── blogService.ts
├── _types/
│   └── BlogTypes.ts
├── _schemas/
│   └── blogSchema.ts
├── _state/
│   └── blogStore.ts
├── page.tsx
└── layout.tsx

Validating your config

Always validate your config after changes:

bash

npx heco validate

This checks for:

Invalid folder names
Missing required fields
Type mismatches
Unknown options

The validation uses Zod schemas and gives clear error messages pointing to the exact problem.

Next steps

Custom Generators — build complex multi-file generators
Templates — create templates with dynamic content