or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bom.mddom.mdframework-integration.mdindex.mdtypes.mdutilities.md
tile.json

tessl/npm-tarojs--runtime

Cross-platform runtime for Taro framework providing DOM/BOM polyfills and mini-program bridge functionality

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

To install, run

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

index.mddocs/

@tarojs/runtime

A comprehensive TypeScript runtime library for the Taro cross-platform framework providing DOM/BOM polyfills, event handling, lifecycle management, and bridge functionality for mini-programs.

Package Information

import { 
  // BOM APIs
  document, window, history, location, navigator, 
  URL, URLSearchParams, requestAnimationFrame, cancelAnimationFrame,
  // DOM APIs  
  TaroElement, TaroNode, TaroText, TaroEvent, createEvent,
  // Framework Integration
  createPageConfig, createComponentConfig, getCurrentInstance,
  // Utilities
  hydrate, nextTick, eventCenter, throttle, debounce,
  // Environment & Runtime
  env, parseUrl, hooks
} from '@tarojs/runtime'

Package: @tarojs/runtime@4.1.6
Repository: tarojs/taro

Overview

The @tarojs/runtime package enables React-like development for multiple platforms including WeChat Mini Programs, Alipay Mini Programs, and web browsers. It bridges the gap between web APIs and mini-program platforms by providing:

  • Complete DOM/BOM polyfills for non-web environments
  • Virtual DOM implementation with optimized mini-program rendering
  • Cross-platform event system with bubbling and delegation
  • Lifecycle management for pages and components
  • Performance monitoring and optimization tools
  • Context switching for multi-page applications

Architecture

The runtime creates a unified development environment by:

  1. Polyfilling Web APIs: Provides document, window, history, location and other browser objects
  2. Virtual DOM: Implements DOM nodes (TaroElement, TaroNode, TaroText) that compile to mini-program data structures
  3. Event Bridge: Translates between web events and mini-program events with proper bubbling
  4. Update Batching: Optimizes rendering with efficient setData calls and path-based updates
  5. Component Aliasing: Maps generic components to platform-specific implementations

Basic Usage

Setting Up a Page

import { createPageConfig, TaroElement } from '@tarojs/runtime'

// Create a page configuration
const pageConfig = createPageConfig(
  ComponentClass,     // React component class
  'index',           // Page name  
  { title: 'Home' }, // Initial data
  { navigationBarTitleText: 'Home Page' } // Page config
)

// The runtime handles lifecycle automatically:
// onLoad, onShow, onHide, onReady, onUnload

DOM Manipulation

import { document, TaroElement } from '@tarojs/runtime'

// Create elements
const element: TaroElement = document.createElement('view')
element.className = 'container'
element.setAttribute('data-test', 'value')

// Modify content  
element.textContent = 'Hello World'
element.style.setProperty('color', 'red')

// DOM tree operations
document.body.appendChild(element)

Event Handling

import { TaroEvent, eventHandler } from '@tarojs/runtime'

// Event listener
element.addEventListener('tap', (event: TaroEvent) => {
  console.log('Tapped:', event.target)
  event.stopPropagation()
})

// Event handler for mini-programs
const handler = eventHandler((event) => {
  // Automatically converts mini-program event to TaroEvent
})

Core Type Definitions

import { AppInstance, Router, PageInstance, PageLifeCycle } from '@tarojs/runtime'

// Main runtime instance
interface Current {
  app: AppInstance | null
  router: Router | null  
  page: PageInstance | null
  preloadData?: any
}

// Page instance with lifecycle
interface PageInstance extends PageLifeCycle {
  onLoad?(options: Record<string, unknown>): void
  onReady?(): void
  onShow?(): void  
  onHide?(): void
  onUnload?(): void
}

// DOM node types
interface TaroNode extends TaroEventTarget {
  nodeType: number
  nodeName: string
  parentNode: TaroNode | null
  childNodes: TaroNode[]
}

// Event system
interface TaroEvent extends Event {
  mpEvent?: any // Original mini-program event
  type: string
  target: TaroElement
  currentTarget: TaroElement
}

Capabilities

Browser Object Model (BOM)

Complete browser API polyfills including document, window, history, location, and navigation.

import { window, document, history, location } from '@tarojs/runtime'

// Window operations
window.addEventListener('resize', handler)
window.requestAnimationFrame(callback)

// Document manipulation
const element = document.createElement('view')
document.getElementById('app')

// Navigation
history.pushState({}, 'New Page', '/new-page')
location.href = '/redirect'

→ Full BOM Documentation

Document Object Model (DOM)

Virtual DOM implementation with nodes, elements, events, and style management optimized for mini-programs.

import { TaroElement, TaroText, Style } from '@tarojs/runtime'

// Create and modify elements
const view = new TaroElement()
view.tagName = 'view'
view.className = 'container'

// Text nodes
const text = new TaroText('Hello World')
view.appendChild(text)

// Style management
view.style.setProperty('background-color', '#fff')
view.classList.add('active')

→ Full DOM Documentation

Framework Integration

DSL functions for page/component configuration, lifecycle management, and instance handling.

import { 
  createPageConfig, 
  createComponentConfig, 
  getCurrentInstance,
  getPageInstance
} from '@tarojs/runtime'

// Page configuration
const config = createPageConfig(MyComponent, 'home', { count: 0 })

// Get current runtime instance  
const current = getCurrentInstance()
console.log(current.page, current.router)

// Component lifecycle
const componentConfig = createComponentConfig({
  attached() { /* component ready */ },
  detached() { /* component cleanup */ }
})

→ Full Framework Integration Documentation

Utilities & Performance

Utility functions, performance monitoring, event emitters, and optimization tools.

import { 
  throttle, 
  debounce, 
  nextTick, 
  hydrate, 
  eventCenter,
  perf 
} from '@tarojs/runtime'

// Performance utilities
const throttledFn = throttle(expensiveFunction, 250)
const debouncedFn = debounce(updateFunction, 500)

// Async operations
nextTick(() => {
  // Execute after next DOM update
})

// Performance monitoring
perf.start('render')
// ... rendering work
perf.stop('render')

→ Full Utilities Documentation

Type Definitions

Core interfaces, type definitions, and contracts for the runtime system.

// Instance types
interface Instance<T = Record<string, any>> extends Component<T>, PageInstance
interface ReactPageInstance<T = PageProps> extends Component<T>, PageInstance

// Event types
interface MpEvent { /* mini-program event */ }
interface EventOptions { /* event construction options */ }

// Update types  
interface UpdatePayload { /* DOM update payload */ }
interface MiniData { /* mini-program data structure */ }

→ Full Types Documentation

Environment Support

  • Mini Programs: WeChat, Alipay, ByteDance, Baidu, QQ
  • Web Browsers: Chrome, Firefox, Safari, Edge
  • Mobile Apps: React Native (via Taro)
  • Desktop Apps: Electron (via Taro)

Performance Features

  • Update Batching: Efficient DOM updates with setData optimization
  • Path-based Updates: Incremental changes using dot-notation paths
  • Component Aliasing: Platform-specific component mapping
  • Event Delegation: Optimized event handling with ancestor checking
  • Context Switching: Automatic state management for multi-page apps
  • Mutation Observation: Change tracking with lifecycle integration

The runtime enables unified cross-platform development while maintaining optimal performance on each target platform.