uni-app Project Structure Guide

This guide provides a detailed introduction to the uni-app project file structure, helping you better understand and organize your project code.

Overview

The uni-app project structure follows Vue.js conventions while having its own special files and directories. Understanding the project structure is fundamental to developing uni-app applications.

Basic Project Structure

my-uni-app/
├── uniCloud/                   # Cloud development directory (optional)
│   ├── cloudfunctions/         # Cloud functions directory
│   └── database/               # Database directory
├── components/                 # Components directory
│   └── comp-a.vue             # Reusable components
├── pages/                      # Pages directory
│   ├── index/
│   │   └── index.vue          # Home page
│   └── list/
│       └── list.vue           # List page
├── static/                     # Static resources directory
│   ├── images/                # Image resources
│   └── fonts/                 # Font resources
├── uni_modules/               # uni_module plugins directory
├── store/                     # State management directory (optional)
├── api/                       # API interfaces directory (optional)
├── utils/                     # Utility functions directory (optional)
├── main.js                    # Vue initialization entry file
├── App.vue                    # Application configuration file
├── manifest.json              # Application configuration manifest
├── pages.json                 # Page routing configuration
├── uni.scss                   # Global style variables (optional)
└── package.json               # Project dependencies configuration

Tip: The uni-app project structure follows Vue conventions while also having its own special files.

Core Files Explained

1. pages.json - Page Routing Configuration

The pages.json file is used for global configuration of uni-app, determining page file paths, window styles, native navigation bars, native bottom tabbar, etc.

Basic Structure

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "Home"
      }
    },
    {
      "path": "pages/list/list",
      "style": {
        "navigationBarTitleText": "List"
      }
    }
  ],
  "globalStyle": {
    "navigationBarTextStyle": "white",
    "navigationBarTitleText": "uni-app",
    "navigationBarBackgroundColor": "#42b983",
    "backgroundColor": "#F8F8F8"
  },
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#42b983",
    "borderStyle": "black",
    "backgroundColor": "#ffffff",
    "list": [
      {
        "pagePath": "pages/index/index",
        "iconPath": "static/tab-home.png",
        "selectedIconPath": "static/tab-home-active.png",
        "text": "Home"
      },
      {
        "pagePath": "pages/list/list",
        "iconPath": "static/tab-list.png",
        "selectedIconPath": "static/tab-list-active.png",
        "text": "List"
      }
    ]
  }
}

Main Configuration Items

• pages: Page path configuration

  • path: Page path
  • style: Page window style

• globalStyle: Global style configuration

  • navigationBarTextStyle: Navigation bar title color (black/white)
  • navigationBarTitleText: Navigation bar title text
  • navigationBarBackgroundColor: Navigation bar background color
  • backgroundColor: Window background color

• tabBar: Bottom tab bar configuration

  • color: Default tab text color
  • selectedColor: Selected tab text color
  • backgroundColor: Tab background color
  • list: Tab list (2-5 items)

2. manifest.json - Application Configuration Manifest

The manifest.json file is the application configuration file, used to specify the application name, icon, permissions, etc.

Basic Structure

{
  "name": "uni-app Example",
  "appid": "__UNI__XXXXXXX",
  "description": "uni-app example project",
  "versionName": "1.0.0",
  "versionCode": "100",
  "transformPx": false,
  "app-plus": {
    "usingComponents": true,
    "nvueCompiler": "uni-app",
    "splashscreen": {
      "alwaysShowBeforeRender": true,
      "waiting": true,
      "autoclose": true,
      "delay": 0
    }
  },
  "mp-weixin": {
    "appid": "WeChat Mini Program appid starting with wx",
    "setting": {
      "urlCheck": false
    },
    "usingComponents": true
  },
  "h5": {
    "router": {
      "base": "/"
    },
    "optimization": {
      "treeShaking": {
        "enable": true
      }
    }
  }
}

Main Configuration Items

• Basic Information

  • name: Application name
  • appid: Application identifier
  • description: Application description
  • versionName: Version name
  • versionCode: Version code

• Platform Configuration

  • app-plus: App-specific configuration
  • mp-weixin: WeChat Mini Program specific configuration
  • mp-alipay: Alipay Mini Program specific configuration
  • h5: H5-specific configuration

3. App.vue - Application Entry Component

App.vue is the main component of uni-app. All pages are switched under App.vue, and it's the page entry file.

Basic Structure

<script>
export default {
  onLaunch: function() {
    console.log('App Launch')
  },
  onShow: function() {
    console.log('App Show')
  },
  onHide: function() {
    console.log('App Hide')
  }
}
</script>

<style>
/* Global styles */
.container {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
}
</style>

Application Lifecycle

• onLaunch: Triggered when uni-app initialization is complete (triggered only once globally)
• onShow: When uni-app starts or enters foreground from background
• onHide: When uni-app enters background from foreground

4. main.js - Vue Initialization Entry

main.js is the entry file of uni-app, mainly used to initialize Vue instance, define global components, use required plugins, etc.

Basic Structure

import Vue from 'vue'
import App from './App'

// Import global components
import myComponent from './components/my-component.vue'
Vue.component('my-component', myComponent)

// Import global styles
import './common/uni.css'

// Import state management
import store from './store'

// Import global methods
Vue.prototype.$api = {
  formatDate(date) {
    return date.toLocaleDateString()
  }
}

Vue.config.productionTip = false

App.mpType = 'app'

const app = new Vue({
  store,
  ...App
})
app.$mount()

Main Functions

• Vue instance creation and mounting
• Global component registration
• Global style imports
• State management configuration (Vuex)
• Global methods and filters addition

Directory Structure Details

pages Directory

The pages directory stores all business page files and is the core directory of the application.

Features

• Each page should have a separate directory
• Directory name should match page name
• Each page directory must have a Vue file with the same name
• Pages can be nested, supporting multi-level directory structure

Directory Structure Example

pages/
├── index/
│   └── index.vue          # Home page
├── list/
│   └── list.vue           # List page
└── user/
    ├── user.vue           # User main page
    └── profile/
        └── profile.vue    # User profile page

components Directory

The components directory stores reusable components to improve code reusability.

Features

• Components can be used in multiple pages
• Components can be nested
• Supports easycom specification for automatic registration
• Recommended to categorize by function or business module

Directory Structure Example

components/
├── common/                # Common components
│   ├── navbar.vue
│   └── tabbar.vue
├── form/                  # Form components
│   ├── input.vue
│   └── button.vue
└── business/              # Business components
    └── product-card.vue

static Directory

The static directory stores local static resources referenced by the application.

Resource Types

• Images, videos, audio and other media files
• Font files
• Third-party js, css and other resources
• Other static files

Directory Structure Example

static/
├── images/
│   ├── logo.png
│   └── icons/
│       ├── home.png
│       └── user.png
├── fonts/
│   └── iconfont.ttf
└── js/
    └── third-party.js

uni_modules Directory

The uni_modules directory stores plugins that comply with the uni_module specification.

Features

• Each plugin is a separate directory
• Plugins can include components, JS SDK, page templates, project examples, etc.
• Plugins can be easily imported, exported and shared
• Supports plugin marketplace one-click installation

Directory Structure Example

uni_modules/
├── uni-calendar/
│   ├── components/
│   │   └── uni-calendar/
│   │       └── uni-calendar.vue
│   ├── pages/
│   │   └── calendar/
│   │       └── calendar.vue
│   └── package.json
└── uni-popup/
    ├── components/
    │   └── uni-popup/
    │       └── uni-popup.vue
    └── package.json

uniCloud Directory

The uniCloud directory stores cloud development related files (cloud development projects only).

Main Subdirectories

• cloudfunctions: Cloud functions directory
• database: Database directory, stores database Schema and extension validation functions

Directory Structure Example

uniCloud-aliyun/
├── cloudfunctions/
│   ├── common/
│   │   └── index.js
│   ├── getUser/
│   │   └── index.js
│   └── updateUser/
│       └── index.js
└── database/
    ├── db_init.json
    └── user.schema.json

Special Files Description

File Name	Description
uni.scss	Global style variables file, can define globally common style variables
vue.config.js	Vue CLI configuration file, can customize webpack configuration
package.json	Project configuration file, records project dependencies and script commands
tsconfig.json	TypeScript configuration file (TypeScript projects only)
README.md	Project documentation

Project Structure Best Practices

1. Directory Naming Conventions

• Use lowercase letters and hyphens (kebab-case)
• Directory names should be concise and clear, e.g., user-profile
• Avoid using Chinese characters or special characters

2. Component Classification Management

• Categorize by function: form components, navigation components, layout components, etc.
• Categorize by business: product components, order components, user components, etc.
• Use clear directory structure for easy maintenance

3. Static Resource Management

• Store by type in the static directory
• Group image resources by functional modules
• Reasonably compress image sizes to improve loading performance

4. Unified API Management

• Create api directory to manage interfaces uniformly
• Encapsulate API request functions by business modules
• Uniformly handle request and response interceptors

5. State Management

• Use Vuex to manage global state
• Create store directory, organize code by modules
• Reasonably divide state, mutations, actions

Complete Project Structure Example

my-uni-app/
├── uniCloud-aliyun/            # Cloud development directory (Alibaba Cloud)
├── components/                 # Components directory
│   ├── common/                # Common components
│   │   ├── navbar.vue
│   │   └── tabbar.vue
│   └── business/              # Business components
│       └── product-card.vue
├── pages/                     # Pages directory
│   ├── index/
│   │   └── index.vue         # Home page
│   ├── category/
│   │   └── category.vue      # Category page
│   ├── cart/
│   │   └── cart.vue          # Shopping cart page
│   └── user/
│       └── user.vue          # User page
├── static/                    # Static resources directory
│   ├── images/               # Image resources
│   │   ├── logo.png
│   │   └── icons/
│   │       ├── home.png
│   │       └── user.png
│   └── fonts/                # Font resources
│       └── iconfont.ttf
├── store/                     # Vuex state management
│   ├── index.js              # Entry file
│   └── modules/              # State modules
│       ├── user.js
│       └── cart.js
├── api/                       # API request encapsulation
│   ├── index.js              # API entry
│   ├── request.js            # Request encapsulation
│   └── modules/              # API modules
│       ├── user.js
│       └── product.js
├── utils/                     # Utility functions
│   ├── format.js             # Formatting utilities
│   └── validate.js           # Validation utilities
├── config/                    # Configuration files
│   ├── index.js              # Main configuration
│   └── env.js                # Environment configuration
├── uni_modules/               # uni_module specification plugins
├── main.js                    # Entry file
├── App.vue                    # Application configuration
├── manifest.json              # Build configuration
├── pages.json                 # Page configuration
├── uni.scss                   # Global style variables
└── package.json               # Project configuration

Summary

The uni-app project structure is well-designed, following Vue.js development conventions while being optimized for cross-platform development. Understanding and mastering the project structure is fundamental to developing uni-app applications, helping to:

• Improve development efficiency
• Facilitate team collaboration
• Reduce maintenance costs
• Enhance code quality

It's recommended to flexibly adjust the directory structure according to project scale and team needs in actual development, while maintaining consistency and maintainability.

Related Links

• Lifecycle - Learn about uni-app application and page lifecycle
• Basic Components - Understand how to use uni-app basic components
• API Usage - Learn how to use APIs provided by uni-app