@vira-ui/cli

Vira CLI - Генератор проектов и кода для Vira Framework

Создавайте проекты, генерируйте компоненты, сервисы и backend-код одной командой.

📖 Quickstart: Создаём CRM за 10 минут • 🚀 Production-Ready • Установка • Быстрый старт • Команды • Примеры

🎯 Что это?

Vira CLI — это мощный инструмент командной строки для быстрого создания проектов и генерации кода в экосистеме Vira Framework. Он автоматизирует рутинные задачи и помогает начать разработку за секунды.

Основные возможности

• ✅ Создание проектов — Frontend, Fullstack, Kanban reference app
• ✅ Генерация компонентов — React компоненты, сервисы, страницы, модели
• ✅ Backend scaffolding — Go handlers, models, migrations, event handlers
• ✅ Синхронизация типов — Автоматическая синхронизация TypeScript типов из Go структур
• ✅ VRP Protocol — Валидация и генерация документации протокола
• ✅ Docker & DevOps — Готовая инфраструктура для разработки и продакшена

Примечание: Некоторые функции находятся в экспериментальной стадии в альфа-версиях.

📦 Установка

Глобальная установка

# Глобальная установка
npm install -g @vira-ui/cli

Использование через npx (рекомендуется)

npx @vira-ui/cli create my-app

🚀 Быстрый старт

💡 Новый? Начните с 📖 Quickstart гайда — создайте полноценную CRM страницу за 10 минут!

1. Создание проекта

# Интерактивный выбор шаблона
npx vira create my-app

# Или с указанием шаблона
npx vira create my-app --template frontend
npx vira create my-app --template fullstack
npx vira create my-app --template kanban

2. Генерация компонента

cd my-app
npx vira generate component Button
npx vira generate service User
npx vira generate page Dashboard

3. Запуск проекта

cd my-app
npm install
npm run dev

Готово! Ваш проект запущен и готов к разработке.

📚 Команды

vira create <name> — Создание проекта

Создаёт новый проект Vira с выбранным шаблоном.

Опции:

• -t, --template <template> — Тип шаблона: frontend, fullstack, kanban

Примеры:

# Интерактивный выбор
vira create my-app

# Frontend проект (React + Vite + Vira UI)
vira create my-app --template frontend

# Fullstack проект (Frontend + Go Backend + Docker)
vira create my-app --template fullstack

# Kanban reference app (демонстрация VRP)
vira create my-app --template kanban

vira init — Инициализация проекта

Инициализирует проект Vira в текущей директории. Полезно для инициализации существующего проекта.

Опции:

• -t, --template <template> — Тип шаблона: frontend, fullstack, kanban

Примеры:

# Интерактивный выбор шаблона
cd my-existing-project
vira init

# С указанием шаблона
vira init --template frontend

Что создаётся:

Frontend Template

my-app/
├── src/
│   ├── components/     # React компоненты
│   ├── services/        # Сервисы (DI)
│   ├── pages/          # Страницы
│   ├── models/         # Модели с валидацией
│   ├── hooks/          # Custom hooks
│   ├── utils/          # Утилиты
│   ├── App.tsx         # Главный компонент
│   └── main.tsx        # Точка входа
├── package.json        # Зависимости
├── tsconfig.json       # TypeScript конфигурация
├── vite.config.ts     # Vite конфигурация
└── index.html          # HTML шаблон

Fullstack Template

my-app/
├── frontend/           # React приложение
├── ui/                 # Vira UI пакет/шоукейсы
├── backend/            # Go API
│   ├── cmd/api/        # Точка входа
│   ├── internal/
│   │   ├── handlers/   # HTTP handlers
│   │   ├── models/     # Go модели
│   │   ├── events/     # Event handlers
│   │   ├── db/         # Database
│   │   ├── cache/      # Redis
│   │   └── config/     # Конфигурация
│   ├── migrations/     # SQL миграции
│   └── queries/        # SQLC queries
├── deploy/             # Docker & DevOps
│   ├── docker-compose.dev.yml
│   └── docker-compose.prod.yml
└── migrations/         # Общие миграции

Kanban Template

my-app/
├── src/
│   ├── components/
│   │   ├── KanbanBoard.tsx
│   │   ├── KanbanColumn.tsx
│   │   └── KanbanCard.tsx
│   ├── services/
│   │   └── kanban.ts   # VRP сервис
│   └── models/
│       └── kanban.ts   # Типы
└── ...

vira generate <type> <name> — Генерация кода

Генерирует файлы для компонентов, сервисов, страниц, моделей и роутов.

Алиас: vira g

Типы:

• component / comp — React компонент
• service — Сервис (DI)
• page — Страница
• model — Модель с валидацией
• route — Роут
• test — Тест для компонента, сервиса или страницы

Опции:

• -d, --dir <directory> — Директория для вывода (по умолчанию: src)
• -i, --interactive — Интерактивный режим (для компонентов и сервисов - выбор props, VRP, UI)
• --vrp — Явно использовать Vira Reactive Protocol (VRP)
• --no-vrp — Явно не использовать VRP

Примеры:

vira generate component Button
vira g comp UserCard

# Интерактивная генерация компонента с выбором props
vira generate component Button --interactive

# Явное использование VRP (без интерактивного режима)
vira generate component Button --vrp

# Явное указание не использовать VRP
vira generate component Button --no-vrp

# Комбинация: интерактивный режим с принудительным VRP
vira generate component Button --interactive --vrp

# Генерация сервиса
vira generate service User
vira g service Product

# Генерация страницы
vira generate page Dashboard
vira g page Profile

# Генерация модели
vira generate model User
vira g model Product

# Генерация роута
vira generate route users
vira g route products

# Генерация теста
vira generate test Button
vira g test UserService

# С указанием директории
vira generate component Button --dir src/components

Сгенерированные файлы:

Component

// src/components/Button.tsx
import { createElement } from '@vira-ui/core';
import type { ViraComponentProps } from '@vira-ui/core';

export interface ButtonProps extends ViraComponentProps {
  // Add your props here
  // При использовании --interactive здесь будут автоматически добавлены props
}

export function Button(props: ButtonProps) {
  return createElement('div', { className: 'button' },
    // Add your content here
  );
}

Интерактивная генерация компонента:

vira generate component Button --interactive

Интерактивный режим позволяет:

• ✅ Выбрать использование Vira Reactive Protocol (VRP) для state management
• ✅ Настроить VRP channel и state type
• ✅ Интерактивно добавить props с выбором типов
• ✅ Выбрать использование Vira UI компонентов (@vira-ui/ui)
• ✅ Автоматически сгенерировать правильную структуру компонента

Пример интерактивной генерации с VRP:

vira generate component TaskCard --interactive
# → Использовать VRP? Yes
# → Channel: task:123
# → State type: TaskState
# → Использовать Vira UI? Yes

Результат будет включать:

• useViraState hook для синхронизации состояния
• Интерфейс состояния (TaskState)
• Интеграцию с Vira UI компонентами
• Готовую структуру для работы с VRP

Примечание: createElement и некоторые экспериментальные функции могут изменяться в будущих версиях.

Service

// src/services/UserService.ts
import { createViraService, signal } from '@vira-ui/core';

export const UserService = createViraService('user', () => {
  const data = signal([]);
  const loading = signal(false);
  const error = signal<string | null>(null);

  const fetch = async () => {
    loading.set(true);
    try {
      // Add your logic here
      // const result = await api.get('/user');
      // data.set(result);
    } catch (e) {
      error.set(e instanceof Error ? e.message : 'Unknown error');
    } finally {
      loading.set(false);
    }
  };

  return {
    data,
    loading,
    error,
    fetch,
  };
});

VRP-based Service (при интерактивной генерации с выбором VRP):

// src/services/UserService.ts
import { createService, useService } from '@vira-ui/core';
import { useViraState } from '@vira-ui/react';

export interface UserState {
  id?: string;
  // Add your state fields here
}

// Business logic service
createService('user', () => ({
  processData(data: UserState | null): any {
    // Add processing logic
    return data;
  },
}));

// VRP hook
export function useUser(id?: string) {
  const channel = id ? `user:${id}` : 'user';
  const { data, sendEvent, sendUpdate, sendDiff } = useViraState<UserState>(channel, null);
  const userService = useService('user');

  return {
    data,
    update(updates: Partial<UserState>) {
      sendDiff(updates);
    },
    sendEvent(eventName: string, payload: any) {
      sendEvent(eventName, payload);
    },
  };
}

Page

// src/pages/DashboardPage.tsx
import { createElement } from '@vira-ui/core';

export function DashboardPage() {
  return createElement('div', { className: 'dashboard-page' },
    createElement('h1', null, 'Dashboard'),
    // Add your content here
  );
}

Model

// src/models/User.ts
import { defineModel } from '@vira-ui/core';

export const UserModel = defineModel({
  // Add your fields here
  id: {
    type: 'string',
    required: true,
  },
});

Route

// src/routes/users.ts
import { reactiveRoute } from '@vira-ui/core';
import { UsersPage } from '../pages/UsersPage';

export const usersRoute = reactiveRoute({
  path: '/users',
  component: UsersPage,
});

Test

// src/components/Button.test.tsx
import React from 'react';
import { render } from '@testing-library/react';
import { Button } from './Button';
import type { ButtonProps } from './Button';

describe('Button', () => {
  it('renders correctly', () => {
    const props: ButtonProps = {
      // Add test props here
    };
    const { container } = render(React.createElement(Button, props));
    expect(container).toBeTruthy();
  });
});

vira make <type> <name> — Backend scaffolding (Go)

Генерирует Go-код для backend разработки.

Типы:

• handler — HTTP handler
• model — Go модель (struct)
• migration — SQL миграция (up/down)
• event — Event handler
• crud — CRUD handlers (List, Get, Create, Update, Delete)

Опции:

• -d, --dir <directory> — Целевая директория
• -m, --model <model> — Имя модели (для crud)

Примеры:

# Генерация HTTP handler
vira make handler user
# Создаёт: backend/internal/handlers/user.go

# Генерация модели
vira make model User
# Создаёт: backend/internal/models/User.go

# Генерация миграции
vira make migration create-users
# Создаёт: migrations/20240101120000_create-users.up.sql
#          migrations/20240101120000_create-users.down.sql

# Выполнение миграций
vira db migrate                    # Применить все миграции
vira db up                         # Алиас для migrate
vira db rollback                   # Откатить последнюю миграцию
vira db down                       # Алиас для rollback
vira db status                     # Показать статус миграций

# С указанием URL базы данных
vira db migrate --db-url "postgres://user:pass@localhost/dbname?sslmode=disable"
# Или через переменную окружения
DATABASE_URL="postgres://user:pass@localhost/dbname?sslmode=disable" vira db migrate

# Генерация event handler
vira make event user.created
# Создаёт: backend/internal/events/user_created.go
#          backend/internal/events/registry_user_created.go

# Генерация CRUD handlers
vira make crud user
# Создаёт: backend/internal/handlers/user_crud.go
#          (ListUser, GetUser, CreateUser, UpdateUser, DeleteUser)

vira make crud product --model Product
# Создаёт CRUD handlers с указанной моделью

Сгенерированные файлы:

Handler

// backend/internal/handlers/user.go
package handlers

import (
  "encoding/json"
  "net/http"
)

type UserResponse struct {
  Message string `json:"message"`
}

// User handles GET /user
func User(w http.ResponseWriter, r *http.Request) {
  w.Header().Set("Content-Type", "application/json")
  _ = json.NewEncoder(w).Encode(UserResponse{
    Message: "User handler ok",
  })
}

Model

// backend/internal/models/User.go
package models

import "time"

type User struct {
  ID        string    `db:"id"`
  CreatedAt time.Time `db:"created_at"`
  UpdatedAt time.Time `db:"updated_at"`
}

Migration

-- migrations/20240101120000_create-users.up.sql
-- +goose Up
-- TODO: add migration SQL here

-- migrations/20240101120000_create-users.down.sql
-- +goose Down
-- TODO: rollback SQL here

Event Handler

// backend/internal/events/user_created.go
package events

import (
  "context"
  "encoding/json"
  "github.com/gorilla/websocket"
)

// UserCreated handles event: user.created
func UserCreated(ctx context.Context, hub EventEmitter, conn *websocket.Conn, msg WSMessage) {
  var payload map[string]any
  if len(msg.Data) > 0 {
    _ = json.Unmarshal(msg.Data, &payload)
  }

  // TODO: implement domain logic here
  // Example: hub.Emit(ChannelCustom("demo", "echo"), payload)
}

func init() {
  Register("user.created", UserCreated)
}

// backend/internal/events/registry_user_created.go
package events

func init() {
  Register("user.created", UserCreated)
}

CRUD Handler

// backend/internal/handlers/user_crud.go
package handlers

import (
  "encoding/json"
  "net/http"
  "github.com/gorilla/mux"
)

// ListUser handles GET /user
func ListUser(w http.ResponseWriter, r *http.Request) {
  // Implementation
}

// GetUser handles GET /user/{id}
func GetUser(w http.ResponseWriter, r *http.Request) {
  // Implementation
}

// CreateUser handles POST /user
func CreateUser(w http.ResponseWriter, r *http.Request) {
  // Implementation
}

// UpdateUser handles PUT /user/{id}
func UpdateUser(w http.ResponseWriter, r *http.Request) {
  // Implementation
}

// DeleteUser handles DELETE /user/{id}
func DeleteUser(w http.ResponseWriter, r *http.Request) {
  // Implementation
}

vira db — Команды для работы с базой данных

Управление миграциями базы данных через goose.

Подкоманды:

vira db migrate (или vira db up)

Применить все неприменённые миграции.

Опции:

• -d, --dir <directory> — Директория с миграциями (по умолчанию: migrations)
• --db-url <url> — URL подключения к базе данных (или используйте переменную DATABASE_URL)
• --driver <driver> — Драйвер БД: postgres, mysql, sqlite3 (по умолчанию: postgres)

Примеры:

# Использование переменной окружения
export DATABASE_URL="postgres://user:pass@localhost/mydb?sslmode=disable"
vira db migrate

# Или напрямую в команде
vira db migrate --db-url "postgres://user:pass@localhost/mydb?sslmode=disable"

# С указанием директории миграций
vira db migrate --dir migrations --db-url "postgres://..."

vira db rollback (или vira db down)

Откатить последнюю применённую миграцию.

Опции: те же, что у migrate

Пример:

vira db rollback
vira db rollback --db-url "postgres://user:pass@localhost/mydb?sslmode=disable"

vira db status

Показать статус всех миграций (какие применены, какие нет).

Опции: те же, что у migrate

Пример:

vira db status

Примечание: Для работы команд требуется установленный goose. CLI автоматически попытается установить его при первом использовании, если он не найден.

vira sync — Синхронизация типов

Синхронизирует TypeScript типы из Go структур.

Опции:

• --types — Синхронизировать TypeScript типы (по умолчанию: true)
• --backend <path> — Путь к Go файлу (по умолчанию: backend/internal/types/types.go)
• --frontend <path> — Путь для TypeScript типов (по умолчанию: frontend/src/vira-types.ts)
• --ui <path> — Путь для TypeScript типов UI (по умолчанию: ui/src/vira-types.ts)
• -w, --watch — Watch mode: автоматическая синхронизация при изменениях (в разработке)

Пример:

vira sync --types

# С указанием путей
vira sync --backend backend/internal/types/types.go \
         --frontend frontend/src/types/vira.ts \
         --ui ui/src/types/vira.ts

Что делает:

1. Парсит Go структуры
2. Конвертирует Go типы в TypeScript
3. Генерирует TypeScript файлы с типами
4. Создаёт helper функции для каналов VRP

Пример Go структуры:

// backend/internal/types/types.go
package types

type User struct {
  ID    string `json:"id"`
  Name  string `json:"name"`
  Email string `json:"email"`
}

type Task struct {
  ID        string `json:"id"`
  Title     string `json:"title"`
  Completed bool   `json:"completed"`
}

Сгенерированный TypeScript:

// frontend/src/vira-types.ts
// Auto-generated by vira sync --types. Do not edit manually.

export type ViraMessageType =
  | 'handshake' | 'ack' | 'sub' | 'sub_ack' | 'unsub' | 'unsub_ack'
  | 'update' | 'event' | 'diff' | 'ping' | 'pong' | 'error';

export enum ViraChannelEnum {
  User = 'user',
  Task = 'task',
  Notifications = 'notifications',
  Demo = 'demo',
}

export type ViraChannel =
  | `${ViraChannelEnum.User}:${string}`
  | `${ViraChannelEnum.Task}:${string}`
  | `${ViraChannelEnum.Notifications}:${string}`
  | ViraChannelEnum.Demo
  | string;

export interface ViraDataMap {
  User: User;
  Task: Task;
}

export type ViraAnyData = ViraDataMap[keyof ViraDataMap];

export interface User {
  id: string;
  name: string;
  email: string;
}

export interface Task {
  id: string;
  title: string;
  completed: boolean;
}

// ... helper functions для каналов

vira proto — VRP Protocol утилиты

Работа с Vira Reactive Protocol (VRP).

Примечание: Некоторые функции VRP находятся в экспериментальной стадии в альфа-версиях.

Подкоманды:

vira proto validate

Валидирует схему VRP протокола и проверяет типы.

Опции:

• --file <path> — Путь к Go файлу с типами (по умолчанию: backend/internal/types/types.go)

Примеры:

# Валидация с файлом по умолчанию
vira proto validate

# Валидация с указанным файлом
vira proto validate --file backend/internal/types/models.go

Что проверяется:

• Наличие и корректность Go структур
• Соответствие структур требованиям VRP
• Наличие необходимых полей для каналов

vira proto generate

Генерирует документацию по каналам VRP и схемы протокола.

Опции:

• --file <path> — Путь к Go файлу с типами (по умолчанию: backend/internal/types/types.go)
• --output <path> — Директория для вывода (по умолчанию: docs)

Примеры:

# Генерация документации
vira proto generate

# С указанием путей
vira proto generate --file backend/internal/types/types.go --output docs/vrp

Что генерируется:

• VRP_CHANNELS.md — Документация по всем доступным каналам
• Описание типов данных для каждого канала
• Примеры использования с useViraState

vira doc — Генерация документации

Генерирует документацию CLI команд в docs/cli.md.

vira doc

vira validate — Валидация проекта

Проверяет структуру проекта и наличие необходимых файлов.

vira validate

Что проверяется:

• Наличие обязательных файлов (package.json, vite.config.ts, и т.д.)
• Структура директорий
• Конфигурационные файлы

🎨 Примеры

Создание Fullstack проекта

# Создание проекта
vira create my-crm --template fullstack

cd my-crm

# Frontend: генерация компонентов
cd frontend
vira generate component ClientCard
vira generate service Client
vira generate page Clients

# Backend: генерация handlers
cd ../backend
vira make handler client
vira make model Client
vira make migration create-clients

# Синхронизация типов
cd ..
vira sync --types

# Запуск
cd frontend && npm install && npm run dev
cd ../backend && go mod tidy && go run ./cmd/api

Синхронизация типов

# Создание Kanban reference app
vira create kanban-app --template kanban

cd kanban-app

# Генерация дополнительных компонентов
vira generate component TaskCard
vira generate service Task

# Backend: генерация event handlers
cd ../backend
vira make event kanban.card.create
vira make event kanban.card.move
vira make event kanban.card.delete

# Запуск
cd .. && npm install && npm run dev

Пример 3: Работа с миграциями

# Создание миграции
vira make migration create-users

# Редактирование миграции
# migrations/20240101120000_create-users.up.sql
CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(255) NOT NULL,
  email VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

# migrations/20240101120000_create-users.down.sql
DROP TABLE IF EXISTS users;

Пример 4: Синхронизация типов

# 1. Определяем Go структуры
# backend/internal/types/types.go
type Product struct {
  ID    string `json:"id"`
  Name  string `json:"name"`
  Price int64  `json:"price"`
}

2. Синхронизируем типы

vira sync --types

# 3. Используем в TypeScript
# frontend/src/components/ProductCard.tsx
import type { Product } from '../vira-types';

export function ProductCard({ product }: { product: Product }) {
  return <div>{product.name} - ${product.price}</div>;
}

❓ FAQ

Q: Можно ли использовать CLI без глобальной установки?
A: Да! Используйте npx @vira-ui/cli.

Q: Можно ли использовать CLI в существующем проекте?
A: Да! Команды generate и make работают в любом проекте.

Q: Как синхронизировать типы из нескольких Go файлов?
A: Объедините структуры в один файл или используйте несколько вызовов vira sync с разными путями.

Q: Как работает синхронизация типов?
A: CLI парсит Go структуры, конвертирует типы в TypeScript и генерирует файлы с типами и helper функциями.

Q: Поддерживаются ли другие языки backend?
A: Сейчас поддерживается только Go. Поддержка других языков планируется в будущих версиях.

🔧 Разработка CLI

# Клонирование и установка
git clone https://github.com/skrolikov/vira-cli.git
cd vira-cli
npm install

# Сборка
npm run build

# Локальное использование
npm link
vira create test-app

✨ Что нового в v1.0.1

Улучшенная генерация компонентов

• ✅ Интерактивный режим с опцией использования VRP
• ✅ Интеграция с Vira UI компонентами
• ✅ Автоматическая генерация VRP-enabled компонентов
• ✅ Умный выбор props с интерактивным добавлением типов

Улучшенная генерация сервисов

• ✅ Поддержка VRP для сервисов
• ✅ Генерация hooks с useViraState
• ✅ Интеграция с DI container

VRP Protocol утилиты

• ✅ Реальная валидация Go структур
• ✅ Генерация документации по каналам
• ✅ Автоматическое определение доступных каналов

Новые команды

• ✅ vira init — инициализация проекта в существующей директории
• ✅ vira generate test — генерация тестов
• ✅ vira make crud — генерация CRUD handlers
• ✅ vira validate — валидация структуры проекта

🛣️ Roadmap

v1.1 (В разработке)

• [ ] Watch mode для vira sync
• [ ] Поддержка других шаблонов (Vue, Svelte)
• [ ] Генерация Storybook историй
• [ ] Плагины для расширения функциональности

v1.2 (Планируется)

• [ ] Шаблоны для микросервисов
• [ ] Интеграция с CI/CD
• [ ] Генерация OpenAPI спецификаций
• [ ] Автоматическая генерация событий из схем

📄 License

MIT

🤝 Contributing

Мы приветствуем вклад! Пожалуйста, прочитайте CONTRIBUTING.md для деталей.

📞 Support

• GitHub Issues: Создать issue
• Discussions: Обсуждения

Сделано с ❤️ командой Vira

GitHub • Документация • Примеры