Ramses MiniApp DevTools

The Ramses MiniApp DevTools is a development environment designed to simplify the development process of MiniApps for the Ramses SuperApp ecosystem. It provides a local HTTP server for serving MiniApp files, watches for changes in the project directory, and injects WebSocket functionality for live-reloading. The dev tools also include utilities for navigating and initializing screens within the MiniApp.

Features

• Serve MiniApp files with live-reload functionality.
• Inject WebSocket support for live-reloading of the app when files change.
• Provide a QR code to access the app on mobile devices.
• Watch for file changes and notify connected clients to reload.
• Navigate between screens using local JSON files.

Installation

1. Ensure you have Node.js installed (version 14+ recommended).

2. Install the DevTools package globally using npm:

   npm install -g @ramses-superapp/ramses-mini-app-dev-tools

3. After installation, you can run the development environment with:

   run-dev-env

Usage

Running the DevTools

1. Open your terminal.

2. Navigate to your MiniApp project directory.

3. Run the following command:

   run-dev-env

The server will start, and you will see a QR code generated in the terminal. Scan the QR code with your mobile device to access the MiniApp.

Project Structure

The project follows this structure:

/
├── index.js # Main entry point for the DevTools server
├── getIPv4Address.js # Fetches the active wireless IPv4 address
├── Utils.js # Utility functions for screen navigation and app initialization
├── package.json # Metadata and dependencies for the DevTools package

File Breakdown

index.js

• Purpose: The main entry point for the DevTools server.
• Functionality:
  • Starts an Express HTTP server to serve the MiniApp files.
  • Injects WebSocket functionality into HTML files for live-reloading.
  • Generates a QR code for mobile access.
  • Watches for file changes in the current directory and notifies connected WebSocket clients to reload.

getIPv4Address.js

• Purpose: Retrieves the active wireless IPv4 address of the machine.
• Functionality:
  • Scans the network interfaces and identifies the active wireless adapter.
  • Returns the IPv4 address of the wireless adapter for use in the WebSocket URL and server URL.

Utils.js

• Purpose: Provides utility functions for navigating between screens and initializing the MiniApp.
• Key Functions:
  • navigateTo(screen_path): Fetches a local JSON file and sends its contents as a message to the React Native WebView.
  • initApp(first_screen): Initializes the app by navigating to the first screen when the page is loaded.

package.json

• Purpose: Contains the metadata and configuration for the DevTools package.
• Key Properties:
  • main: Entry point (index.js).
  • bin: Command to run the development environment (run-dev-env).
  • dependencies: Lists required dependencies like express, chokidar, qrcode-terminal, and ws.

Example Workflow

1. Run the development environment by executing:

   run-dev-env

2. The server starts, and the terminal displays the following:

   Server running at: http://<IPv4-Address>:9923

   A QR code is generated for mobile access. Scan the QR code to access the app on your device.

3. If you modify any file within the project directory, the connected WebSocket clients (e.g., mobile devices) will automatically reload.

Troubleshooting

• Permission denied error: Ensure you have the necessary write permissions for the target directory. You can try running the command with sudo if required.

  sudo run-dev-env

• IPv4 address not found: Ensure your machine has an active wireless network connection. The default fallback address is 127.0.0.1.

• Port conflicts: The server uses port 9923 and the WebSocket server uses port 9924. Ensure these ports are available on your system.

Future Enhancements

• Support for customizing WebSocket behavior.
• Add support for multiple MiniApp projects simultaneously.
• Improve error handling for file system operations.