Volt Modules

A powerful CLI tool for generating Next.js App Router feature modules with TanStack Query, React Hook Form, and TypeScript.

Features

• 🚀 Interactive CLI - Prompts for module name and custom hooks preference
• 📁 Feature-based Architecture - Creates organized features/{module}/ structure
• 🎨 Custom Hooks - Optional UI hooks, services, and constants
• 📋 CRUD Operations - Complete Create, Read, Update, Delete functionality
• 🔍 Built-in Filtering - Search and status filtering out of the box
• 🎯 TypeScript First - Fully typed with Zod schemas
• 📱 Responsive Tables - Mobile-friendly data tables
• 🎨 Modal Forms - Professional form components with validation

Installation

# Install globally
npm install -g @volt.js/modules

# Or use with npx (no installation needed)
npx @volt.js/modules init

Usage

Create a New Module

volt-modules init

The CLI will prompt you for:

1. Framework: Choose between Next.js (App Router), Vite + React Router, or TanStack Router
2. Custom Hooks: Whether to include reusable UI hooks and services
3. Module Name: The name of your feature module

Example

$ volt-modules init
? Which framework are you using?
  1) Next.js (App Router)
  2) Vite + React Router
  3) TanStack Router
? Enter your choice (1-3): 1
? Do you want to include custom hooks? (y/N): y
? Enter module name: user-management

ℹ Detected src/ architecture
✓ Created: src/hooks/use-form.tsx
✓ Created: src/services/user-preferences.ts
✓ Created: src/constants/storage-keys.ts
✓ Created: app/user-management/page.tsx
✓ Created: app/user-management/layout.tsx
✓ Created: src/features/user-management/_schemas/UserManagementSchema.ts
✓ Created: src/features/user-management/_api/queries/user-management.queries.ts
✓ Created: src/features/user-management/_api/mutations/user-management.mutations.ts
✓ Created: src/features/user-management/_components/UserManagementTable.tsx
✓ Created: src/features/user-management/_components/UserManagementForm.tsx

✓ Module "user-management" created successfully in src/features/user-management

Generated Structure

With Custom Hooks (recommended)

src/ (or app/)
├── hooks/
│   ├── use-form.tsx
│   ├── use-page.tsx
│   └── use-user-preferences.ts
├── services/
│   └── user-preferences.ts
├── constants/
│   └── storage-keys.ts
└── features/
    └── user-management/
        ├── _schemas/
        │   └── UserManagementSchema.ts
        ├── _api/
        │   ├── queries/
        │   │   └── user-management.queries.ts
        │   └── mutations/
        │       └── user-management.mutations.ts
        ├── _components/
        │   ├── UserManagementTable.tsx
        │   └── UserManagementForm.tsx
        ├── page.tsx
        └── layout.tsx

Without Custom Hooks

src/ (or app/)
└── features/
    └── user-management/
        ├── _schemas/
        │   └── UserManagementSchema.ts
        ├── _api/
        │   ├── queries/
        │   │   └── user-management.queries.ts
        │   └── mutations/
        │       └── user-management.mutations.ts
        ├── _components/
        │   ├── UserManagementTable.tsx
        │   └── UserManagementForm.tsx
        ├── page.tsx
        └── layout.tsx

What's Included

🔧 Core Files

• Schema: TypeScript types with Zod validation
• API Layer: TanStack Query hooks for data fetching
• Components: Table and Form components
• Page: Complete page component with CRUD operations
• Layout: Basic layout wrapper

🎨 Custom Hooks (Optional)

• useFormHook: Advanced form management with validation
• usePage: Page layout with tabs and actions
• useUserPreferences: Persistent user preferences
• userPreferencesService: Local storage service
• Storage keys: Centralized constants

✨ Features

• Search and filtering
• Modal forms with confirmation dialogs
• Loading states and error handling
• TypeScript types throughout
• Responsive design
• Accessibility support

Requirements

• Node.js 18+
• Next.js 13+ with App Router
• TanStack Query
• React Hook Form
• Zod
• TypeScript

Integration

After generating a module:

1. Add to your route:

// In your route file
import "./features/user-management/user-management"

2. Navigate to the page:

http://localhost:3000/user-management

3. Customize the module:
   • Update the schema in _schemas/
   • Modify API calls in _api/
   • Customize components in _components/

CLI Options

| Option | Description | Default | |--------|-------------|---------| | -p, --path <path> | Output directory | '.' | | -d, --dry-run | Show files without creating | false |

Examples

# Create in specific directory
volt-modules init --path ./src

# Preview what would be created
volt-modules init --dry-run

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © Your Name