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**

Create pages.json in the root directory.
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

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

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