Руководство

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

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

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

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

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

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

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

bash

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

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

Установка mise

Unix/Linux/macOS:

bash

curl https://mise.run | sh

macOS (Homebrew):

bash

brew install mise

Windows:

powershell

winget install jdx.mise

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

bash

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

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

TIP

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

Установка Razd

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

bash

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

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

# Проверьте установку
razd --version
# Должно вывести: razd 0.4.4

Подробное руководство по установке

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

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

Давайте настроим ваш первый проект с Razd. У вас есть три варианта:

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

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

bash

# Клонирование и настройка проекта одной командой
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 и т.д.)
⚙️ Выполняет задачи настройки (миграции БД, первичная сборка)
✅ Проект готов к работе!

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

bash

# Клонировать в директорию с выбранным именем
razd up https://github.com/user/project.git --name my-awesome-project
cd my-awesome-project

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

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

bash

cd my-existing-project

# Настроить проект
razd up

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

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

Создайте Razdfile.yml с автоматическим определением типа проекта:

bash

cd my-project

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

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

yaml

mise:
  tools:
    task: latest
tasks:
  default:
    desc: "Set up project and start development"
    cmds:
      - echo "🚀 Setting up project..."
      - task: install
      
  install:
    desc: "Install development tools via mise"
    cmds:
      - echo "📦 Installing tools..."
      - mise install
      
  dev:
    desc: "Start development workflow"
    cmds:
      - echo "🚀 Starting development..."

      
  build:
    desc: "Build project"
    cmds:
      - echo "🔨 Building project..."

Настройка под ваш проект

Базовый Razdfile.yml содержит шаблонные задачи. Вам потребуется:

Добавить необходимые инструменты в секцию mise.tools (например, node: "22", python: "3.11")
Заменить команды echo в задачах на реальные команды вашего проекта
Добавить дополнительные задачи специфичные для вашего проекта

Секция tasks в Razdfile.yml основана на стандарте Taskfile.yml. Полную документацию по синтаксису и возможностям задач смотрите в официальном руководстве Taskfile.

См. раздел Понимание Razdfile.yml ниже для полных примеров конфигурации.

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

После настройки проекта используйте эти команды для работы:

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

bash

# Установить все инструменты из Razdfile.yml
razd install

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

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

bash

# Установить зависимости проекта (npm install, pip install и т.д.)
razd setup

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

bash

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

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

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

bash

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

# С аргументами
razd run deploy --args "--env=production"

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

bash

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

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

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

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

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

yaml


mise:
  tools:
    node: "22"

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

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

yaml


# Управление инструментами через mise
mise:
  tools:
    # Простые версии
    node: "22"
    python: "3.11"
    task: "latest"
    
    # Расширенная конфигурация
    go:
      version: "1.21"
      postinstall: "go install golang.org/x/tools/cmd/goimports@latest"
      install_env:
        CGO_ENABLED: "1"
  
  # Кастомные плагины (опционально)
  plugins:
    node: "https://github.com/asdf-vm/asdf-nodejs.git"

# Определения задач
tasks:
  # Главная задача (выполняется при `razd up`)
  default:
    desc: Настроить и запустить проект
    cmds:
      - task: install
      - task: setup
      - task: dev
  
  # Установка инструментов
  install:
    desc: Установить инструменты разработки
    cmds:
      - mise install
      - echo "✓ Инструменты установлены"
  
  # Настройка зависимостей
  setup:
    desc: Установить зависимости проекта
    cmds:
      - npm install
      - npm run build
  
  # Dev сервер
  dev:
    desc: Запустить dev сервер
    cmds:
      - npm run dev
  
  # Сборка
  build:
    desc: Собрать для продакшена
    cmds:
      - npm run build
      - npm run test
  
  # Кастомная задача с переменными
  deploy:
    desc: Деплой в окружение
    cmds:
      - task: build
        vars:
          ENV: production
      - ./scripts/deploy.sh {{.ENV}}

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

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

bash

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

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

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

bash

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

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

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

# Собрать
razd build

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

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

yaml

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

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

yaml

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

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

yaml

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

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

bash

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

# Или через переменную окружения
export RAZD_NO_SYNC=1
razd up

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

yaml

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

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

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

bash

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

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

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

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

bash

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

# Или создайте минимальный вручную
cat > Razdfile.yml << 'EOF'

mise:
  tools:
    node: "22"
tasks:
  default:
    cmds:
      - echo "Проект настроен!"
EOF

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

bash

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

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

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

bash

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

# Или откройте Razdfile.yml
cat Razdfile.yml

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

Поздравляем! Теперь вы знаете основы работы с Razd. 🎉

Продолжите обучение:

❓ Ознакомьтесь с FAQ — ответы на частые вопросы
💡 Посмотрите примеры проектов — реальные конфигурации

Присоединяйтесь к сообществу:

Удачной разработки с Razd! 🚀

Что только что произошло?

Когда вы запустили razd up, вот что произошло за кулисами:

Обнаружение: Razd искал конфигурационные файлы:
- .mise.toml или .tool-versions (для управления инструментами)
- Taskfile.yml (для задач проекта)

Установка инструментов: Если найдена конфигурация mise:

bash

mise install  # Устанавливает все инструменты, определённые в .mise.toml

Настройка проекта: Если найден Taskfile:

bash

task setup    # Запускает задачу setup, определённую в Taskfile.yml

Готово: Ваше окружение разработки теперь готово!

Проверка настройки

Чтобы убедиться, что всё работает правильно:

bash

# Проверьте, что razd работает
razd --version

# Запустите задачу разработки по умолчанию
razd task

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

Теперь, когда Razd у вас работает, изучите эти темы:

Руководство по установке: Узнайте о разных методах установки
Что такое Razd: Поймите философию и преимущества Razd
FAQ: Распространённые вопросы и устранение неполадок

Распространённые проблемы

Возникли трудности? Проверьте эти распространённые решения:

Команда не найдена: razd

Убедитесь, что Razd правильно установлен и находится в вашем PATH. См. руководство по установке.

Команда mise не найдена

Razd требует mise для управления инструментами. Установите его с mise.jdx.dev.

Задача не запускается

Убедитесь, что в вашем Taskfile.yml определена задача setup. Вы можете создать простую задачу setup для начала.

Нужна помощь?

Если у вас всё ещё есть проблемы, проверьте наш FAQ или обратитесь на GitHub.

Что дальше?

Готовы погрузиться глубже? Вот несколько рекомендуемых следующих шагов:

Изучите FAQ: Узнайте о распространённых паттернах использования
Настройка команды: Настройте Razd для вашей команды разработки
Продвинутое использование: Создавайте пользовательские настройки проектов и автоматизацию

Руководство ​

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

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

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

Установка Razd ​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Продолжите обучение: ​

Присоединяйтесь к сообществу: ​

Что только что произошло? ​

Проверка настройки ​

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

Распространённые проблемы ​

Команда не найдена: razd ​

Команда mise не найдена ​

Задача не запускается ​

Что дальше? ​

Руководство

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

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

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

Установка Razd

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Продолжите обучение:

Присоединяйтесь к сообществу:

Что только что произошло?

Проверка настройки

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

Распространённые проблемы

Команда не найдена: razd

Команда mise не найдена

Задача не запускается

Что дальше?