### Install @uni-helper/vite-plugin-uni-pages

Source: https://github.com/uni-helper/vite-plugin-uni-pages/blob/main/packages/core/README.md

Installs the @uni-helper/vite-plugin-uni-pages package as a development dependency using pnpm.

```bash
pnpm i -D @uni-helper/vite-plugin-uni-pages
```

--------------------------------

### Async Page Definition with Dynamic Configuration

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Demonstrates how to use `definePage` with an asynchronous function or a regular function to dynamically configure page metadata. This allows for fetching configurations from an API or reacting to runtime conditions like dark mode.

```vue
<script setup lang="ts">
import { fetchPageConfig } from '@/api/config'

definePage(async () => {
  const config = await fetchPageConfig('dynamic-page')

  return {
    style: {
      navigationBarTitleText: config.title,
      navigationBarBackgroundColor: config.bgColor
    },
    needLogin: config.requireAuth
  }
})

// Or use a regular function
definePage(() => {
  const isDarkMode = uni.getSystemInfoSync().theme === 'dark'

  return {
    style: {
      navigationBarTitleText: 'Dynamic',
      navigationBarBackgroundColor: isDarkMode ? '#000000' : '#ffffff'
    }
  }
})
</script>
```

--------------------------------

### Configure Sub-Packages - TypeScript

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Organize Uni-app pages into sub-packages for better code organization and lazy loading. Define sub-package configurations in pages.config.ts, specifying the root directory and pages within each sub-package. The vite.config.ts file is used to tell the plugin which directories to scan for sub-packages.

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

export default defineUniPages({
  globalStyle: {
    navigationBarTextStyle: 'black',
    navigationBarTitleText: 'App'
  },
  subPackages: [
    {
      root: 'pages-user',
      pages: []  // Auto-discovered from pages-user directory
    },
    {
      root: 'pages-shop',
      pages: [
        {
          path: 'product-detail',
          style: { navigationBarTitleText: 'Product' }
        }
      ]
    }
  ]
})
```

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

export default defineConfig({
  plugins: [
    UniPages({
      dir: 'src/pages',
      subPackages: ['src/pages-user', 'src/pages-shop']
    })
  ]
})
```

--------------------------------

### Define Global Page Properties with pages.config.ts

Source: https://github.com/uni-helper/vite-plugin-uni-pages/blob/main/packages/core/README.md

Defines global properties for uni-app pages using a configuration file. Supports conditional compilation directives like `#ifdef H5`.

```typescript
import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages'

export default defineUniPages({
  pages: [],
  globalStyle: {
    navigationBarTextStyle: 'black',
    navigationBarTitleText: '@uni-helper',
  },
})
```

--------------------------------

### Configure Viewport Meta Tag with CSS Support Check (JavaScript)

Source: https://github.com/uni-helper/vite-plugin-uni-pages/blob/main/packages/playground/index.html

This JavaScript code checks if the browser supports CSS `env()` or `constant()` functions to determine if `viewport-fit=cover` should be included in the meta tag. This ensures optimal display on devices with notches or cutouts.

```javascript
var coverSupport = 'CSS' in window && typeof CSS.supports === 'function' && (CSS.supports('top: env(a)') || CSS.supports('top: constant(a)'))
document.write( '<meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0' + (coverSupport ? ', viewport-fit=cover' : '') + '" />')
```

--------------------------------

### Configure Vite with @uni-helper/vite-plugin-uni-pages

Source: https://github.com/uni-helper/vite-plugin-uni-pages/blob/main/packages/core/README.md

Configures Vite to use the @uni-helper/vite-plugin-uni-pages plugin. It's recommended to place this plugin before the Uni plugin for proper initialization.

```typescript
import Uni from '@dcloudio/vite-plugin-uni'
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [UniPages(), Uni()],
})
```

--------------------------------

### Define Global pages.json Configuration in TypeScript

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Utilizes `defineUniPages` to declare global settings for `pages.json` within a TypeScript file. This allows for centralized configuration of global styles, page lists, sub-packages, and tabBar items.

```typescript
import { defineUniPages } from '@uni-helper/vite-plugin-uni-pages'

export default defineUniPages({
  globalStyle: {
    navigationBarTextStyle: 'black',
    navigationBarTitleText: '@uni-helper',
    navigationBarBackgroundColor: '#F8F8F8',
    backgroundColor: '#F8F8F8',
    enablePullDownRefresh: false
  },
  pages: [
    // Manually defined pages (optional, auto-discovered pages will be merged)
  ],
  subPackages: [
    {
      root: 'pages-sub',
      pages: []
    }
  ],
  tabBar: {
    color: '#7A7E83',
    selectedColor: '#3cc51f',
    borderStyle: 'black',
    backgroundColor: '#ffffff',
    list: [
      {
        pagePath: 'pages/index',
        iconPath: 'static/tab-home.png',
        selectedIconPath: 'static/tab-home-active.png',
        text: 'Home'
      },
      {
        pagePath: 'pages/profile',
        iconPath: 'static/tab-profile.png',
        selectedIconPath: 'static/tab-profile-active.png',
        text: 'Profile'
      }
    ]
  }
})
```

--------------------------------

### Add Route Meta-data using SFC Route Block

Source: https://github.com/uni-helper/vite-plugin-uni-pages/blob/main/packages/core/README.md

Adds custom route meta-data to SFCs by using a `<route>` block. Supports JSON, JSON5, and YAML formats, with JSON5 as the default parser. This meta-data overrides the generated route information.

```html
<!-- index.vue -->
<route type="home">
{
  "style": { "navigationBarTitleText": "@uni-helper" }
}
</route>

<!-- other.vue -->
<route lang="yaml">
style:
  navigationBarTitleText: "@uni-helper"
</route>
```

--------------------------------

### Define Platform-Specific Pages - Vue

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Implement platform-specific configurations for Uni-app pages using conditional compilation directives within Vue components. This allows for tailoring page styles, such as navigation bar titles, based on the target platform (e.g., H5, WeChat Mini Program).

```vue
<!-- pages/platform-specific.vue -->
<script setup lang="ts">
definePage({
  style: {
    // #ifdef H5
    navigationBarTitleText: 'H5 Page',
    // #endif
    // #ifdef MP-WEIXIN
    navigationBarTitleText: '微信小程序页面',
    // #endif
    navigationBarBackgroundColor: '#ffffff'
  }
})
</script>
```

--------------------------------

### Define Page-Level Metadata in Vue Components

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Uses the `definePage` macro within a Vue component's script section to specify page-specific configurations. This includes styling, login requirements, and tabBar item details, overriding or supplementing global settings.

```vue
<script setup lang="ts">
definePage({
  type: 'home',
  style: {
    navigationBarTitleText: 'Home Page',
    navigationBarBackgroundColor: '#ffffff',
    navigationStyle: 'custom',
    enablePullDownRefresh: true,
    onReachBottomDistance: 50
  },
  needLogin: false,
  tabBar: {
    text: 'Home',
    iconPath: '/static/home.png',
    selectedIconPath: '/static/home-active.png',
    index: 0
  }
})

const handleRefresh = () => {
  // Pull down refresh logic
  console.log('Refreshing...')
}
</script>

<template>
  <view class="container">
    <text>Welcome to uni-app!</text>
  </view>
</template>
```

--------------------------------

### Access All Page Metadata via Virtual Module

Source: https://github.com/uni-helper/vite-plugin-uni-pages/blob/main/packages/core/README.md

Imports and accesses the metadata of all generated pages through a virtual module provided by the plugin. This allows for dynamic access to page information within your application.

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

console.log(pages)
```

--------------------------------

### Access Page Metadata with Virtual Module - TypeScript

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Import and access page routes programmatically using the virtual module provided by vite-plugin-uni-pages. This allows for type-safe access to page metadata, navigation, and filtering of pages based on properties like 'needLogin'.

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

// Type-safe page metadata access
console.log('All pages:', pages)
console.log('Sub packages:', subPackages)

// Navigate to a specific page
const homePage = pages.find(p => p.type === 'home')
if (homePage) {
  uni.navigateTo({ url: `/${homePage.path}` })
}

// Get pages that require login
const protectedPages = pages.filter(p => p.needLogin)
console.log('Protected routes:', protectedPages)

// Access sub-package pages
subPackages.forEach(pkg => {
  console.log(`Package ${pkg.root} has ${pkg.pages.length} pages`)
  pkg.pages.forEach(page => {
    console.log(`  - ${page.path}`)
  })
})
```

--------------------------------

### Configure PageContext Lifecycle Hooks - TypeScript

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Customize page generation by implementing lifecycle hooks within the vite-plugin-uni-pages configuration in vite.config.ts. These hooks allow for custom logic execution before and after various stages of the page processing pipeline, such as loading configuration, scanning pages, and merging metadata.

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

export default defineConfig({
  plugins: [
    UniPages({
      onBeforeLoadUserConfig: (ctx) => {
        console.log('Loading user config from:', ctx.pagesConfigSourcePaths)
      },
      onAfterLoadUserConfig: (ctx) => {
        console.log('Loaded config:', ctx.pagesGlobConfig)
      },
      onBeforeScanPages: (ctx) => {
        console.log('Scanning directories:', ctx.options.dirs)
      },
      onAfterScanPages: (ctx) => {
        console.log(`Found ${ctx.pages.size} pages`)
        // Modify pages before generation
        ctx.pages.forEach((page, path) => {
          console.log(`  ${path} -> ${page.uri}`)
        })
      },
      onBeforeMergePageMetaData: (ctx) => {
        // Custom logic before merging
      },
      onAfterMergePageMetaData: (ctx) => {
        console.log('Page metadata:', ctx.pageMetaData)
        console.log('Sub-package metadata:', ctx.subPageMetaData)
      },
      onBeforeWriteFile: (ctx) => {
        console.log('Writing to:', ctx.resolvedPagesJSONPath)
      },
      onAfterWriteFile: (ctx) => {
        console.log('pages.json written successfully')
      }
    }),
    Uni()
  ]
})
```

--------------------------------

### Configure Vite Plugin Uni Pages in vite.config.ts

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Integrates the @uni-helper/vite-plugin-uni-pages into your Vite configuration. This snippet demonstrates how to set up the plugin with various options like directory scanning, output directory, sub-package definitions, and event hooks.

```typescript
import Uni from '@dcloudio/vite-plugin-uni'
import UniPages from '@uni-helper/vite-plugin-uni-pages'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [
    UniPages({
      dir: 'src/pages',
      outDir: 'src',
      subPackages: ['src/pages-sub'],
      homePage: 'pages/index',
      exclude: ['node_modules', '.git', '**/__*__/**'],
      routeBlockLang: 'json5',
      minify: false,
      dts: true,
      mergePages: true,
      onBeforeScanPages: (ctx) => {
        console.log('Starting page scan...')
      },
      onAfterWriteFile: (ctx) => {
        console.log('pages.json generated successfully')
      }
    }),
    Uni()
  ]
})
```

--------------------------------

### Enable Debug Mode - TypeScript

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Activate debug mode in vite-plugin-uni-pages to enable detailed logging for troubleshooting. You can enable all debug logs by setting `debug: true`, or specify specific categories like 'pages', 'options', or 'cache' to filter the logs.

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

export default defineConfig({
  plugins: [
    UniPages({
      debug: true,  // Enable all debug logs
      // Or enable specific debug categories
      // debug: 'pages'  // Only page scanning logs
      // debug: 'options'  // Only option logs
      // debug: 'cache'  // Only cache logs
    })
  ]
})
```

--------------------------------

### TypeScript Interface for @uni-helper/vite-plugin-uni-pages Options

Source: https://github.com/uni-helper/vite-plugin-uni-pages/blob/main/packages/core/README.md

Defines the TypeScript interface for the configuration options of the @uni-helper/vite-plugin-uni-pages plugin. Includes options for page merging, directory scanning, exclusion patterns, route block parsing, and various lifecycle hooks.

```typescript
export interface Options {
  /**
   * Whether to scan and merge pages in pages.json
   * @default true
   */
  mergePages: boolean

  /**
   * Paths to the directory to search for page components.
   * @default 'src/pages'
   */
  dir: string

  /**
   * pages.json dir
   * @default "src"
   */
  outDir: string

  /**
   * exclude page
   * @default []
   */
  exclude: string[]

  /**
   * Set the default route block parser, or use `<route lang="xxx">` in SFC route block
   * @default 'json5'
   */
  routeBlockLang: 'json5' | 'jsonc' | 'json' | 'yaml' | 'yml'

  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
}
```

--------------------------------

### Generate TypeScript Declarations - TypeScript

Source: https://context7.com/uni-helper/vite-plugin-uni-pages/llms.txt

Enable type-safe page path autocompletion by configuring vite-plugin-uni-pages to generate TypeScript declaration files (.d.ts). This feature provides type safety when navigating to pages and accessing page metadata.

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

export default defineConfig({
  plugins: [
    UniPages({
      dts: true,  // Generates uni-pages.d.ts at project root
      // Or specify custom path
      // dts: 'types/uni-pages.d.ts'
    })
  ]
})
```

```typescript
// Usage with generated types
import type { PageMetaDatum } from 'uni-pages'

function navigateToPage(pagePath: string) {
  // TypeScript will provide autocomplete for valid page paths
  uni.navigateTo({ url: `/${pagePath}` })
}

// Type-safe page metadata
const getPageMeta = (path: string): PageMetaDatum | undefined => {
  return pages.find(p => p.path === path)
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.