# Uniapp Frontend

> uni-app cross-platform frontend development with Vue 3 + TypeScript. Use for: (1) Creating new uni-app projects or pages, (2) Integrating UI libraries (uView Plus, uni-ui, TuniaoUI), (3) Implementing multi-theme design systems, (4) Building WeChat Mini Programs, H5, and other platforms, (5) Setting up SCSS theming and global styles, (6) Configuring Vite build system. Includes reusable templates,…

- **Type:** Skill
- **Install:** `agentstack add skill-enze00-uniapp-frontend-skills-uniapp-frontend-skills`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [enze00](https://agentstack.voostack.com/s/enze00)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [enze00](https://github.com/enze00)
- **Source:** https://github.com/enze00/uniapp-frontend-skills

## Install

```sh
agentstack add skill-enze00-uniapp-frontend-skills-uniapp-frontend-skills
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# uni-app Frontend Development

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

## Quick Start

### Create a New Page

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

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

### Register Page in pages.json

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

### Basic Page Template

See [assets/page-template.vue](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:**
```bash
npm install uview-plus
```

**Configuration:**

App.vue - Import styles:
```vue

@import "uview-plus/index.scss";
@import "@/styles/common.scss";

```

main.ts - Register plugin:
```typescript
import uviewPlus from "uview-plus";
app.use(uviewPlus);
```

vite.config.ts - Global SCSS:
```typescript
css: {
  preprocessorOptions: {
    scss: {
      additionalData: `@import "@/styles/theme.scss";@import "uview-plus/theme.scss";`,
      api: "modern-compiler",
    },
  },
}
```

### Other UI Libraries

**uni-ui** (official):
```bash
npm install @dcloudio/uni-ui
```

**TuniaoUI** (Tuniao):
```bash
npm install @tuniao/tnui-vue3-uniapp
```

See [references/ui-libraries.md](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:**
```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:
```typescript
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**
```scss
// 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**
```typescript
// 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](references/theme-guide.md) for complete theming patterns.

## Build Commands

```bash
# 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

```vue

import { ref, onMounted } from "vue";

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

const items = ref([]);
const loading = ref(false);
const error = ref(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;
  }
};

```

### Navigation Patterns

```typescript
// 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:**
```typescript
uni.showToast({
  title: "Success",
  icon: "success",
  duration: 2000,
});

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

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

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

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

### Lifecycle Hooks

```vue

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();
});

```

## Platform Detection

```typescript
// 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:**
```typescript
// 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:**
```vue

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) {
  // ...
}

```

## API Integration

**API module:**
```typescript
// 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:**
```typescript
// 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [enze00](https://github.com/enze00)
- **Source:** [enze00/uniapp-frontend-skills](https://github.com/enze00/uniapp-frontend-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-enze00-uniapp-frontend-skills-uniapp-frontend-skills
- Seller: https://agentstack.voostack.com/s/enze00
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.