or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application-mounting.mdhistory-management.mdindex.mdnavigation-apis.mdrouter-creation.mdutility-functions.md
tile.json

tessl/npm-tarojs--router

A routing system for H5 (web) applications in the Taro cross-platform framework, providing compatibility with mini-program routing specifications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@tarojs/router@4.1.x

To install, run

npx @tessl/cli install tessl/npm-tarojs--router@4.1.0

index.mddocs/

@tarojs/router

@tarojs/router is a comprehensive H5 routing system for the Taro cross-platform framework, providing compatibility with mini-program routing specifications. It supports both single-page (SPA) and multi-page (MPA) application modes, includes navigation APIs, history management, and UI components for creating web applications that follow mini-program conventions.

Package Information

  • Package Name: @tarojs/router
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @tarojs/router
  • Node Version: >= 18

Core Imports

import { createRouter, createMultiRouter } from "@tarojs/router";

For navigation APIs:

import { navigateTo, navigateBack, redirectTo, switchTab, reLaunch } from "@tarojs/router";

For history management:

import { setHistoryMode, setHistory, createMpaHistory, prependBasename } from "@tarojs/router";

For standard history creation:

import { createBrowserHistory, createHashHistory } from "@tarojs/router";

Basic Usage

Single-Page Application Router

import { createRouter, setHistoryMode } from "@tarojs/router";

// Set up history mode (hash, browser, or multi)
setHistoryMode("hash", "/");

// Create SPA router
const router = createRouter(history, app, {
  routes: [
    { path: "/home", load: () => import("./pages/home") },
    { path: "/profile", load: () => import("./pages/profile") }
  ],
  router: {
    mode: "hash",
    basename: "/",
    pathname: "/home"
  },
  pages: ["/home", "/profile"]
}, "react");

Navigation

import { navigateTo, navigateBack } from "@tarojs/router";

// Navigate to a new page
await navigateTo({
  url: "/profile?id=123",
  success: (res) => console.log("Navigation successful"),
  fail: (err) => console.error("Navigation failed", err)
});

// Navigate back
await navigateBack({
  delta: 1 // Number of pages to go back
});

Architecture

@tarojs/router is built around several key components:

  • Router Engines: SPA and MPA router implementations with page lifecycle management
  • Navigation API: Mini-program compatible navigation functions (navigateTo, redirectTo, etc.)
  • History Management: Browser and hash history with custom MPA history implementation
  • Application Mounting: Functions to mount the app with or without tabbar support
  • Utility Functions: Route alias management, navigation bar control, and mobile detection

Capabilities

Router Creation

Core router creation functions for SPA and MPA applications with full lifecycle support and page stack management.

function createRouter(
  history: History,
  app: AppInstance,
  config: SpaRouterConfig,
  framework?: string
): () => void;

function createMultiRouter(
  history: History,
  app: AppInstance,
  config: MpaRouterConfig,
  framework?: string
): Promise<void>;

Router Creation

Navigation APIs

Mini-program compatible navigation system with promise-based callbacks and page stack management.

function navigateTo(option: Taro.navigateTo.Option): Promise<TaroGeneral.CallbackResult>;
function redirectTo(option: Taro.redirectTo.Option): Promise<TaroGeneral.CallbackResult>;
function navigateBack(option?: Taro.navigateBack.Option): Promise<TaroGeneral.CallbackResult>;
function switchTab(option: Taro.switchTab.Option): Promise<TaroGeneral.CallbackResult>;
function reLaunch(option: Taro.reLaunch.Option): Promise<TaroGeneral.CallbackResult>;

Navigation APIs

History Management

Browser history abstraction with support for hash, browser, and multi-page modes with custom routing behavior.

function setHistoryMode(mode?: IH5RouterConfig['mode'], base?: string): void;
function setHistory(h: History, base?: string): void;
function createMpaHistory(options?: HashHistoryOptions | BrowserHistoryOptions): MpaHistory;
function prependBasename(url?: string): string;

History Management

Application Mounting

Application mounting functions for setting up the H5 app with or without tabbar support.

function handleAppMount(config: SpaRouterConfig | MpaRouterConfig, history: History, appId?: string): void;
function handleAppMountWithTabbar(config: SpaRouterConfig | MpaRouterConfig, history: History, appId?: string): void;

Application Mounting

Utility Functions

Navigation bar control, mobile detection, and route alias management utilities.

function setTitle(title: string): void;
function setNavigationBarStyle(option: { backgroundColor: string; frontColor: string }): void;
function setNavigationBarLoading(loading: boolean): void;
function getCurrentPages(): Taro.Page[];

Utility Functions

Core Types

interface SpaRouterConfig extends AppConfig {
  routes: Route[];
  router: Router;
  PullDownRefresh?: any;
}

interface MpaRouterConfig extends AppConfig {
  route: Route;
  pageName: string;
  router: Router;
  PullDownRefresh?: any;
}

interface Route extends PageConfig {
  path?: string;
  load?: () => Promise<any>;
}

interface Router {
  mode: IH5RouterConfig['mode'];
  basename: string;
  customRoutes?: Record<string, string | string[]>;
  pathname: string;
  forcePath?: string;
  enhanceAnimation?: boolean;
}