Road_roller/.claude/skills/uni-helper/references/plugin-pages.md

name, description

name	description
vite-plugin-uni-pages	File-based routing system for Vite-powered uni-app projects with automatic page discovery and TypeScript support

vite-plugin-uni-pages

Provides file-based routing for uni-app projects using Vite. Automatically generates pages.json configuration from your file structure.

Installation

npm i -D @uni-helper/vite-plugin-uni-pages

Basic Setup

// vite.config.ts
import Uni from '@dcloudio/vite-plugin-uni'
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'

// Place UniPages before Uni
export default defineConfig({
  plugins: [UniPages(), Uni()],
})

TypeScript Support

Add types to tsconfig.json:

{
  "compilerOptions": {
    "types": ["@uni-helper/vite-plugin-uni-pages"]
  }
}

Global Configuration

Create pages.config.ts (or .js/.json) for global settings:

// pages.config.ts
import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages'

export default defineUniPages({
  // Optional: manual pages have highest priority
  pages: [],
  globalStyle: {
    navigationBarTextStyle: 'black',
    navigationBarTitleText: '@uni-helper',
  },
})

Virtual Module

Access page metadata via virtual module:

/// <reference types="@uni-helper/vite-plugin-uni-pages/client" />
import { pages } from 'virtual:uni-pages'

console.log(pages)

definePage Macro

Define page configuration directly in SFC files:

<script setup lang="ts">
// Object form
definePage({
  style: {
    navigationBarTitleText: 'hello world',
  },
  middlewares: ['auth'],
})

// Function form (supports TypeScript, async)
definePage(() => {
  return {
    style: {
      navigationBarTitleText: 'dynamic title',
    },
  }
})

// Async form
definePage(async () => {
  const title = await fetchTitle()
  return {
    style: { navigationBarTitleText: title },
  }
})
</script>

Important Notes for definePage

• Write inside <script> block
• definePage runs in a different scope than SFC (no access to SFC variables)
• Page path is auto-generated from file path
• Only one definePage per file
• Supports importing external libraries (pure JS only)
• Supports TypeScript type imports (types are stripped)

Using with Condition Compile

<script setup>
import { isH5 } from '@uni-helper/uni-env'

definePage(() => {
  const title = isH5 ? 'H5 Environment' : 'Other Platform'
  return {
    style: { navigationBarTitleText: title },
  }
})
</script>

Configuration Options

export interface Options {
  /** Generate TypeScript declarations */
  dts?: boolean | string  // default: true (outputs uni-pages.d.ts)

  /** Config file pattern */
  configSource: string    // default: 'pages.config.(ts|mts|cts|js|cjs|mjs|json)'

  /** Default home page */
  homePage: string        // default: 'pages/index' or 'pages/index/index'

  /** Merge with existing pages.json */
  mergePages: boolean     // default: true

  /** Pages directory */
  dir: string             // default: 'src/pages'

  /** Sub-packages directories */
  subPackages: string[]   // e.g., ['src/pages-sub']

  /** Output directory for pages.json */
  outDir: string          // default: 'src'

  /** Exclude patterns */
  exclude: string[]       // default: []

  /** Route block language in SFC */
  routeBlockLang: 'json5' | 'jsonc' | 'json' | 'yaml' | 'yml'  // default: 'json5'

  // Lifecycle hooks
  onBeforeLoadUserConfig?: (ctx: PageContext) => void
  onAfterLoadUserConfig?: (ctx: PageContext) => void
  onBeforeScanPages?: (ctx: PageContext) => void
  onAfterScanPages?: (ctx: PageContext) => void
  onBeforeMergePageMetaData?: (ctx: PageContext) => void
  onAfterMergePageMetaData?: (ctx: PageContext) => void
  onBeforeWriteFile?: (ctx: PageContext) => void
  onAfterWriteFile?: (ctx: PageContext) => void
}

Usage with Layouts

<script setup>
definePage({
  layout: 'default',  // Specify layout
  middlewares: ['auth'],
})
</script>