#Memory Cache Lifecycle Description

To facilitate clearer understanding of the changes in a Mini Program's state when entering and resuming memory cache, new memory cache-related lifecycle events have been added to the Mini Program's App object to distinguish different stages and handle different logic.

#New Lifecycle Events

#Compatibility Notes

To ensure that existing mini-programs are not affected, the original App.onShow and App.onHide lifecycle methods will still be triggered normally.

In scenarios involving memory caching, the triggering order of lifecycle events is as follows:

#Entering Memory Cache

1. Trigger App.onPause

2. Trigger App.onHide

#Resuming from Memory Cache

1. Trigger App.onResume

2. Trigger App.onShow

export default class App extends React.Component {
  // did mount is triggered during onLaunch
  componentDidMount() {
    console.log('App launch');
  }
  onPause() {
    console.log('Entered memory cache state');
  }
  onResume() {
    console.log('Resumed from memory cache state')
  }
  render() {
    return this.props.children;
  }
}

For functional components of App, lifecycle events can be listened to using the useAppEvent hook

• ray version requires >= 1.7.39

import { useAppEvent } from '@ray-js/ray';

export default function App(props) {
  useAppEvent('onPause', () => {
    console.log('Entered in-memory cache state');
  });
  useAppEvent('onResume', () => {
    console.log('Resumed from in-memory cache state')
  });
  return props.children;
}

#1. Mini Program Lifecycle

A mini program goes through several states from launch to termination, and its behavior varies across these states.

#1.1 Launch

From the user's perspective, a mini program can start in two ways:

• Cold Start:
  When the mini program is opened for the first time, or after it has been completely destroyed, it needs to reload all resources — this is called a cold start.

• Warm Start:
  When the user reopens a mini program that was previously opened but not destroyed, it simply resumes from the background — this is called a warm start.

In lifecycle terminology, “launch” usually refers to a cold start, while warm start means “switching from background to foreground.”

#1.2 Foreground and Background

When the mini program is running and visible to the user, it is in the foreground state.
When the user leaves the mini program, it does not immediately shut down but instead enters the background state, where it may continue running briefly with limited API access.

Common ways to enter the background:

• Tapping the top-right capsule button to exit
• Swiping right from the left edge on iOS
• Pressing the Back key on Android
• Putting the app into background via Home or gestures
• Locking the screen while the mini program is active

When the user reopens the app and returns to the mini program, it re-enters the foreground state.

#1.3 Termination

A mini program will be completely terminated when it remains unused for a long time or system resources are low.
Once terminated, reopening it will trigger a cold start.

Common termination scenarios:

• The mini program has been in the background for over 10 minutes
• More than three mini programs are in the background — the earliest one will be destroyed

#2. Page Behavior on Cold Start

When a mini program starts cold, the initial page depends on how it’s launched:

• Scenario A: If no path is provided in the launch parameters, the container will open the default entryPagePath.
• Scenario B: If a path is provided, the mini program will open that specific page directly.

#3. Page Behavior on Warm Start

When warm-starting, the opened page depends on configuration:

• By default, the mini program opens the same first page as during cold start.
• If cachePageStack: true is configured, the previous browsing state (page stack) will be restored.

Configuration location: global.config.ts

#4. Manual Destruction

If you want the mini program to always start fresh (cold start every time), you can explicitly disable caching:

Configuration location: global.config.ts

#5. Scenarios Without Memory Caching

In certain cases, the mini program will be closed directly without being stored in memory.
This means that when reopened, it will reload completely instead of restoring from memory.

The following conditions trigger non-caching closure:

• Non-production builds:
  Development or experience versions do not use memory caching.

• White screen on exit:
  If the mini program UI is blank (white screen) when closing, it will be destroyed to avoid restoring an abnormal state.

• Incomplete process during exit:
  If the app is still performing startup tasks or network requests, caching will be skipped.

• Explicitly disabled cache:
  If disableCache: true is set in global.config.ts, the mini program will always be destroyed on exit.

• Experience rating enabled:
  If user experience rating is active, caching is disabled for consistency.

• Running inside a native tab bar:
  Mini programs running within native tab environments do not support memory caching.

#6. Additional Notes

• The mini program only enters memory cache mode if all caching conditions are met.
• Cached mini programs resume faster when reopened, restoring the previous user state.
• If caching is disabled or skipped, the next launch will always be a cold start.

#7. Frequently Asked Questions (FAQ)

#Q1: Why does my mini program reopen on the same page after I press the Android Back button?

That happens because the mini program was cached in memory when you exited.
Reopening it restores the previous state instead of reloading from scratch.

How to fix this:

In your global configuration file global.config.ts, set:

disableCache: true

#Q2: I want to retain the last page I was working on in a mini program so I can use it again the next time I open it. How do I configure this?

Just make sure:

• disableCache: true is not set
• No direct closing is triggered (see Section 5 above)

By default, the mini program automatically enters memory caching mode, and the last page will be restored the next time it is opened.

#Q3: In what situations will the mini program not be cached?

• The mini program is in the development/experience version
• A white screen appears when closing
• Background tasks are not completed when launching
• The experience rating feature is enabled
• In the Native Tab bar
• It shows that disableCache: true is configured.