Quick Start

This guide assumes you have completed the prerequisites and installed the BowlerKit CLI.

Create the project

bowler create my-expo-app

cd my-expo-app/mobile-app
cp .env.example .env
pnpm install
pnpm start

Account profile setup

Choose this profile when the app needs sign-in, cloud data, uploads, or server-managed notifications.

1. Configure Laravel

cd my-expo-app/admin-panel
cp .env.example .env
composer install
npm install
php artisan key:generate

Set the PostgreSQL, Redis, mail, Firebase, and RevenueCat values in .env. The default template uses PostgreSQL; SQLite is not the configured default.

2. Migrate and seed local data

php artisan migrate --seed
php artisan serve

The development seeder creates [email protected] / superapp and [email protected] / user. Treat these as local-only credentials and replace or remove them before production.

The Laravel admin panel is available at http://localhost:8000/admin. It also serves the Account profile's public landing page and SEO surface at / plus the built-in theme routes; customize those in admin-panel/resources/js/Pages/Home.tsx and the theme files. Laravel owns authentication, Sanctum token issuance, migrations, uploads, webhooks, and destructive account operations.

3. Start the Go API when needed

cd ../api-backend
cp .env.example .env
# Match the shared PostgreSQL and Redis settings used by Laravel.
go mod download
go run ./cmd/api

The Go service validates Laravel Sanctum tokens and serves the protected mobile resource routes. It shares Laravel's database; it does not issue tokens or run migrations. Start Laravel first, then place the Go service behind the production gateway when you are ready to use it.

Guest profile setup

Guest projects are local-first and do not include admin-panel/ or api-backend/. They include the standalone landing-page/ app for marketing, legal pages, and SEO.

• Account routes and remote API work are runtime-gated.
• Local settings, local notifications, static help/about content, Paywall/RevenueCat, and AdMob remain available.
• Store purchase and restore operations still require internet access.
• Optional dependency and route removal is documented in the generated docs/AI-GUEST-CLEANUP.md.

Verify the app

1. Launch the mobile app.
2. For Account, register or sign in and confirm the profile loads from /api/v1/app/me.
3. For Guest, confirm the app opens without a login or backend connection.
4. If you use the Go service, verify /health and /api/v1/health before routing mobile traffic to it.

What's next?

Troubleshooting

Connection refused

• Android emulator: use http://10.0.2.2:8000 for a Laravel server running on the host.
• iOS simulator: http://127.0.0.1:8000 usually works.
• Physical device: use the host computer's LAN IP and allow the port through the firewall.
• Do not append /api/v1 to EXPO_PUBLIC_API_URL.

Database or cache errors

Check the Laravel .env PostgreSQL and Redis values, then run:

php artisan migrate:fresh --seed

This resets the local database. Never run it against production data.

Metro cache issues

pnpm start -- --clear