uni-app Frontend Development

Comprehensive guide for building cross-platform apps with uni-app, Vue 3, and TypeScript.

Quick Start

Create a New Page

# Create page directory
mkdir -p src/pages/newpage

# Create page files
touch src/pages/newpage/index.vue

Register Page in pages.json

{
  "pages": [
    {
      "path": "pages/newpage/index",
      "style": {
        "navigationBarTitleText": "Page Title"
      }
    }
  ]
}

Basic Page Template

See assets/page-template.vue for a complete page template.

Project Structure

Standard uni-app CLI project structure:

src/
├── pages/          # Page components (one per directory)
├── components/     # Shared/reusable components
├── store/          # Pinia state management
├── api/            # API interface definitions
├── utils/          # Utility functions
├── types/          # TypeScript type definitions
├── styles/         # Global styles
│   ├── theme.scss       # Theme variables
│   └── common.scss      # Common styles
├── static/         # Static assets (images, icons)
├── App.vue         # App root component
├── main.ts         # App entry point
├── pages.json      # Page and tabBar configuration
└── uni.scss        # uni-app built-in variables

UI Library Integration

uView Plus

Installation:

npm install uview-plus

Configuration:

App.vue - Import styles:

<style lang="scss">
@import "uview-plus/index.scss";
@import "@/styles/common.scss";
</style>

main.ts - Register plugin:

import uviewPlus from "uview-plus";
app.use(uviewPlus);

vite.config.ts - Global SCSS:

css: {
  preprocessorOptions: {
    scss: {
      additionalData: `@import "@/styles/theme.scss";@import "uview-plus/theme.scss";`,
      api: "modern-compiler",
    },
  },
}

Other UI Libraries

uni-ui (official):

npm install @dcloudio/uni-ui

TuniaoUI (Tuniao):

npm install @tuniao/tnui-vue3-uniapp

See references/ui-libraries.md for integration guides.

Theme System Design

Implement flexible theming for multi-role or multi-brand applications.

Basic Theme Setup

src/styles/theme.scss:

// Theme colors
$theme-primary: #1890ff;
$theme-success: #52c41a;
$theme-warning: #faad14;
$theme-error: #f5222d;

// Neutral colors
$color-text-primary: #333333;
$color-text-regular: #666666;
$color-text-secondary: #999999;

$color-bg-page: #f5f5f5;
$color-bg-card: #ffffff;

// Spacing scale
$spacing-xs: 8rpx;
$spacing-sm: 16rpx;
$spacing-md: 24rpx;
$spacing-lg: 32rpx;
$spacing-xl: 48rpx;

// Typography
$font-size-xs: 20rpx;
$font-size-sm: 24rpx;
$font-size-base: 28rpx;
$font-size-lg: 32rpx;
$font-size-xl: 36rpx;

// Border radius
$border-radius-sm: 4rpx;
$border-radius-md: 8rpx;
$border-radius-lg: 16rpx;
$border-radius-circle: 50%;

vite.config.ts - Inject globally:

css: {
  preprocessorOptions: {
    scss: {
      additionalData: `@import "@/styles/theme.scss";`,
      api: "modern-compiler",
    },
  },
}

Multi-Theme Implementation

For apps requiring multiple themes (e.g., user/admin, different brands):

Option 1: Theme variables per environment

// src/styles/theme.scss
// Define different theme color sets
$theme-user-primary: #1890ff;
$theme-admin-primary: #0050b3;

// Set active theme
$theme-primary: $theme-user-primary; // Change based on build/env

Option 2: Dynamic theme switching

// store/theme.ts
import { defineStore } from 'pinia';

export const useThemeStore = defineStore('theme', {
  state: () => ({
    currentTheme: 'default',
  }),

  getters: {
    themeColors() {
      const themes = {
        default: { primary: '#1890ff' },
        dark: { primary: '#0050b3' },
      };
      return themes[this.currentTheme];
    },
  },
});

See references/theme-guide.md for complete theming patterns.

Build Commands

# WeChat Mini Program
npm run dev:mp-weixin      # Development
npm run build:mp-weixin    # Production

# H5
npm run dev:h5             # Development
npm run build:h5           # Production

# Other platforms
npm run dev:mp-alipay       # Alipay Mini Program
npm run dev:mp-baidu       # Baidu Mini Program
npm run dev:mp-toutiao     # Toutiao Mini Program

Common Patterns

Data Fetching Pattern

<script setup lang="ts">
import { ref, onMounted } from "vue";

interface Item {
  id: number;
  title: string;
}

const items = ref<Item[]>([]);
const loading = ref(false);
const error = ref<string | null>(null);

onMounted(() => {
  loadData();
});

const loadData = async () => {
  loading.value = true;
  error.value = null;
  try {
    const data = await api.getItems();
    items.value = data;
  } catch (err) {
    error.value = "Failed to load data";
    uni.showToast({ title: error.value, icon: "none" });
  } finally {
    loading.value = false;
  }
};
</script>

Navigation Patterns

// Navigate to page (adds to history stack)
uni.navigateTo({ url: "/pages/detail/index" });

// Navigate with parameters
uni.navigateTo({ url: `/pages/detail/index?id=${id}&type=parcel` });

// Redirect (replaces current page, no back button)
uni.redirectTo({ url: "/pages/login/index" });

// Switch to tabBar page
uni.switchTab({ url: "/pages/home/index" });

// Navigate back
uni.navigateBack();

// Launch another mini program
uni.navigateToMiniProgram({
  appId: "xxxxx",
  path: "pages/index/index",
});

User Feedback

Toast:

uni.showToast({
  title: "Success",
  icon: "success",
  duration: 2000,
});

uni.showToast({
  title: "Error message",
  icon: "none",
});

// Loading toast
uni.showLoading({ title: "Loading..." });
uni.hideLoading();

Modal:

uni.showModal({
  title: "Confirm",
  content: "Are you sure?",
  success: (res) => {
    if (res.confirm) {
      // User clicked confirm
    }
  },
});

Action Sheet:

uni.showActionSheet({
  itemList: ["Option 1", "Option 2", "Option 3"],
  success: (res) => {
    console.log("Selected:", res.tapIndex);
  },
});

Lifecycle Hooks

<script setup lang="ts">
import {
  onLaunch,
  onShow,
  onHide,
  onUnload,
} from "@dcloudio/uni-app";

import { onLoad, onReady, onReachBottom, onPullDownRefresh } from "@dcloudio/uni-app";

// App-level hooks (use in App.vue)
onLaunch(() => {
  console.log("App launched");
});

onShow(() => {
  console.log("App shown");
});

// Page-level hooks (use in pages)
onLoad((options) => {
  console.log("Page loaded with params:", options);
});

onReady(() => {
  console.log("Page ready");
});

onReachBottom(() => {
  console.log("Reached bottom - load more");
});

onPullDownRefresh(() => {
  console.log("Pull down refresh");
  // Stop loading after data fetch
  uni.stopPullDownRefresh();
});
</script>

Platform Detection

// Get platform info
const systemInfo = uni.getSystemInfoSync();
console.log("Platform:", systemInfo.platform); // ios, android, devtools
console.log("System:", systemInfo.system);     // iOS 14.5, Android 10

// Conditional code based on platform
// #ifdef H5
console.log("Running on H5");
// #endif

// #ifdef MP-WEIXIN
console.log("Running on WeChat Mini Program");
// #endif

// #ifdef MP-ALIPAY
console.log("Running on Alipay Mini Program");
// #endif

Pinia State Management

Store definition:

// src/store/user.ts
import { defineStore } from 'pinia';

export const useUserStore = defineStore('user', {
  state: () => ({
    userInfo: null,
    token: '',
  }),

  getters: {
    isLoggedIn: (state) => !!state.token,
  },

  actions: {
    async login(credentials) {
      const data = await api.login(credentials);
      this.token = data.token;
      this.userInfo = data.user;
    },

    logout() {
      this.token = '';
      this.userInfo = null;
    },
  },
});

Use in component:

<script setup lang="ts">
import { useUserStore } from "@/store/user";

const userStore = useUserStore();

// Access state
console.log(userStore.userInfo);

// Call actions
await userStore.login({ username, password });

// Use getters
if (userStore.isLoggedIn) {
  // ...
}
</script>

API Integration

API module:

// src/api/index.ts
const BASE_URL = "https://api.example.com";

export const api = {
  // GET request
  async getItems() {
    const res = await uni.request({
      url: `${BASE_URL}/items`,
      method: "GET",
    });
    return res.data;
  },

  // POST request
  async createItem(data: any) {
    const res = await uni.request({
      url: `${BASE_URL}/items`,
      method: "POST",
      data,
    });
    return res.data;
  },
};

With interceptors:

// src/utils/request.ts
let token = "";

export const request = (options: UniApp.RequestOptions) => {
  // Add token
  if (token) {
    options.header = {
      ...options.header,
      Authorization: `Bearer ${token}`,
    };
  }

  return uni.request(options);
};

// Set token after login
export const setToken = (newToken: string) => {
  token = newToken;
};

Troubleshooting

SCSS Variables Not Found

Error: Undefined variable $spacing-md

Solutions:

1. Check vite.config.ts has additionalData configuration
2. Verify theme file path is correct
3. Restart dev server after config changes

Components Not Rendering

Check:

1. Component registered in pages.json
2. Correct import path (use @/ alias)
3. Component name in PascalCase for Vue components

Build Errors

Common fixes:

1. Clear cache: rm -rf node_modules dist && npm install
2. Check Node.js version (use LTS)
3. Verify dependencies are compatible

Platform-Specific Issues

WeChat Mini Program:

• Ensure appid is correct in manifest.json
• Check domain whitelist in Mini Program admin console
• Test in WeChat DevTools

H5:

• Test in multiple browsers
• Check CORS configuration
• Verify API endpoints support HTTPS

Resources

references/theme-guide.md

Complete theme system design with multi-theme patterns, color theory, and implementation strategies.

references/ui-libraries.md

Integration guides for uView Plus, uni-ui, TuniaoUI, and other popular UI libraries.

references/page-patterns.md

Reusable page patterns: list pages, detail pages, forms, search/filter, empty states, etc.

references/platform-specific.md

Platform-specific considerations and best practices for WeChat, Alipay, H5, etc.

assets/page-template.vue

Minimal Vue 3 + TypeScript page template ready to customize.

assets/component-templates/

Common component templates (card, button-group, list-item, etc.).

Best Practices

1. Use TypeScript - Catch errors at compile time
2. Component composition - Keep components small and focused
3. State management - Use Pinia for complex state
4. Error handling - Always handle API errors gracefully
5. Loading states - Show loading indicators during async operations
6. Responsive design - Test on multiple screen sizes
7. Performance - Lazy load images and long lists
8. Accessibility - Use semantic HTML and ARIA labels
9. Code organization - Follow consistent file structure
10. Version control - Commit frequently with meaningful messages