Project Initialization and Environment Setup

Ensure the local environment meets the Node.js version requirements (^14.18.0 or >=16.0.0). Use the official UniApp preset to scaffold the project structure via degit:

npx degit dcloudio/uni-preset-vue#vite my-cross-platform-app
cd my-cross-platform-app

Install dependencies using pnpm. If registry issues occur, configure the npm registry to resolve them.

pnpm install

Run the development command to compile the WeChat Mini-program. This generates a dist/dev/mp-weixin directory, which should be imported into WeChat Developer Tools for debugging.

pnpm dev:mp-weixin

Automated Imports Configuration

To eliminate repetitive import statements for Vue and UniApp APIs, integrate unplugin-auto-import.

pnpm add -D unplugin-auto-import

Modify vite.config.js to include the plugin. This generates an auto-imports.d.ts file, enabling direct usage of Composition API methods like ref and computed without explicit imports.

import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
import AutoImport from 'unplugin-auto-import/vite'

export default defineConfig({
  plugins: [
    uni(),
    AutoImport({
      imports: ['vue', 'uni-app'],
      dts: 'src/auto-imports.d.ts',
    })
  ]
})

Atomic CSS with UnoCSS

Install UnoCSS and relevant presets for broad compatibility across H5 and Mini-program platforms.

pnpm add -D unocss @unocss/preset-uno @iconify-json/ep

Create unocss.config.ts at the project root. Configure presets to handle platform-specific transformations, such as converting rem to rpx for Mini-programs.

import { defineConfig, presetUno, presetIcons } from 'unocss'
import { presetApplet } from 'unocss-applet'

export default defineConfig({
  presets: [
    presetApplet(),
    presetUno(),
    presetIcons({ scale: 1.2 }),
  ],
  shortcuts: {
    'flex-center': 'flex justify-center items-center',
  },
})

Register the CSS in main.js and add the Vite plugin. Components can then use atomic classes like text-red-500 or icons like i-ep-apple.

State Management with Pinia

Implement Pinia for state management, ensuring persistence across page reloads using storage adapters compatible with the Mini-program environment.

pnpm add pinia pinia-plugin-persistedstate

Configure the store to use uni.getStorageSync and uni.setStorageSync for storage operations, as localStorage is unavailable in the Mini-program context.

// src/store/index.js
import { createPinia } from 'pinia'
import { createPersistedState } from 'pinia-plugin-persistedstate'

const pinia = createPinia()
pinia.use(createPersistedState({
  storage: {
    getItem: (key) => uni.getStorageSync(key),
    setItem: (key, value) => uni.setStorageSync(key, value),
  },
}))

export default pinia

Define a store module using defineStore with persist: true enabled.

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

export const useUserStore = defineStore('user', {
  state: () => ({ token: '' }),
  actions: {
    setToken(val) { this.token = val }
  },
  persist: true
})

Network Request Architecture

Standardize API requests using Axios and a UniApp adapter. This allows for a consistent request/response interception strategy similar to standard web applications.

pnpm add axios @uni-helper/axios-adapter

Create a service instance that adapts Axios for UniApp. Modularize API endpoints to keep the codebase organized.

// src/api/modules/user.js
import request from '../utils/request'

export const fetchUserInfo = (params) => {
  return request({
    url: '/user/info',
    method: 'GET',
    params
  })
}

Implement a central request utility that handles global errors, token injection, and loading states.

// src/utils/request.js
import axios from 'axios'
import { createUniAppAxiosAdapter } from '@uni-helper/axios-adapter'

const service = axios.create({
  adapter: createUniAppAxiosAdapter(),
  baseURL: import.meta.env.VITE_APP_BASE_URL,
  timeout: 10000,
})

service.interceptors.response.use(
  response => response.data,
  error => {
    uni.showToast({ title: 'Network Error', icon: 'none' })
    return Promise.reject(error)
  }
)

export default service

Code Quality and Commit Standards

Integrate Husky and lint-staged to enforce code standards automatically during commits. This ensures that ESLint, Prettier, and Stylelint checks run against staged files.

pnpm add -D husky lint-staged @commitlint/cli @commitlint/config-conventional

Configure package.json to define lint-staged commands.

{
  "scripts": {
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.{js,vue,ts}": ["eslint --fix", "prettier --write"],
    "*.{css,scss,vue}": ["stylelint --fix"]
  }
}

Use Commitlint to enforce conventional commit messages, facilitating automated changelog generation and readable git history.