v0-project-converter

V0 Project Conversion Specification

Quickly convert a Next.js project generated by V0 into this project's page components, maintaining visual effects and functionality, and complying with this project's development standards.

Core Objectives

Maintain page visual consistency
Remove Next.js-specific implementations
Produce page components that can run in this project

Usage

Step 1: Run the preprocessing script

node scripts/v0-converter.mjs <v0-project-dir> [output-name]

Example

node scripts/v0-converter.mjs "temp/my-v0-project" my-page


**脚本会自动完成**：
- 完整复制 V0 项目到 `src/prototypes/[页面名]/`
- 分析项目结构（路径别名、Next.js 代码等）
- 生成 AI 工作文档（`.v0-tasks.md`）
- 生成详细数据（`.v0-analysis.json`）
- **不修改任何代码**（100% 安全）

### 步骤 2：按任务清单完成转换

脚本会生成 `.v0-tasks.md` 文件，包含：
- 项目概况统计
- 6 个具体任务清单
- 路径别名转换参考表
- 依赖安装命令
- 验收测试步骤

按任务清单与本规范示例执行转换。

## 转换要点

### 本项目页面组件规范

默认先转换为普通 React 页面组件。只有在需求明确要求接入 Axhub / Axure 运行时能力时，才引入 `forwardRef<AxureHandle, AxureProps>`、`useImperativeHandle` 和 `axure-types`。

**默认格式（推荐）**：

```typescript
/**
 * @name 页面名称
 * 
 * 参考资料：
 * - /rules/development-guide.md
 * - /skills/default-resource-recommendations/SKILL.md
 */

import './style.css';
import React from 'react';

export default function PageName() {
  // 组件逻辑
  
  return (
    // JSX 内容
  );
}

Only integrate the Axure API in the following scenarios：

The page needs to be taken over by Axhub / Axure
Configuration panels, external data sources, event callbacks or action triggers need to be configured
The user explicitly requests maintaining an interface form consistent with existing Axure components

At this point, refer again to /rules/axure-api-guide.md, using the following wrapping form:

import React, { forwardRef, useImperativeHandle } from 'react';
import type { AxureProps, AxureHandle } from '../../common/axure-types';

const Component = forwardRef<AxureHandle, AxureProps>(function PageName(innerProps, ref) {
  useImperativeHandle(ref, function () {
    return {
      getVar: function () { return undefined; },
      fireAction: function () {},
      eventList: [],
      actionList: [],
      varList: [],
      configList: [],
      dataList: []
    };
  }, []);

  return (
    // JSX 内容
  );
});

export default Component;

Remove Next.js-specific code

Remove all Next.js-specific implementations:

// ❌ 需要移除
"use client"                                    // Next.js 客户端组件指令，本项目不需要
import { useRouter } from 'next/navigation'    // Next.js 路由
import Image from 'next/image'                 // Next.js 图片组件
import Link from 'next/link'                   // Next.js 链接组件
import type { Metadata } from 'next'           // Next.js 元数据类型
import { Analytics } from '@vercel/analytics/next'  // Vercel 分析

// ✅ 替换为
// 删除 "use client" 指令
// 删除 useRouter 相关代码
<img> 替代 <Image>
<a> 替代 <Link>
// 删除 Metadata 和 Analytics

About "use client": -This project does not use Next.js; all components are client-rendered

Must be deleted, otherwise it will cause syntax errors

Path alias conversion

Convert V0's @/ alias to relative paths:

// V0 原始代码
import { cn } from "@/lib/utils"
import { Button } from "@/components/ui/button"

// 在 app/page.tsx 中转换为
import { cn } from "../lib/utils"
import { Button } from "../components/ui/button"

// 在 components/ui/card.tsx 中转换为
import { cn } from "../../lib/utils"

The analysis report generated by the script will provide specific conversion references for each file.

Style files

/* style.css 必须以此开头 */
@import "tailwindcss";

/* 然后是原 globals.css 的内容 */
/* 保持 Tailwind V4 语法不变 */
@theme inline { ... }
@custom-variant dark (...);

Dependency management

Exclude Next.js-related dependencies:

next and all next-* packages
@vercel/* packages
react and react-dom(already in this project)

Keep other dependencies:

class-variance-authority, clsx, tailwind-merge
@radix-ui/* components
lucide-react, recharts, date-fns , etc.

Acceptance criteria

After conversion is complete, run the acceptance script:

node scripts/check-app-ready.mjs /prototypes/[页面名]

Acceptance requirements：

Status is READY
The page renders normally
No console errors
Interaction functions normally
Styles display correctly

Common issues

Missing dependencies

# 根据报告中的依赖列表安装
pnpm add [依赖名称]

Path error

Check whether @/ has been converted to a relative path
Refer to .v0-analysis.md for the conversion table

Style issues

Confirm that style.css contains @import "tailwindcss"
Check whether CSS variables are complete

Next.js remnants

Search "use client"、next/、@vercel/
Make sure all are removed or replaced

Reference resources

Development standards：/rules/development-guide.md
Debugging guide：/rules/debugging-guide.md
Tailwind CSS：/skills/default-resource-recommendations/SKILL.md