TWA Setup

Configure your TWA project using the interactive setup script.

Prerequisites

• Node.js 20+
• Java JDK 17+ (for keytool and gradle)
• Your PWA deployed with HTTPS

Quick Setup

The template includes an interactive setup script that handles everything:

cd twa
./scripts/init-twa.sh

This script will:

1. Prompt for your app configuration
2. Generate a signing keystore
3. Extract SHA256 fingerprint
4. Create twa-manifest.json from your input
5. Update assetlinks.json automatically
6. Build the signed APK

Interactive Prompts

The script will ask for:

Prompt	Description	Example
App Name	Full application name	My Solana App
Package ID	Unique Android identifier	com.mycompany.myapp
Host URL	Your deployed PWA domain	myapp.vercel.app
Keystore Password	Password for signing key	(secure password)

Example Session

=== Solana Mobile TWA Setup ===

Enter your app name: My Solana App
Enter your package ID (e.g., com.company.app): com.mycompany.myapp
Enter your host URL (without https://): myapp.vercel.app
Enter keystore password: ********

Creating keystore...
Extracting SHA256 fingerprint...
Generating twa-manifest.json...
Updating assetlinks.json...
Building APK...

✓ Setup complete!
  APK: app-release-signed.apk
  Fingerprint: AA:BB:CC:DD:...

Configuration Files

twa-manifest.json

Generated by the init script with your configuration:

{
  "packageId": "com.mycompany.myapp",
  "host": "myapp.vercel.app",
  "name": "My Solana App",
  "launcherName": "My Solana App",
  "display": "standalone",
  "themeColor": "#9945FF",
  "navigationColor": "#000000",
  "backgroundColor": "#0a0a0a",
  "startUrl": "/",
  "iconUrl": "/icons/icon-512x512.png",
  "splashScreenFadeOutDuration": 300,
  "enableNotifications": true,
  "fallbackType": "customtabs",
  "orientation": "portrait",
  "signing": {
    "keystore": "./android.keystore",
    "alias": "android"
  },
  "appVersionCode": 1,
  "appVersionName": "1.0.0",
  "minSdkVersion": 24,
  "targetSdkVersion": 34
}

Key Fields

Field	Description
packageId	Unique Android app identifier
host	Your deployed domain (no https://)
themeColor	Status bar color
navigationColor	Navigation bar color
backgroundColor	Splash screen background
fallbackType	customtabs shows URL bar if verification fails
minSdkVersion	Minimum Android version (24 = Android 7.0)

twa-manifest.template.json

The template file with placeholder values. The init script uses this as a base.

Manual Configuration

If you prefer manual setup:

1. Install Bubblewrap

npm install -g @bubblewrap/cli

2. Create Keystore

keytool -genkeypair \
  -alias android \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000 \
  -keystore android.keystore

3. Get SHA256 Fingerprint

keytool -list -v -keystore android.keystore | grep SHA256

4. Create twa-manifest.json

Copy twa-manifest.template.json to twa-manifest.json and update:

• packageId - Your unique package ID
• host - Your deployed domain
• name and launcherName - Your app name

5. Update assetlinks.json

Edit public/.well-known/assetlinks.json:

• Replace YOUR_PACKAGE_ID_HERE with your package ID
• Replace YOUR_SHA256_FINGERPRINT_HERE with your fingerprint

6. Build

./scripts/build-twa.sh

Keystore Security

Important

Your android.keystore file is critical:

• Never commit to git (it's in .gitignore)
• Back it up securely - You need it for all future updates
• Remember your password - Cannot be recovered if lost

Lost keystore = new app listing on dApp Store.

Directory Structure

After setup:

twa/
├── twa-manifest.json          # Your configuration (gitignored)
├── twa-manifest.template.json # Template with placeholders
├── android.keystore           # Signing key (gitignored)
├── CustomLauncherActivity.java
├── scripts/
│   ├── init-twa.sh           # Interactive setup
│   ├── build-twa.sh          # Rebuild script
│   └── update-assetlinks.sh  # Update fingerprint
└── (generated after build)
    ├── app/                   # Android project
    └── app-release-signed.apk

Deploy Your PWA

After running init, deploy your PWA with the updated assetlinks.json:

# From project root
npm run build
# Deploy to Vercel/your hosting

Verify it's accessible:

curl https://your-domain.com/.well-known/assetlinks.json

Next Steps

1. Test your APK
2. Verify frameless mode
3. Publish to dApp Store