lynx-family · jianliang00 · Jun 4, 2025 · May 31, 2025
diff --git a/explorer/.npmrc b/explorer/.npmrc
@@ -0,0 +1,3 @@
+shamefully-hoist=true
+strict-peer-dependencies=false
+auto-install-peers=true
diff --git a/explorer/README.md b/explorer/README.md
@@ -0,0 +1,27 @@
+# Lynx Explorer
+
+The official app for testing and exploring Lynx. It is featured in Lynx Quick Start Guide at <https://lynxjs.org/guide/start/quick-start.html>.
+
+The dir consists of two main parts:
+1. Native mobile applications (Android/iOS) that provide the runtime environment
+2. ReactLynx-based web applications that run inside the native apps
+
+## Building the Native Apps
+
+If you want to build and run the native mobile applications from source, please refer to the platform-specific dirs and guides:
+
+### android/
+Contains the native Android apps that integrated Lynx. See [Android Build Guide](android/README.md) for instructions.
+
+### darwin/
+Contains the native iOS apps that integrated Lynx. See [iOS Build Guide](darwin/ios/README.md) for instructions.
+
+## Developing the Bundled Lynx Projects
+
+If you already have a built Lynx Explorer app (or any other Lynx-integrated environment), you can focus on developing the Lynx screens that run inside it. There are currently two screens: 
+
+### homepage/
+Contains the home screen of Lynx Explorer implemented with ReactLynx. This is the entry point of the application.
+
+### showcase/
+Contains the showcase screen of Lynx Explorer implemented with ReactLynx. This demonstrates various Lynx features and capabilities by integrating the official Lynx examples at <https://github.com/lynx-family/lynx-examples>.
diff --git a/explorer/android/README.md b/explorer/android/README.md
@@ -1,13 +1,13 @@
-# Build Lynx Explorer
+# Building Lynx Explorer for Android
 
-This document will help you build LynxExplorer for Android on MacOS, Linux and Windows.
+This document provides instructions for building the Lynx Explorer Android app from source. If you just want to try out Lynx, you can download the pre-built APK from the releases page instead.
 
-## System requirements
+## System Requirements
 
 - 100GB or more of disk space
 - Git/Python3(>=3.9) installed
 
-## Install dependencies
+## Install Dependencies
 
 The following dependencies are needed:
 
@@ -98,7 +98,7 @@ Add the following statement to your environment configuration file (it may be ~/
     [Environment]::SetEnvironmentVariable('PATH', "$JDK_PATH;$EXISTING_PATH", 'User')
     ```
 
-### Android development environment
+### Android Development Environment
 
 Configuring the Android development environment required by Lynx includes the following step:
 
@@ -122,8 +122,7 @@ If you have NOT installed the Android SDK before, you can set ANDROID_HOME to th
     [Environment]::SetEnvironmentVariable('ANDROID_HOME', $path-to-android-sdk, 'User')
     ```
 
-
-### Python library
+### Python Library
 
 We recommend using pyenv to manage python environment.
 To install pyenv: 
@@ -138,17 +137,17 @@ pyenv install 3.9 # or higher
 pyenv global 3.9 # or higher
 ```
 
-## Get the code
+## Get the Code
 
-### Pull the repository
+### Pull the Repository
 
 Pull the code from the Github repository and specify the path(`src/lynx`) to avoid contaminating the directory when installing dependencies.
 
 ```
 git clone https://github.com/lynx-family/lynx.git src/lynx
 ```
 
-### Get the dependent files
+### Get the Dependent Files
 
 After getting the project repository, execute the following commands in the root directory of the project to get the project dependent files.
 
@@ -168,41 +167,41 @@ After getting the project repository, execute the following commands in the root
     tools\hab.ps1 sync .
     ```
 
-### Install the Android components
+### Install the Android Components
 
 Execute the following commands, which will install the Android components required by Lynx, including the Android SDK/NDK. During the execution process, your authorization might be required.
 
 ```
 python3 tools/android_tools/prepare_android_build.py
 ```
 
-## Compile and run
+## Build and Run
 
 You can compile LynxExplorer through the command line terminal or Android Studio. The following two methods are introduced respectively.
 
-### Method 1: Compile and run using Android Studio
+### Method 1: Build and Run using Android Studio
 
-#### Open the project
+#### Open the Project
 
-1.Use Android Studio to open the `/explorer/android` directory of the project.
+1. Use Android Studio to open the `/explorer/android` directory of the project.
 
-2.Make sure that the JDK used by your Android Studio points to the JDK 11 installed in the above steps: 
+2. Make sure that the JDK used by your Android Studio points to the JDK 11 installed in the above steps: 
 
-1. Open Settings > Build,Execution,Deployment > Build Tools > Gradle, modify the Default Gradle JDK.
-2. Fill in the path of your JAVA_HOME. If you follow the JDK configuration steps above, it is likely to be
-    - `/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home` on MacOS.
-    - `/usr/lib/jvm/java-11-openjdk-amd64` on Linux.
-    - `C:\Program Files\ojdkbuild\java-11-openjdk-11.0.15-1` on Windows.
+    1. Open Settings > Build,Execution,Deployment > Build Tools > Gradle, modify the Default Gradle JDK.
+    2. Fill in the path of your JAVA_HOME. If you follow the JDK configuration steps above, it is likely to be
+        - `/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home` on MacOS.
+        - `/usr/lib/jvm/java-11-openjdk-amd64` on Linux.
+        - `C:\Program Files\ojdkbuild\java-11-openjdk-11.0.15-1` on Windows.
 
-3.Trigger Gradle sync.
+3. Trigger Gradle sync.
 
-#### Compile and run
+#### Build and Run
 
 Select the `LynxExplorer` module and click the `Run` button to experience LynxExplorer on your device.
 
-### Method 2: Compile and run using the command line
+### Method 2: Build and Run using the Command Line
 
-#### Compile
+#### Build
 
 Enter the `explorer/android` directory from the project root directory and execute the following command.
 
@@ -217,9 +216,9 @@ This command will generate LynxExplorer-noasan-debug.apk in the `lynx_explorer/b
 
 You can install the above .apk file on your device using the adb command.
 
-````
+```
 adb install lynx_explorer/build/outputs/apk/noasan/debug/LynxExplorer-noasan-debug.apk
-````
+```
 
 If the adb command is not found, you can add the path to the adb command in the environment configuration file(~/.zshrc or ~/.bash_profile or ~/.bashrc):
 

diff --git a/explorer/darwin/ios/README.md b/explorer/darwin/ios/README.md
@@ -1,13 +1,13 @@
-# Build Lynx Explorer for iOS
+# Building Lynx Explorer for iOS
 
-This document will help you build LynxExplorer for iOS on macOS.
+This document provides instructions for building the Lynx Explorer iOS app from source. If you just want to try out Lynx, you can download the pre-built app from the releases page instead.
 
-## System requirements
+## System Requirements
 
 - 100GB or more of disk space
 - Git/Python3(>=3.9)/Ruby(>=2.7, <3.4) installed
 
-## Install dependencies
+## Install Dependencies
 
 The following dependencies are needed:
 
@@ -23,7 +23,7 @@ Lynx requires Xcode 15.0 or later. It is recommended to keep Xcode up to date. Y
 - Open Xcode->Settings->Locations, to make sure the `Command Line Tools` are configured
 - You can run `xcode-select -p` in the terminal, and if it prints a correct path, it's configure successfully.
 
-### Python library
+### Python Library
 
 The yaml dependency needs to be installed to execute some auto-generation logic.
 
@@ -35,17 +35,17 @@ source venv/bin/activate
 pip3 install pyyaml
 ```
 
-## Get the source code
+## Get the Source Code
 
-### Pull the repository
+### Pull the Repository
 
 Pull the code from the Github repository and specify the path(`src/lynx`) to avoid contaminating the directory when installing dependencies.
 
 ```
 git clone https://github.com/lynx-family/lynx.git src/lynx
 ```
 
-### Install third-party library
+### Install Third-party Library
 
 Run the following commands from the root of the repository to install the dependencies.
 
@@ -67,7 +67,7 @@ cd explorer/darwin/ios/lynx_explorer
 
 ## Troubleshooting
 
-### Using a Personal Team to run on device
+### Using a Personal Team to Run on Device
 
 By default, the project doesn't configure the "Team" for signing. If you want to change it to your Personal Team (associated with your Apple ID), follow these steps:
 
@@ -76,11 +76,10 @@ By default, the project doesn't configure the "Team" for signing. If you want to
 3. Update the "Bundle Identifier" from `com.lynx.LynxExplorer` to a unique identifier like `com.<your-name>.LynxExplorer`. This step ensures the identifier is unique and available for your use.
 4. Enable the "Automatically manage signing" option to allow Xcode to handle the app signing process automatically.
 
-### Handle error when installing ruby gems
+### Handle Error when Installing Ruby Gems
 
 When running `./bundle_install.sh` command, if you encounter the following problems: *Bundler::GemNotFound: Your bundle is lock to xxx, but that version could not be found in any of the sources listed in Gemfile...* You can try running the following commands to fix the problem:
 ```
 SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk bundle install
 ./bundle_install.sh
 ```
-
diff --git a/explorer/darwin/ios/lynx_explorer/bundle_install.sh b/explorer/darwin/ios/lynx_explorer/bundle_install.sh
@@ -20,7 +20,7 @@ usage() {
 build_card_resources() {
     # build home page card
     pushd $root_dir/explorer/homepage
-    pnpm install
+    pnpm install --no-frozen-lockfile
     pnpm run build
     cp $root_dir/explorer/homepage/dist/main.lynx.bundle $root_dir/explorer/darwin/ios/lynx_explorer/LynxExplorer/Resource/homepage.lynx.bundle
     popd

diff --git a/explorer/homepage/build.py b/explorer/homepage/build.py
@@ -12,5 +12,5 @@
 from tools.js_tools.pnpm_helper import run_pnpm_command
 
 # Install dependencies and build
-run_pnpm_command(['pnpm', 'install'], os.getcwd())
+run_pnpm_command(['pnpm', 'install', '--frozen-lockfile'], os.getcwd())
 run_pnpm_command(['pnpm', 'build'], os.getcwd())