add-feature

Add Frontend Feature

Scaffold a new feature module following the project's React + TypeScript conventions.

Arguments

• {feature} — Feature name in kebab-case (e.g., alerts, settings, users)

Configuration

Read cloudstack.json from the project root at the start of execution. Extract:

• FRONTEND_PATH = frontend.path (default: web)
• DEV_PORT = frontend.devPort (default: 5173)
• UI_LIBRARY = frontend.uiLibrary (default: shadcn)
• STATE_SERVER = frontend.stateManagement.server (default: tanstack-query)
• STATE_CLIENT = frontend.stateManagement.client (default: zustand)
• MULTI_TENANT = backend.multiTenancy (default: false)

If cloudstack.json does not exist, auto-detect by checking package.json dependencies.

Structure

Creates the following structure under {FRONTEND_PATH}/src/features/{feature}/:

{feature}/
├── pages/
│   └── {feature}-page.tsx
└── components/
    └── {feature}-overview.tsx

And adds an API service at {FRONTEND_PATH}/src/api/services/{feature}.api.ts.

0. Detect Existing Patterns

Before scaffolding, scan the project for existing conventions:

# Find existing API client
find {FRONTEND_PATH}/src/api -name "client.*" -o -name "http.*" -o -name "axios.*" 2>/dev/null | head -5

# Find existing feature modules for reference
ls -d {FRONTEND_PATH}/src/features/*/pages/ 2>/dev/null | head -3

# Check for multi-tenancy utility
grep -rl "tenantId\|appendTenant\|multiTenant" {FRONTEND_PATH}/src/api/ 2>/dev/null | head -3

Read any existing API service file and feature page to match the project's established patterns.

1. API Service ({FRONTEND_PATH}/src/api/services/{feature}.api.ts)

Adapt the template based on the existing API client pattern detected in step 0.

If using a custom apiRequest wrapper:

/**
 * {Feature} API client
 */

import { apiRequest } from '../client'
import type { PaginatedResponse } from '../types'

// Define types inline or in ../types/index.ts
export interface {Entity} {
  id: string
  // fields
}

const BASE_PATH = '/api/{feature}'

export const {feature}Api = {
  /**
   * Get paginated list
   */
  async getAll(page = 1, pageSize = 20): Promise<PaginatedResponse<{Entity}>> {
    const params = new URLSearchParams()
    params.set('pageNumber', page.toString())
    params.set('pageSize', pageSize.toString())

    return apiRequest({ url: BASE_PATH, params })
  },

  /**
   * Get by ID
   */
  async getById(id: string): Promise<{Entity}> {
    return apiRequest({ url: `${BASE_PATH}/${id}` })
  },
}