Site icon Efficient Coder

HBuilderX Migration Guide: Convert AI Web Projects to uni-app in 3 Steps

高效码农

Converting Web Projects to uni-app in HBuilderX: A Comprehensive Migration Guide

Snippet: Learn how to convert AI-generated Web projects (Claude/ChatGPT) into standard uni-app projects. This guide covers fixing manifest.json visibility, resolving “missing index.html” Vite errors, and adapting Vue 3 main.js for cross-platform deployment in HBuilderX.

Why Your AI-Generated Project Isn’t Working in HBuilderX

When you use Claude or other AI tools to generate code, they typically output a standard Vite + Vue 3 web structure. However, uni-app is an enhanced framework with specific directory requirements and a specialized compiler. If you simply drag a web folder into HBuilderX, you’ll often encounter a raw manifest.json code view or the dreaded “Missing index.html” error.

To unlock cross-platform capabilities (iOS, Android, Mini-Programs), you must transition your project from a “Web Page” to a “uni-app Application.”

Phase 1: Reconstructing Core Configuration Files

1.1 manifest.json: The Project Identity

The manifest.json file is the heart of a uni-app project. If HBuilderX fails to show the graphical interface (tabs like “Basic Settings”), it means the IDE doesn’t recognize the folder as a uni-app project.

Key Parameters for manifest.json:

Parameter Function Quantitative Example/Value
appid DCloud App Identifier Format: __UNI__XXXXXXX
versionName App Version Name e.g., 1.0.0
versionCode App Version Code Integer, e.g., 100
vueVersion Vue Compiler Version Must be "3" for Vite support
router.mode H5 Routing Mode hash or history

Expert Tip: If your appid is empty, go to the HBuilderX menu: Project -> Get AppID. This is mandatory for real-device debugging and cloud packaging.

1.2 pages.json: The Mandatory Router

Standard web projects use vue-router, but uni-app relies exclusively on pages.json. Without this file, the compiler cannot locate your entry pages.

**How-To: Configure a Minimal pages.json**

  1. Create pages.json in the root directory.
  2. Insert the following structure:
{
  "pages": [
    {
      "path": "pages/index/index",
      "style": { "navigationBarTitleText": "Home" }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "black",
    "navigationBarBackgroundColor": "#F8F8F8"
  }
}

Phase 2: Deep Adaptation for Vue 3 & Vite

2.1 Resolving the “Missing index.html” Error

If you see the error Missing index.html in root directory, it’s because the Vue 3 Vite compiler requires an HTML template as a service entry point.

Technical Specification: index.html Template
Create an index.html file in your root directory (same level as manifest.json) with this exact hook:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <script>
      var coverSupport = 'CSS' in window && typeof CSS.supports === 'function' && (CSS.supports('top: env(a)') || CSS.supports('top: constant(a)'))
      document.write('<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0' + (coverSupport ? ', viewport-fit=cover' : '') + '">')
    </script>
    <title>uni-app Project</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/main.js"></script>
  </body>
</html>

2.2 Adapting main.js for uni-app (Vue 3)

AI-generated main.js files usually use createApp(App).mount('#app'). For uni-app’s multi-platform compatibility, you must use the createSSRApp factory function.

Implementation:

import App from './App.vue'
import { createSSRApp } from 'vue'

export function createApp() {
  const app = createSSRApp(App)
  return {
    app
  }
}

Phase 3: Syntax and Directory Migration

3.1 Tag Replacement Strategy

Because uni-app compiles code into native components for different platforms, you should replace standard HTML tags with uni-app components.

Migration Mapping Table:

Web HTML Tag uni-app Component Reason for Conversion
<div> <view> Container component for cross-platform Flexbox
<span> <text> Inline text; supports features like long-press copy
<img> <image> Enhanced component; supports lazy loading and modes
<a> <navigator> Internal routing via pages.json

3.2 Standardized Directory Structure

Web projects often hide files inside a src folder. uni-app requires core files to reside in the root directory.

  • Root/
  • pages/ — Page .vue files (formerly src/views)
  • static/ — Assets like images (formerly public)
  • App.vue — App lifecycle management
  • main.js — Entry point
  • index.html — Host template
  • manifest.json — Multi-platform config
  • pages.json — Routing config

FAQ: Troubleshooting Common Issues

Q1: Why does manifest.json still show as raw JSON after my changes?
A: This is usually an IDE refresh issue. Right-click your project name in the left panel -> Remove from View, then drag the folder back into HBuilderX. Ensure pages.json and App.vue exist in the root.

Q2: What does “Vite is compiling on demand” mean?
A: This is a feature, not a bug. Vite only compiles the page you are currently viewing to speed up development. This “slowness” disappears entirely after you Publish (Build) the project.

Q3: Can I keep using axios for API calls?
A: While it works for H5, it may fail on Mini-Programs or native Apps due to CORS or adapter issues. It is highly recommended to use uni.request, which has an axios-like syntax and native support for all platforms.

Summary: The 3-Minute Migration Checklist

  1. Create Template: File -> New -> Project -> uni-app (Select Vue 3).
  2. Move Code: Copy your AI-generated logic into the new pages/index/index.vue.
  3. Global Replace: Use HBuilderX to replace all div with view and img with image.
  4. Sync Config: Copy your old manifest.json code into the new project’s “Source View.”
  5. Run: Click Run -> Run to Browser.

By aligning your project with the uni-app engineering standards, you transform a simple web page into a powerful multi-platform application.

Exit mobile version