Basic Feature Generation

Generate your first feature from scratch. This walks through every step and explains what happens under the hood.

Step 1: Create a config file

The generator needs to know where to put files and what folders to create. Create hfg.config.json in your project root:

{
  "folderNames": {
    "components": "components",
    "hooks": "hooks",
    "services": "services",
    "types": "types",
    "validations": "validations",
    "store": "store"
  },
  "basePath": "src/features"
}

What this does:

• folderNames maps logical folder roles to directory names. Each key represents a role (components, hooks, etc.) and the value is the actual folder name on disk.
• basePath tells the generator where to place all features. Every feature will be created under src/features/<feature-name>/.

Step 2: Generate a user profile feature

npx heco generate user-profile

When you run this command, here's exactly what happens:

1. Config loading — The CLI reads hfg.config.json from the current directory and merges it with built-in defaults. Missing folders get their default values.
2. Name parsing — user-profile is passed through the naming engine to produce:
   • PascalName → UserProfile
   • camelName → userProfile
   • snakeName → user_profile
   • upperName → USER_PROFILE
3. Generator resolution — The default feature generator is selected (you can define custom generators — see Custom Generators example).
4. File rendering — Each file definition in the generator is processed:
   • The template file (.hbs) is located (user directory first, then built-in)
   • Handlebars renders the template with the naming variables
   • The output path is computed using the naming patterns
5. File writing — Files are written to disk. By default, existing files are skipped.

Step 3: The result

src/features/user-profile/
├── components/
│   ├── UserProfileList.tsx
│   └── UserProfileCard.tsx
├── hooks/
│   ├── useUserProfile.ts
│   └── useUserMutations.ts
├── services/
│   └── userProfileService.ts
├── types/
│   └── userProfileTypes.ts
├── validations/
│   └── userProfileSchema.ts
└── store/
    └── userProfileStore.ts

Each file is pre-populated with working boilerplate:

• Components export a React functional component with props interface
• Hooks use TanStack Query for data fetching and mutations
• Services contain API call stubs with proper error handling
• Types have TypeScript interfaces for all entities
• Validations include Zod schemas
• Store is a Zustand store

Step 4: Verify the result

npx heco list

This shows all generated features and their file structure. You can also inspect the files directly.

What's happening behind the scenes?

Config merging

The CLI merges your hfg.config.json with the default config. Your values take precedence, but any missing fields fall back to defaults. This means you can start with a minimal config and add over time.

Template resolution

Templates are located in this order:

1. A custom templates directory (if configured)
2. Built-in templates bundled with the package

This allows you to override any built-in template by placing a file with the same name in your project.

File writing modes

The default mode is skip — existing files are never overwritten. You can change this with flags:

npx heco generate user-profile --overwrite  # Replace existing files
npx heco generate user-profile --ask        # Prompt for each file
npx heco generate user-profile --dry-run    # Preview without writing

Next steps

Now that you've generated your first feature, try:

• Custom Config — customize folder names, paths, and add new folder types
• Custom Generators — define your own file structures