Mini-app lifecycle

Two levels of lifecycle — the App (the whole mini app) and the Page (one screen). Getting this right is why data loads once, screens stay fresh, and timers don't leak after the user leaves.

Part 1 · App vs Page

A Shoppingate mini app has two levels of lifecycle. The App lifecycle is about the whole mini app: starting, going to the background, coming back, and global errors. The Page lifecycle is about one screen: being opened, shown, hidden and closed, plus what the user does on that screen.

A simple way to think about it: the App is the shop building, and Pages are the rooms inside it. The building opens once in the morning (onLaunch), and it can close and reopen its doors (onHide / onShow). People walk in and out of the rooms all day (Page onLoad, onShow, onHide, onUnload).

Side-by-side comparison

Same name, different meaning: onShow and onHide

Both App and Page have onShow and onHide, and they are easy to mix up.

How they run together

This is the order of calls in common situations:

Notice that App onLaunch and Page onLoad run only once each, while onShow and onHide can run many times.

Part 2 · App lifecycle

The full sweep of an app.js from launch to shutdown, plus the four side-channels for errors, missing pages, uncaught rejections, and theme changes.

Mini App starts
    │
App onLaunch(options)     ← once: app initialized
    │
App onShow(options)       ← app visible (start, or back from background)
    │
Page onLoad → Page onShow → Page onReady   (first page opens)
    │
    │── script or API error         → onError(error)
    │── page does not exist         → onPageNotFound(options)
    │── Promise rejected, no catch  → onUnhandledRejection(res)
    │── system theme changes        → onThemeChange(res)
    │
Page onHide → App onHide()   ← app goes to background
    │
App onShow(options)          ← app comes back to foreground

// app.js
App({
  globalData: { userInfo: null },

  onLaunch(options) {
    console.log('Opened page:', options.path)
    console.log('Query:', options.query)
    console.log('Scene:', options.scene)

    ft.getUserInfo({
      success: (res) => {
        this.globalData.userInfo = res.userInfo
      },
      fail: (err) => {
        console.log('getUserInfo failed:', err)
      }
    })
  }
})

App({
  onShow(options) {
    console.log('App is visible, scene:', options.scene)

    if (options.referrerInfo) {
      console.log('Opened by appId:', options.referrerInfo.appId)
      console.log('Extra data:', options.referrerInfo.extraData)
    }
  }
})

App({
  globalData: { cart: [] },

  onHide() {
    console.log('App moved to background')
    ft.setStorageSync('cart', this.globalData.cart)
  }
})

App({
  onError(error) {
    console.log('App error:', error)

    ft.request({
      url: 'https://api.example.com/log/error',
      method: 'POST',
      data: { message: error },
      success: () => {
        console.log('Error reported')
      },
      fail: (err) => {
        console.log('Request failed:', err)
      }
    })
  }
})

App({
  onPageNotFound(options) {
    console.log('Page not found:', options.path)
    console.log('Is entry page:', options.isEntryPage)

    ft.redirectTo({
      url: '/pages/home/home'
    })
  }
})

App({
  onUnhandledRejection(res) {
    console.log('Unhandled rejection:', res.reason)
  }
})

// Somewhere in a page: this rejection has no .catch(),
// so onUnhandledRejection runs
new Promise((resolve, reject) => {
  reject('Something went wrong')
})

// app.json
{ "darkmode": true }

// app.js
App({
  globalData: { theme: 'light' },

  onThemeChange(res) {
    console.log('New theme:', res.theme)   // 'light' or 'dark'
    this.globalData.theme = res.theme
  }
})

getApp(): using the app from a page

getApp() returns the App instance, so any page can read globalData or call functions defined in App. Do not call it inside App itself — use this there.

// pages/profile/profile.js
Page({
  data: { userInfo: null },

  onLoad() {
    const app = getApp()

    this.setData({
      userInfo: app.globalData.userInfo
    })
  }
})

Putting it all together: one complete app.js

A real app usually uses only some of these. Here is a complete app.js that combines them.

// app.js
App({
  globalData: {
    userInfo: null,
    cart: [],
    theme: 'light'
  },

  onLaunch(options) {
    console.log('App launched, scene:', options.scene)
    this.globalData.cart = ft.getStorageSync('cart') || []

    ft.getUserInfo({
      success: (res) => {
        this.globalData.userInfo = res.userInfo
      },
      fail: (err) => {
        console.log('getUserInfo failed:', err)
      }
    })
  },

  onShow(options) {
    console.log('App shown, path:', options.path)
  },

  onHide() {
    ft.setStorageSync('cart', this.globalData.cart)
  },

  onError(error) {
    ft.request({
      url: 'https://api.example.com/log/error',
      method: 'POST',
      data: { message: error },
      success: () => {
        console.log('Error reported')
      },
      fail: (err) => {
        console.log('Request failed:', err)
      }
    })
  },

  onPageNotFound(options) {
    console.log('Page not found:', options.path)
    ft.redirectTo({ url: '/pages/home/home' })
  },

  onUnhandledRejection(res) {
    console.log('Unhandled rejection:', res.reason)
  },

  onThemeChange(res) {
    this.globalData.theme = res.theme
  }
})

App quick reference

Learn onLaunch, onShow and onHide first. The rest are handlers for errors and special situations.

Part 3 · Page lifecycle

One page's life: created, shown, ready, hidden, destroyed — plus every event hook a page can react to.

Page opens
    │
onLoad(query)  ← once: read URL params, first API request
    │
onShow()       ← every time the page becomes visible
    │
onReady()      ← once: first render finished, UI is usable
    │
    │── user scrolls           → onPageScroll()
    │── user pulls down        → onPullDownRefresh()
    │── user reaches bottom    → onReachBottom()
    │── user shares            → onShareAppMessage()
    │── user favorites         → onAddToFavorites()
    │── user taps a tab        → onTabItemTap()
    │── window size changes    → onResize()
    │
onHide()       ← page hidden (navigateTo, tab switch, app to background)
    │            (can come back → onShow() again)
onUnload()     ← page destroyed (redirectTo, navigateBack)

// Opened with: ft.navigateTo({ url: '/pages/product/product?id=123' })
Page({
  data: { product: null },

  onLoad(query) {
    const id = query.id   // "123" (always a string!)

    ft.request({
      url: 'https://api.example.com/products/' + id,
      success: (res) => {
        this.setData({ product: res.data })
      },
      fail: (err) => {
        console.log('Request failed:', err)
      }
    })
  }
})

Page({
  data: { cartCount: 0 },

  onShow() {
    ft.request({
      url: 'https://api.example.com/cart/count',
      success: (res) => {
        this.setData({ cartCount: res.data.count })
      },
      fail: (err) => {
        console.log('Request failed:', err)
      }
    })
  }
})

Page({
  onReady() {
    ft.setNavigationBarTitle({ title: 'Product Details' })
  }
})

Page({
  onHide() {
    const video = ft.createVideoContext('promo')
    video.pause()
  }
})

Page({
  onLoad() {
    this.timer = setInterval(() => {
      console.log('Running...')
    }, 1000)
  },

  onUnload() {
    clearInterval(this.timer)
  }
})

// product-list.json
{ "enablePullDownRefresh": true }

// product-list.js
Page({
  data: { products: [] },

  onPullDownRefresh() {
    ft.request({
      url: 'https://api.example.com/products',
      success: (res) => {
        this.setData({ products: res.data })
      },
      fail: (err) => {
        console.log('Request failed:', err)
      },
      complete: () => {
        ft.stopPullDownRefresh()   // always stop the animation
      }
    })
  }
})

Page({
  data: { products: [], page: 1 },

  onReachBottom() {
    const nextPage = this.data.page + 1

    ft.request({
      url: 'https://api.example.com/products',
      data: { page: nextPage },
      success: (res) => {
        this.setData({
          products: this.data.products.concat(res.data),
          page: nextPage
        })
      },
      fail: (err) => {
        console.log('Request failed:', err)
      }
    })
  }
})

Page({
  onShareAppMessage(options) {
    console.log('Share from:', options.from)   // 'button' or 'menu'

    return {
      title: 'Check out this product!',
      path: '/pages/product/product?id=123'
    }
  }
})

Page({
  data: { showBackToTop: false },

  onPageScroll(options) {
    const show = options.scrollTop > 300

    if (show !== this.data.showBackToTop) {
      this.setData({ showBackToTop: show })
    }
  }
})

Page({
  onTabItemTap(options) {
    console.log('Tab index:', options.index)
    console.log('Page path:', options.pagePath)
    console.log('Tab text:', options.text)
  }
})

// product-list.json
{ "pageOrientation": "auto" }

// product-list.js
Page({
  data: { layout: 'small' },

  onResize(options) {
    const width = options.size.windowWidth

    this.setData({
      layout: width >= 600 ? 'large' : 'small'
    })
  }
})

Page({
  onAddToFavorites(options) {
    return {
      title: 'My Product',
      query: 'id=123'
    }
  }
})

Putting it all together: one complete page

A real product page usually uses only some of these. Here is a complete page that combines the most common ones.

// pages/product/product.js
Page({
  data: {
    product: null,
    reviews: [],
    page: 1,
    showBackToTop: false
  },

  onLoad(query) {
    this.id = query.id

    ft.request({
      url: 'https://api.example.com/products/' + this.id,
      success: (res) => {
        this.setData({ product: res.data })
      },
      fail: (err) => {
        console.log('Request failed:', err)
      }
    })
  },

  onShow() {
    console.log('Page shown')
  },

  onReady() {
    ft.setNavigationBarTitle({ title: 'Product Details' })
    ft.setNavigationBarColor({
      frontColor: '#ffffff',
      backgroundColor: '#07A35A'
    })

    ft.createSelectorQuery()
      .select('#header')
      .boundingClientRect((rect) => {
        console.log('Header height:', rect.height)
      })
      .exec()
  },

  onHide() {
    console.log('Page hidden')
  },

  onUnload() {
    console.log('Page destroyed')
  },

  onPullDownRefresh() {
    ft.request({
      url: 'https://api.example.com/products/' + this.id,
      success: (res) => {
        this.setData({ product: res.data })
      },
      fail: (err) => {
        console.log('Request failed:', err)
      },
      complete: () => {
        ft.stopPullDownRefresh()
      }
    })
  },

  onReachBottom() {
    const nextPage = this.data.page + 1

    ft.request({
      url: 'https://api.example.com/products/' + this.id + '/reviews',
      data: { page: nextPage },
      success: (res) => {
        this.setData({
          reviews: this.data.reviews.concat(res.data),
          page: nextPage
        })
      },
      fail: (err) => {
        console.log('Request failed:', err)
      }
    })
  },

  onPageScroll(options) {
    const show = options.scrollTop > 300
    if (show !== this.data.showBackToTop) {
      this.setData({ showBackToTop: show })
    }
  },

  onShareAppMessage() {
    return {
      title: 'Check out this product!',
      path: '/pages/product/product?id=' + this.id
    }
  },

  onAddToFavorites() {
    return { title: 'My Product', query: 'id=' + this.id }
  }
})

Page quick reference

Learn onLoad, onShow, onReady, onHide and onUnload first. The rest are event handlers you add when you need a specific feature.