🐝 Ruch CLI

A CLI tool to structure React TypeScript front-end architectures according to hexagonal architecture principles.

🚀 Installation

Local development

# Clone the repository
git clone https://github.com/yourusername/ruch.git
cd ruch

# Install dependencies
bun install

# Build the project
bun run build

# Make the file executable
chmod +x dist/index.js

Global installation (future)

# Global installation via npm (when published)
npm install -g ruch

# Or via Bun
bun install -g ruch

📖 Usage

Available commands

create <domain> - Create a new domain

Automatically generates the structure of a business domain with hexagonal architecture.

# Create a domain with all default options
./dist/index.js create user

# Create a domain without UI
./dist/index.js create product --without-ui

# Create a domain without store
./dist/index.js create order --without-store

# Create a minimal domain (without UI, store)
./dist/index.js create notification --without-ui --without-store

Available options:

• --with-ui / --without-ui : Include/exclude UI folder with React components (default: included)
• --with-store / --without-store : Include/exclude store folder with Zustand (default: included)
• --with-queries / --without-queries : Include/exclude queries folder with React Query (default: included)
• --with-api / --without-api : Include/exclude API folder with Axios (default: included)

list - List all domains

Displays all existing domains with their structure.

./dist/index.js list

delete <domain> - Delete a domain

Deletes an existing domain and all its content.

# See security warning
./dist/index.js delete user

# Delete permanently
./dist/index.js delete user --force

Options:

• -f, --force : Force deletion without asking for confirmation

🏗️ Generated structure

When you create a domain with ruch create <domain>, the following structure is generated:

src/domains/<domain>/
├── types/           # TypeScript types for the domain
│   └── index.ts     # Interfaces and types
├── services/        # Business logic (factories, mappers, validators)
│   └── index.ts     # Services and utility functions
├── api/             # API calls with Axios
│   └── index.ts     # API configuration and methods
├── queries/         # React Query hooks
│   └── index.ts     # useQuery, useMutation hooks
├── store/           # Local store with Zustand
│   └── index.ts     # Store configuration
├── ui/              # React components specific to the domain
│   └── index.ts     # Table, Card components, etc.
└── index.ts         # Domain entry point

💡 Usage examples

1. Create a complete User domain

./dist/index.js create user

Generates:

• Types: User, UserCreateRequest, UserUpdateRequest, UserStatus
• Services: createUserFactory, mapUserToDisplayFormat, validateUser
• API: userApi.getAll(), userApi.create(), etc.
• Queries: useUsers(), useUser(id), useCreateUser(), etc.
• Store: useUserStore with Zustand
• UI: UserTable, UserCard React components

2. Create a Product domain without UI

./dist/index.js create product --without-ui

Perfect for domains that don't require specific UI components.

3. Import and use a domain

After creation, you can import domain elements:

// Import everything from the domain
import { User, useUsers, userApi, UserTable } from './src/domains/user';

// Or import specifically
import { User } from './src/domains/user/types';
import { useUsers } from './src/domains/user/queries';
import { UserTable } from './src/domains/user/ui';

🎯 Hexagonal architecture principles

Ruch CLI structures your domains according to the following principles:

Separation of concerns

• Types : Define data structure
• Services : Contain pure business logic
• API : Handle external communication
• Queries : Orchestrate cache and loading states
• Store : Manage local domain state
• UI : Present data to the user

Dependencies and ports

• Business core (types, services) depends on nothing
• Adapters (API, UI) depend on the core
• Queries orchestrate between API and UI
• Store manages temporary local state

🛠️ Technologies used

• Runtime : Bun
• CLI Framework : Commander.js
• File System : fs-extra
• Styling : Chalk (colored messages)
• TypeScript : Strict configuration

🎨 Generated templates

Each folder is created with ready-to-use templates:

• Types : TypeScript interfaces with examples
• API : Axios configuration with complete CRUD
• Queries : Optimized React Query hooks
• Store : Zustand store with DevTools
• UI : React components with Tailwind CSS
• Services : Factory, mappers, and validators

🔧 Development

Available scripts

# Development in watch mode
bun run dev

# Build for production
bun run build

# Test the CLI
./dist/index.js --help

CLI project structure

src/
├── commands/        # Command implementations
│   ├── create.ts
│   ├── delete.ts
│   └── list.ts
├── templates/       # Templates for generating domains
│   └── domain.ts
├── utils/           # Utilities
│   ├── logger.ts
│   └── paths.ts
└── index.ts         # CLI entry point

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please follow TypeScript conventions and add tests for new features.

Made with ❤️ to structure your React TypeScript projects according to hexagonal architecture.