Skip to main content

Getting Started with 54VIE Super App

This guide will help you install and run 54VIE Super App on your local machine.

Requirements​

Before starting, make sure you have installed:

  • Node.js >= 22 (Download)
  • pnpm - Package manager (Install)
  • Xcode 15+ (for iOS development)
  • Android Studio (for Android development)
  • JDK 17+

Verify Installation​

node -v    # v22.x.x
pnpm -v    # 10.x.x

Installation​

1. Clone repository​

git clone https://github.com/54vie/super-app.git
cd super-app

2. Install dependencies​

pnpm install

3. Install iOS pods​

cd app-host/ios && pod install && cd ../..
# or
pnpm pods

Running the Application​

Run Dev Server​

# Run host app dev server
pnpm host

# Or run everything (host + mini-apps)
pnpm start:all

Run on iOS​

pnpm host:ios

Run on Android​

pnpm host:android

Project Structure​

54vie-super-app/
├── app-host/              # Host application
│   ├── src/
│   │   ├── App.tsx
│   │   ├── auth/          # Authentication module
│   │   ├── navigation/    # Navigation setup
│   │   ├── screens/       # Main screens
│   │   ├── providers/     # Context providers
│   │   └── services/      # Services (MiniProgramRegistry)
│   ├── ios/               # iOS native code
│   └── android/           # Android native code
│
├── mini-programs/         # Mini-apps
│   └── dashboard/         # Dashboard mini-app
│
├── miniapp-sdk/           # SDK for mini-apps
├── miniapp-runtime/       # Mini-app runtime
│
├── core/                  # Shared dependencies
├── kit/                   # UI components
├── api/                   # API client
├── analytics/             # Analytics
├── storage/               # Storage
├── device/                # Device utilities
├── location/              # Location services
├── media/                 # Media handling
└── push-notification/     # Push notifications

Main Scripts​

ScriptDescription
pnpm installInstall all dependencies
pnpm hostRun host app dev server
pnpm host:iosRun on iOS simulator
pnpm host:androidRun on Android emulator
pnpm miniRun dashboard mini-app
pnpm start:allRun all dev servers
pnpm typecheckRun TypeScript check
pnpm lintRun ESLint

Development Environment​

  • ESLint
  • Prettier
  • TypeScript and JavaScript Language Features
  • React Native Tools
  • GitLens

Environment Variables​

Create a .env file in app-host/:

# API
API_BASE_URL=https://api.54vie.vn/v1
CDN_URL=https://cdn.54vie.vn

# SSO
GOOGLE_WEB_CLIENT_ID=your-google-client-id
APPLE_CLIENT_ID=your-apple-client-id
FACEBOOK_APP_ID=your-facebook-app-id

# Analytics
ANALYTICS_API_KEY=your-analytics-key

Troubleshooting​

iOS: Pod install fails​

cd app-host/ios
pod deintegrate
pod cache clean --all
pod install

Android: Build fails​

cd app-host/android
./gradlew clean
cd ..
pnpm host:android

Metro bundler issues​

# Clear Metro cache
pnpm host --reset-cache

# Or
rm -rf node_modules/.cache

Module not found​

# Rebuild all packages
pnpm clean
pnpm install

Next Steps​