home / skills / shipshitdev / library / expo-architect

expo-architect skill

This skill scaffolds a production-ready Expo React Native app with complete navigation, auth optional, and immediate bun start.

npx playbooks add skill shipshitdev/library --skill expo-architect

Review the files below or copy the command above to add this skill to your agents.

Files (4)

SKILL.md

3.0 KB

---
name: expo-architect
description: Scaffold a production-ready Expo React Native app with working screens, navigation, and optional Clerk auth. Generates complete mobile app structure that runs immediately with `bun start`.
version: 1.0.0
tags:
  - expo
  - react-native
  - mobile
  - scaffold
  - clerk
---

# Expo Architect

Create **production-ready** Expo React Native apps with:

- **Framework:** Expo SDK 54 + React Native 0.83 + TypeScript
- **Navigation:** Expo Router (file-based routing)
- **Auth:** Clerk authentication (optional)
- **UI:** NativeWind (Tailwind for RN) or StyleSheet
- **Quality:** Biome linting + TypeScript strict mode
- **Package Manager:** bun

## What Makes This Different

Generates **working mobile apps**, not empty scaffolds:

- Complete navigation structure with working screens
- Optional Clerk authentication flow
- Real UI components with proper styling
- API client integration ready
- Runs immediately with `bun start`

## Workflow Summary

1. **PRD Brief Intake** - Extract app type, screens, features, auth needs
2. **Auth Setup** (if requested) - Clerk provider, sign-in/sign-up screens
3. **Screen Generation** - Tab or stack-based navigation
4. **Component Generation** - UI components, entity components, layouts
5. **Quality Setup** - Biome, TypeScript strict, path aliases
6. **Verification** - Run quality gate, report results

## Usage

```bash
# Create app with PRD-style prompt
python3 ~/.claude/skills/expo-architect/scripts/init-expo.py \
  --root ~/www/myapp \
  --name "My App" \
  --brief "A fitness tracker where users can log workouts"

# With specific options
python3 ~/.claude/skills/expo-architect/scripts/init-expo.py \
  --root ~/www/myapp \
  --name "My App" \
  --tabs "Home,Workouts,Profile" \
  --auth
```

## Generated Structure

```
myapp/
├── app/
│   ├── _layout.tsx          # Root layout
│   ├── (tabs)/              # Tab navigator
│   │   ├── _layout.tsx
│   │   ├── index.tsx
│   │   └── ...
│   └── (auth)/              # Auth screens (if enabled)
├── components/
│   ├── ui/                  # Base UI components
│   ├── [entity]/            # Feature components
│   └── layout/              # Layout components
├── lib/
│   ├── api.ts               # API client
│   └── auth.ts              # Auth utilities
├── providers/               # Context providers
├── types/                   # TypeScript types
├── app.json                 # Expo config
├── package.json
├── tsconfig.json
└── biome.json
```

## Development Commands

```bash
bun start          # Start Expo dev server
bun run ios        # iOS simulator
bun run android    # Android emulator
bun run lint       # Check code style
bun run typecheck  # Type checking
```

## Environment Variables

```
EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
EXPO_PUBLIC_API_URL=http://localhost:3001
```

---

**For detailed patterns, code templates, and complete examples:** `references/full-guide.md`

Overview

This skill scaffolds a production-ready Expo React Native app with TypeScript, Expo Router navigation, optional Clerk authentication, and Bun as the package manager. It generates a runnable project with working screens, UI components, API client integration, and quality tooling so the app runs immediately with bun start. The output favors practical app structure over empty templates to accelerate development.

How this skill works

You provide a PRD-style brief or CLI options (app name, tabs, auth) and the tool generates a complete app directory: layouts, tab/stack routing, screens, components, providers, and TypeScript types. It wires optional Clerk auth flows, creates an API client and auth utilities, applies Biome linting and strict TypeScript settings, and includes commands to run and verify the app locally. The scaffold is ready to run with bun start and includes environment variable hints for API and Clerk keys.

When to use it

Starting a new mobile app and want a full working scaffold, not just empty files
Prototyping an app with navigation, auth, and API integration quickly
Bootstrapping teams to a consistent Expo + TypeScript + Bun setup
Creating apps that must meet linting and type-strict quality gates from day one
Generating sample screens and components to iterate UI and flows fast

Best practices

Provide a concise PRD-style brief listing core screens and features to get targeted scaffolding
Enable auth only if you plan to use Clerk or similar managed auth to avoid extra boilerplate
Use NativeWind for fast styling; opt into StyleSheet if you prefer classic RN styles
Keep API URLs and publishable keys in environment variables; never hardcode secrets
Run bun run lint and bun run typecheck after generation to catch issues early
Customize generated routes and components before adding heavy business logic to preserve structure

Example use cases

Create a fitness tracker app with Home, Workouts, and Profile tabs and optional Clerk sign-in
Scaffold a marketplace prototype with listing and checkout flows and an API client wired
Generate an internal admin mobile app with strict TypeScript checks and reusable entity components
Boot an MVP for user onboarding with prebuilt auth screens and navigation already wired
Produce consistent starter apps for multiple projects that share tooling and folder layout

FAQ

Will the generated project run immediately?

Yes. The scaffold is configured to run with bun start and includes essential scripts for iOS/android emulators and lint/type checks.

Is Clerk required?

No. Clerk is optional. Enabling auth adds provider wiring and sign-in/sign-up screens; leave it off to keep the app auth-free.

Which styling approach does the scaffold use?

You can choose NativeWind (Tailwind-like) for rapid styling or classic StyleSheet; both patterns are supported in the generated code.