create-porto-web-app

Scaffold the Porto Web App - A complete Vite + React + TypeScript + Porto + wagmi template with mobile & web support

🚀 Quick Start

# ✅ CORRECT - Use npx to create your app
npx create-porto-web-app@latest my-app
cd my-app
npm install
npm run dev

⚠️ Important: Always use npx create-porto-web-app (not npm install create-porto-web-app). This is a scaffolder tool, not a regular package.

✨ What You Get

• ⚡ Vite + React + TypeScript - Lightning fast development
• 🔐 Porto Integration - Next-gen account stack with passkeys
• 📱 Mobile & Web Support - Responsive design with WebAuthn
• 🌐 RISE Testnet Ready - Pre-configured for gasless transactions
• 🎨 Modern UI - Glassmorphism design with neumorphic elements
• 🔧 HTTPS Development - mkcert integration for local HTTPS

🔑 How Porto Works

Porto is a next-generation account stack for Ethereum that replaces traditional seed phrases with passkeys (WebAuthn). Here's how it works:

Traditional Wallets vs Porto

• Traditional: Seed phrase → Private key → Address
• Porto: Passkey → WebAuthn → Account abstraction → Gasless transactions

Key Benefits

• 🔐 No Seed Phrases - Use your device's biometrics (fingerprint, face ID)
• ⛽ Gasless Transactions - Built-in account abstraction
• 📱 Cross-Platform - Works on mobile and desktop
• 🛡️ Enhanced Security - Hardware-backed authentication
• 🌐 Web Standards - Built on WebAuthn and FIDO2

How Passkeys Work

1. Registration: User creates a passkey using device biometrics
2. Authentication: WebAuthn verifies identity without exposing private keys
3. Transaction: Porto handles account abstraction for gasless execution
4. Signing: Passkey signs the transaction securely

📱 Mobile & Web Support

This template includes:

• Responsive Design - Adapts to mobile and desktop screens
• WebAuthn Polyfills - Ensures compatibility across browsers
• HTTPS Requirements - WebAuthn requires secure contexts
• Touch-Friendly UI - Optimized for mobile interactions

🛠️ Development

Prerequisites

• Node.js 16+
• Modern browser with WebAuthn support
• HTTPS for mobile testing (included with mkcert)

Available Scripts

npm run dev      # Start development server (HTTPS)
npm run build    # Build for production
npm run preview  # Preview production build
npm run lint     # Run ESLint

Mobile Testing

For mobile testing, the dev server runs on HTTPS with mkcert:

• Desktop: https://localhost:5173
• Mobile: https://[your-ip]:5173 (ensure HTTPS)

🌐 RISE Testnet

The app is pre-configured for RISE testnet:

• Chain ID: 11155931
• RPC: https://testnet.riselabs.xyz
• Explorer: https://testnet.riselabs.xyz
• Features: Gasless transactions, account abstraction

📦 What's Included

my-app/
├── src/
│   ├── components/
│   │   ├── WalletConnect.tsx    # Porto wallet connection
│   │   └── SimpleDApp.tsx       # Demo dApp with transactions
│   ├── config.ts                # wagmi + Porto configuration
│   └── ...
├── public/
├── vite.config.ts               # HTTPS + mkcert setup
├── tsconfig.json               # TypeScript configuration
└── package.json                # Dependencies & scripts

🔧 Configuration

The template includes:

• wagmi - React hooks for Ethereum
• viem - TypeScript interface for Ethereum
• Porto - Passkey-based wallet integration
• @tanstack/react-query - Data fetching and caching
• vite-plugin-mkcert - Local HTTPS certificates

📚 Learn More

• Porto Documentation
• WebAuthn Guide
• wagmi Documentation
• RISE Testnet

❓ Troubleshooting

Common Issues

❌ Error: EPERM: operation not permitted

# This happens when you try to install instead of using npx
npm i create-porto-web-app  # ❌ WRONG

# Use npx instead
npx create-porto-web-app my-app  # ✅ CORRECT

❌ Error: Cannot find path 'test-local'

# Make sure you're in the right directory
cd my-app  # Navigate to your created app
npm run dev

❌ Mobile WebAuthn not working

• Ensure you're using HTTPS (included with mkcert)
• Try https://localhost:5173 on desktop first
• For mobile: https://[your-ip]:5173

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

📄 License

MIT © Chris Wilder

Built with ❤️ by Chris Wilder - Making Web3 accessible with passkeys