lovable-migrate

CLI‑утилита для автоматизированной «оздоровляющей» миграции репозиториев из Lovable в более привычный рабочий формат проекта. Скрипт приводит структуру к FSD‑подобной, чистит мусор/легаси, обновляет зависимости, копирует шаблоны конфигов и готовит проект к дальнейшей разработке.

Требования: Node.js ≥ 20. Поддерживаются npm/pnpm/yarn/bun.

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

Запуск без установки:

npx @itcamel/lovable-migrate --dry-run

Запуск с установкой:

npx @itcamel/lovable-migrate

Опции CLI:

• --cwd <path> — указывает корень целевого проекта (по умолчанию текущая папка).
• --dry-run — прогнать все шаги без изменения файлов (только лог/предпросмотр).

Примеры:

# анализ в текущей папке
npx @itcamel/lovable-migrate --dry-run

# запуск над другим проектом
npx @itcamel/lovable-migrate --cwd ../my-app

При реальном запуске без --dry-run перед началом будет создан snapshot (точка отката) и автоматически использована при ошибке.

Что делает инструмент (коротко)

Пайплайн задач (в типовом порядке):

1. checkTarget — валидация целевой директории: есть package.json, версия Node ≥ 20 и т.п.
2. removeFiles — удаление мусорных/конфликтных файлов (см. deletes).
3. installDeps — установка пакетов (lock‑файлом выбранного PM), первичная подготовка окружения.
4. tailwindUpgrade — запуск @tailwindcss/upgrade (если включено).
5. radixMigrate — чистка старых @radix-ui/* и установка нового radix-ui (если включено).
6. fsdRefactor — реорганизация src/ по маппингу (см. fsd.mapping), перепись импортов, патч index.html/main.* и удаление пустых папок.
7. copyTemplates — копирование шаблонов конфигов (Prettier, Vite) в корень проекта.
8. ncuUpdate — npm-check-updates обновляет версии в package.json (по аргументам ncu.args).
9. installDevRequired — установка dev‑зависимостей из конфига.

Дополнительно (внутренние шаги): snapshot (точка отката), enforcePM (синхронизация менеджера пакетов), installRuntimeDeps, sanitize, build.

Конкретный набор/порядок можно ограничивать через tasks.only / tasks.except / tasks.order.

Конфигурация

Создайте один из файлов в корне проекта:

lovable.migrate.json
.lovable-migrate.json

Если конфиг не найден — берутся значения по умолчанию. Ниже — полная схема с пояснениями.

Структура Config

{
	"general": {
		"dryRunDefault": false, // Включить dry‑run по умолчанию
		"requireGitClean": false, // TODO: Требовать чистое состояние git (зарезервировано)
		"backupSuffix": ".bak", // Суффикс для бэкапов при перезаписи
	},
	"pm": {
		"preferredPM": "yarn", // Предпочтительный менеджер пакетов
		"purgeNodeModules": true, // Удалять node_modules при смене PM
		"updatePackageManagerField": true, // Обновлять поле packageManager в package.json
		"packageManagerVersionTag": "1.22.22", // Версия для packageManager (например [email protected])
	},
	"tasks": {
		"order": [
			"checkTarget",
			"removeFiles",
			"installDeps",
			"tailwindUpgrade",
			"radixMigrate",
			"fsdRefactor",
			"copyTemplates",
			"ncuUpdate",
			"installDevRequired",
		],
		"only": [], // Выполнить только указанные задачи
		"except": [], // Исключить указанные задачи
		"presets": {}, // Именованные наборы задач
		"continueOnError": false, // Пытаться продолжать после ошибок
	},
	"rollback": {
		"enabled": true, // Создавать snapshot и откатывать при ошибке
	},
	"paths": {
		"ignoreDirs": [
			// Директории для пропуска при обходах/снапшотах
			"node_modules",
			".git",
			"dist",
			"build",
			".lovable",
			".next",
			".turbo",
		],
		"snapshotInclude": [], // Что включать в snapshot (пусто → весь проект, минус ignoreDirs)
		"snapshotDir": ".lovable/snapshots", // Куда складывать snapshot (относительно проекта или абсолютный путь)
	},
	"deletes": {
		"files": [
			// Точечные файлы к удалению
			"bun.lockb",
			"components.json",
			"postcss.config.js",
		],
		"globs": [], // TODO: (зарезервировано) шаблоны на удаление
	},
	"install": {
		"dependencies": ["react-is"], // Рантайм‑зависимости к установке
		"depArgs": [], // Доп. аргументы к установке зависимостей
		"devDependencies": [
			// Dev‑зависимости к установке
			"@tailwindcss/vite",
			"vite-tsconfig-paths",
			"vite-plugin-inspect",
			"@vheemstra/vite-plugin-imagemin",
			"imagemin-gifsicle",
			"imagemin-mozjpeg",
			"imagemin-pngquant",
			"imagemin-svgo",
			"imagemin-webp",
			"@types/imagemin-gifsicle",
			"@types/imagemin-mozjpeg",
			"@types/imagemin-pngquant",
			"@types/imagemin-svgo",
			"@types/imagemin-webp",
			"rollup-plugin-visualizer",
			"@rollup/plugin-terser",
			"terser",
			"lightningcss",
			"cross-env",
			"prettier",
			"@trivago/prettier-plugin-sort-imports",
		],
		"devDepArgs": [], // Доп. аргументы к установке dev‑зависимостей
		"legacyPeerDeps": true, // npm: использовать --legacy-peer-deps при установке
		"scripts": {
			// Обновляемые/создаваемые скрипты в package.json
			"lint": "prettier --check .",
			"format": "prettier --log-level warn --write \"./**/*.{jsx,js,tsx,ts}\"",
		},
	},
	"tailwind": {
		"enabled": true, // Выполнять @tailwindcss/upgrade
		"args": ["--force"], // Аргументы к upgrade
	},
	"radix": {
		"enabled": true, // Включить миграцию Radix
		"removePatterns": ["@radix-ui/"], // Что удалить из зависимостей (или кода в более общих сценариях)
		"targetPackage": "radix-ui", // Какой пакет установить взамен
	},
	"ncu": {
		"enabled": true, // Включить npm-check-updates
		"args": ["-u"], // Аргументы к ncu
	},
	"fsd": {
		"aliasPrefix": "@/", // Префикс алиаса для импортов
		"rewriteImports": true, // Переписывать импорты после переносов
		"pruneEmptyDirs": true, // Удалять пустые каталоги
		"codeExtensions": [".ts", ".tsx", ".js", ".jsx"],
		"mapping": {
			// Правила переноса внутри src/
			"components/ui": "shared/ui",
			"ui": "shared/ui",
			"lib": "shared/lib",
			"utils": "shared/lib",
			"hooks": "shared/lib/hooks",
			"types": "shared/types",
			"assets": "shared/assets",
			"styles": "app/styles",
			"App.css": "app/styles/App.css",
			"App.tsx": "app/App.tsx",
			"main.tsx": "app/main.tsx",
			"index.css": "app/styles/index.css",
		},
		"html": {
			"enabled": true, // Патч index.html (entry → src/app/main.*)
			"entryCandidates": ["index.html"],
		},
		"main": {
			"candidates": [
				// Где искать main.* для патча импорта CSS
				"src/app/main.tsx",
				"src/main.tsx",
				"src/app/main.ts",
				"src/main.ts",
			],
			"cssTarget": "@/app/styles/index.css",
		},
	},
	"templates": {
		"root": "", // Альтернативный корень с шаблонами (по умолчанию встроенные пакета)
		"prettier": {
			"ignoreSrc": "templates/prettier/.prettierignore.tpl",
			"rcSrc": "templates/prettier/.prettierrc.tpl",
			"ignoreDest": ".prettierignore",
			"rcDest": ".prettierrc",
			"overwrite": true, // Перезаписывать если существует
			"backup": false, // Делать .bak перед перезаписью
		},
		"vite": {
			"configSrc": "templates/vite/vite.config.ts.tpl",
			"configDest": "vite.config.ts",
			"overwrite": true,
			"backup": true,
		},
	},
}

Как работает snapshot/rollback

• Перед началом (если не --dry-run и rollback.enabled: true) создаётся snapshot проекта.
• По умолчанию снимок включает весь проект за вычетом paths.ignoreDirs. Если заданы paths.snapshotInclude — включаются только перечисленные пути (также с исключениями).
• Снимки складываются в paths.snapshotDir (по умолчанию: .lovable/snapshots).
• При ошибке любая модификация будет откачена из снапшота. При успешном завершении — снимок удаляется.

Тонкая настройка задач

• tasks.only: перечислите идентификаторы задач, чтобы выполнить только их.
• tasks.except: перечислите задачи, которые нужно пропустить.
• tasks.order: задайте свой порядок выполнения (массив TaskName).
• tasks.presets: именованные наборы задач — удобно для разных пресетов миграции.
• tasks.continueOnError: при true пайплайн постарается идти дальше даже если одна из задач упала (используйте с осторожностью).

Замечания по менеджеру пакетов

• Блок pm позволяет автоматически выравнивать менеджер пакетов:
  • удаление артефактов чужих PM (lock‑файлы, служебные каталоги);
  • обновление package.json.packageManager на выбранный preferredPM@versionTag;
  • опциональная чистка node_modules.

Советы

• Всегда запускайте сначала с --dry-run, чтобы увидеть план изменений.
• Храните конфиг lovable.migrate.json в репозитории — так миграция повторяема.
• При нестабильных peer‑конфликтах используйте install.legacyPeerDeps: true (для npm).

Лицензия

ISC © Yury Moshkin TG @bikeauto

Тестирование пакета

Команда для очистки мусора, сборка, запуск локально.

git restore test && rm -rf ./test/node_modules ./test/dist ./test/.lovable ./test/src/app ./test/src/shared ./test/.prettier* ./test/*.bak.* ./test/yarn.lock && yarn build && node dist --cwd ./test