pages.json Page Information

pages.json is the central configuration file for routing and application-level presentation in a uni-app project. It def

pages.json is the central configuration file for routing and application-level presentation in a uni-app project. It defines which pages exist, determines the initial page displayed at launch, establishes shared window styles, and configures features such as tab bars and subpackages. Because the framework generates routes from this file, every page must be registered before it can be opened or navigated to.
The pages array is the most important part of the configuration. Each entry represents one page and normally contains a path property and an optional style object:

{
  "pages": [
    {
      "path": "pages/index/index",
      "style": {
        "navigationBarTitleText": "Home",
        "enablePullDownRefresh": true
      }
    },
    {
      "path": "pages/detail/detail",
      "style": {
        "navigationBarTitleText": "Details"
      }
    }
  ]
}

The path is relative to the project root and should point to the page component without including the .vue extension. Paths must also match the actual file names, including capitalization.

The first item in the array becomes the application’s launch page. Its position therefore matters: moving the home page elsewhere in the array can unintentionally change the application’s starting point.

A page-level style overrides the corresponding defaults in globalStyle. This makes it possible to share a common visual baseline while giving individual pages their own titles, colors, or pull-to-refresh behavior. Any newly created page that is not listed under pages will not have a generated route, even if its component file exists.

Defining Global Window Styles

The globalStyle section controls the default appearance of every page:

{
  "globalStyle": {
    "navigationBarTitleText": "My Application",
    "navigationBarBackgroundColor": "#FFFFFF",
    "navigationBarTextStyle": "black",
    "backgroundColor": "#F8F8F8",
    "onReachBottomDistance": 50
  }
}

Common settings include:

  • navigationBarTitleText sets the default navigation-bar title.
  • navigationBarBackgroundColor controls the navigation-bar background.
  • navigationBarTextStyle sets the title color to either black or white.
  • backgroundColor defines the default page background.
  • onReachBottomDistance specifies how close the user must scroll to the bottom before the page’s scroll-to-bottom event is triggered.
  • enablePullDownRefresh enables pull-to-refresh by default when set to true.
  • navigationStyle: "custom" removes the native navigation bar so the page can provide its own header.

Page-specific values always take precedence over global defaults. For example, a page can use the standard application navigation bar while another page disables it for a more immersive layout.

When using a custom navigation bar, the application must account for the status bar itself. Without suitable spacing, the page content may overlap the status area on devices with a notch or other system indicators.

Configuring a Tab Bar

Applications with several peer sections commonly use tabBar to provide persistent navigation:

{
  "tabBar": {
    "color": "#7A7E83",
    "selectedColor": "#007AFF",
    "list": [
      {
        "pagePath": "pages/index/index",
        "text": "Home",
        "iconPath": "static/tab/home.png",
        "selectedIconPath": "static/tab/home-active.png"
      },
      {
        "pagePath": "pages/mine/mine",
        "text": "Profile",
        "iconPath": "static/tab/mine.png",
        "selectedIconPath": "static/tab/mine-active.png"
      }
    ]
  }
}

Each item in list connects a tab to a registered page through pagePath. The optional text appears as the tab label, while iconPath and selectedIconPath provide the normal and active icon states.

The built-in tab bar requires between two and five entries. Every referenced page must already exist in the pages array. Icons should be local image assets, and the conventional recommendation is to use PNG files measuring 81 × 81 pixels. Remote images and icon fonts are not suitable for this native tab-bar implementation.

Subpackages and Preloading

Large applications can reduce the size of the main package by moving less frequently used features into subpackages:

{
  "subPackages": [
    {
      "root": "package-profile",
      "pages": [
        {
          "path": "settings/index"
        },
        {
          "path": "orders/index"
        }
      ]
    }
  ]
}

Subpackage pages remain part of the application’s route system, but their code is loaded separately. This can shorten the initial startup process by keeping the main package focused on essential features.

A preloadRule can instruct uni-app to download a subpackage before the user explicitly enters it:

{
  "preloadRule": {
    "pages/index/index": {
      "network": "all",
      "packages": ["package-profile"]
    }
  }
}

Here, visiting the home page creates an opportunity to preload the profile package in the background. Preloading rules should be used selectively. Downloading every possible package too early may consume bandwidth and storage without providing a useful performance benefit.

Development and Component Configuration

The condition section can define special launch scenarios for development and testing. It allows a particular page, and sometimes a set of query parameters, to be opened directly while debugging rather than navigating through the entire application flow.

The easycom section provides automatic component-import rules. Under a suitable naming convention, matching components can be used in templates without manually importing them in every file. This reduces repetitive code and keeps component usage consistent across the project.

Common Pitfalls

Several issues can cause confusing results:

  1. Omitting a page registration: Creating a component file does not automatically create a route. The page must also appear in pages.
  2. Incorrect path formatting: Do not add .vue to a page path, and avoid unnecessary leading slashes or filename differences.
  3. Case mismatches: Page paths are case-sensitive in many build and runtime environments. pages/Index/Index and pages/index/index should not be treated as interchangeable.
  4. Expecting hot reload to apply every change: Some routing or tab-bar changes require a fresh compilation before they appear.
  5. Using strict JSON tooling: uni-app permits comments in pages.json, although generic JSON validators and parsers may reject them.
  6. Overlooking custom navigation layouts: Setting navigationStyle to custom transfers responsibility for status-bar spacing and safe-area handling to the developer.

A reliable pages.json should be organized around clear route naming, consistent styling, and realistic performance needs. Register core screens in the main package, move secondary features into subpackages, and introduce preloading only where it improves the user journey. Treating this file as the structural foundation of the application makes routing easier to maintain and helps prevent configuration problems from spreading across the entire project.