Руководство

Это руководство поможет вам начать работу с Razd и настроить ваш проект.

Что вы узнаете

Как установить Razd и необходимые зависимости
Настройка первого проекта с razd up
Понимание основных команд и рабочего процесса
Создание собственного Razdfile.yml
Советы и лучшие практики

Для подробных руководств по конкретным технологиям см. документацию по стекам технологий.

Предварительные требования

Перед использованием Razd убедитесь, что у вас установлено:

Обязательные зависимости

1. git — для операций с репозиториями

# Проверьте установку
git --version

2. mise — для управления инструментами разработки

Unix/Linux/macOS:

curl https://mise.run | sh

macOS (Homebrew):

brew install mise

Windows:

winget install jdx.mise

После установки перезапустите терминал или обновите PATH:

# Linux/macOS
source ~/.bashrc  # или ~/.zshrc для zsh

3. task — будет установлен автоматически через mise при первом использовании

Не волнуйтесь, если task еще не установлен! Razd автоматически установит его через mise при первом запуске.

Установка Razd

Установите Razd используя mise (рекомендуется):

# Установите плагин Razd
mise plugin install razd https://github.com/razd-cli/vfox-plugin-razd

# Установите последнюю версию
mise use -g razd@latest

# Проверьте установку
razd --version

См. подробное Руководство по установке для других методов.

Ваша первая настройка проекта

У вас есть три варианта:

Вариант 1: Клонирование и настройка нового проекта

Самый простой способ — клонировать репозиторий и сразу его настроить:

razd up https://github.com/razd-cli/example-nodejs-project

Что происходит:

Razd клонирует репозиторий в текущую директорию
Переходит в директорию проекта
Читает Razdfile.yml (или mise.toml + Taskfile.yml)
Синхронизирует конфигурацию (если нужно)
Устанавливает инструменты разработки через mise (Node.js, Python и др.)
Устанавливает зависимости проекта (npm install, pip install и т.д.)
Выполняет задачи настройки (миграции БД, первичная сборка)
Проект готов к работе!

С кастомным именем директории:

razd up https://github.com/user/project.git --name my-awesome-project
cd my-awesome-project

Вариант 2: Настройка существующего локального проекта

Если у вас уже есть проект локально:

cd my-existing-project
razd up

Razd автоматически найдет конфигурацию (Razdfile.yml, mise.toml, Taskfile.yml) и выполнит настройку.

Вариант 3: Инициализация нового проекта с автоопределением

cd my-project
razd init

Созданный Razdfile.yml будет выглядеть так:

version: "1"

dependencies:
  using: "mise"
  ensure: []

tasks:
  default:
    desc: "Set up project and start development"
    cmds:
      - echo "🚀 Setting up project..."

Базовый Razdfile.yml содержит минимальную конфигурацию. Добавьте инструменты в dependencies.ensure (например, "node@22", "python@3.11"), используя razd add node@22 или вручную. Секция tasks основана на стандарте Taskfile.yml.

Основные команды

Управление инструментами

# Установить все зависимости из Razdfile.yml
razd up

# Установить зависимости и запустить default задачу
razd up -r

# Добавить зависимость
razd add node@22

# Без автосинхронизации
razd up --no-sync

Настройка проекта

# Инициализировать новый Razdfile.yml
razd init

# С указанием провайдера
razd init --using devbox

# Миграция с существующего mise.toml или devbox.json
razd init --migrate

Запуск рабочих процессов

# Запустить dev сервер
razd dev

# Собрать проект
razd build

# Запустить интерактивную оболочку
razd shell

Выполнение кастомных задач

# Запустить любую задачу из Razdfile.yml
razd run test
razd run lint
razd run deploy

# Список всех задач
razd list
razd list --all

Вывод справки

# Общая справка
razd --help

# Справка по конкретной команде
razd up --help
razd run --help

Понимание Razdfile.yml

Razdfile.yml — это центральный файл конфигурации, который объединяет управление зависимостями (через mise или devbox) и автоматизацию задач (taskfile).

Минимальная конфигурация

version: "1"

dependencies:
  using: "mise"
  ensure:
    - "node@22"

tasks:
  default:
    cmds:
      - echo "Hello from Razd!"

Полная конфигурация

version: "1"

# Управление зависимостями
dependencies:
  using: "mise"
  
  # Инструменты в формате tool@version
  ensure:
    - "node@22"
    - "python@3.11"
    - "task@latest"
  
  # Нативная конфигурация mise (опционально)
  extra:
    mise:
      env:
        NODE_ENV: development
      settings:
        experimental: true

# Определения задач
tasks:
  # Главная задача (выполняется при `razd run` или `razd up -r`)
  default:
    desc: Настроить и запустить проект
    deps: [install]
    cmds:
      - npm run dev
  
  # Установка зависимостей
  install:
    desc: Установить зависимости проекта
    cmds:
      - npm install
  
  # Dev сервер
  dev:
    desc: Запустить dev сервер
    cmds:
      - npm run dev
  
  # Сборка
  build:
    desc: Собрать для продакшена
    cmds:
      - npm run build
      - npm run test
  
  # Деплой с переменными
  deploy:
    desc: Деплой в окружение
    cmds:
      - npm run build
      - ./scripts/deploy.sh

Примеры рабочих процессов

Сценарий 1: Включение нового разработчика в работу

# Новый член команды получает ссылку на репозиторий
razd up https://github.com/company/main-api

# Через 30 секунд:
# ✓ Репозиторий склонирован
# ✓ Node.js 20, PostgreSQL, Redis установлены
# ✓ npm зависимости установлены
# ✓ База данных мигрирована
# ✓ Dev сервер запущен на localhost:3000
# → Разработчик может сразу начать работу!

Сценарий 2: Работа над открытым проектом

# Контрибьютор хочет протестировать фичу
razd up https://github.com/cool-project/frontend
cd frontend

# Внести изменения
razd dev  # Запустить dev сервер

# Протестировать
razd run test

# Собрать
razd build

Советы и лучшие практики

1. Используйте осмысленные имена задач

tasks:
  dev:          # ✅ Понятно
  start-server: # ✅ Описательно
  s:            # ❌ Не понятно

2. Документируйте задачи

tasks:
  deploy:
    desc: Деплой приложения в production (требуются AWS credentials)
    cmds:
      - ./scripts/deploy.sh

3. Используйте композицию задач

tasks:
  # Переиспользуемые задачи
  test:
    cmds: [npm test]
  
  build:
    cmds: [npm run build]
  
  # Композитная задача
  ci:
    desc: Полный CI процесс
    cmds:
      - task: test
      - task: build

4. Отключайте синхронизацию, когда нужно

# Временно отключить синхронизацию
razd up --no-sync

5. Используйте переменные для гибкости

tasks:
  build:
    cmds:
      - npm run build -- --mode={{.ENV | default "development"}}
  
  deploy:
    cmds:
      - ./deploy.sh {{.TARGET_ENV}} {{.VERSION}}

Устранение неполадок

Проблема: "mise not found"

# Проверьте установку mise
mise --version

# Если не установлен:
curl https://mise.run | sh

# Обновите PATH
source ~/.bashrc  # или ~/.zshrc

Проблема: "No Razdfile.yml found"

# Инициализируйте новый Razdfile.yml
razd init

version: "1"

dependencies:
  using: "mise"
  ensure:
    - "node@22"
tasks:
  default:
    cmds:
      - echo "Проект настроен!"

Проблема: Конфликт между Razdfile.yml и mise.toml

# Razd автоматически синхронизирует, но можно отключить
razd up --no-sync

# Или вручную проверить различия
diff Razdfile.yml mise.toml

Проблема: Задача не найдена

# Проверьте доступные задачи
razd list

# Смотрите все задачи, включая внутренние
razd list --all

Следующие шаги

HelpCircle

FAQ

Ответы на частые вопросы

Layers

Стек технологий

Руководства по конкретным технологиям

MessageSquare

GitHub Issues

Задавайте вопросы

Send

Чат сообщества