@jarrodmedrano/claude-skills 1.0.13 → 1.0.14

package/.claude/commands/new-fullstack.md

@@ -13,6 +13,7 @@ When this skill is invoked:
    - T3 Stack (Next.js + tRPC + Prisma + Tailwind)
    - MERN (MongoDB + Express + React + Node)
    - Monorepo (React frontend + Express backend + shared types)
+   - Solito (Expo + Next.js + shared navigation - Universal app for web + mobile)
 
 2. Extract the project name from args, or ask if not provided
 
@@ -46,6 +47,86 @@ When this skill is invoked:
      ```
    - Set up npm workspaces or pnpm workspace
 
+   **Solito (Universal App)**:
+   - Ask follow-up questions:
+     * Package manager? (pnpm recommended, yarn, npm)
+     * Include NativeWind? (Tailwind for React Native)
+     * Include authentication? (Clerk, Supabase, custom, skip)
+     * Include API layer? (tRPC, REST, skip)
+     * Include UI library? (Tamagui, React Native Paper, custom, skip)
+
+   - Use Solito starter template:
+     ```bash
+     npx create-solito-app@latest {project-name}
+     ```
+     Or create manually if custom setup needed
+
+   - Create monorepo structure:
+     ```
+     {project-name}/
+       apps/
+         expo/              # React Native mobile app
+           app/             # Expo Router file-system routes
+           package.json
+           app.json
+         next/              # Next.js web app
+           app/             # Next.js App Router
+           public/
+           package.json
+           next.config.js
+       packages/
+         app/               # Shared UI and navigation
+           features/        # Feature screens
+           components/      # Reusable components
+           lib/            # Utilities
+           provider/       # Navigation provider
+           package.json
+         api/              # Shared API client (if selected)
+           package.json
+       package.json        # Root workspace config
+       pnpm-workspace.yaml # or yarn/npm workspace
+       turbo.json         # Turborepo config
+     ```
+
+   - Configure based on selections:
+     * **NativeWind**: Set up Tailwind config, Metro config, Babel plugin
+     * **Clerk**: Install @clerk/clerk-expo and @clerk/nextjs, configure providers
+     * **Supabase**: Install @supabase/supabase-js, set up client
+     * **tRPC**: Configure tRPC client, create example router
+     * **Tamagui**: Install and configure Tamagui for universal styling
+
+   - Add example screens:
+     * Home screen (apps/expo/app/index.tsx and apps/next/app/page.tsx)
+     * Profile screen with navigation
+     * Demonstrate shared navigation with solito/link
+
+   - Configure Metro bundler to watch monorepo
+   - Set up TypeScript path aliases
+   - Create .env.example for both platforms (NEXT_PUBLIC_ and EXPO_PUBLIC_)
+
+   - Add development scripts to root package.json:
+     ```json
+     {
+       "scripts": {
+         "dev": "turbo run dev",
+         "dev:next": "pnpm --filter next-app dev",
+         "dev:expo": "pnpm --filter expo-app start",
+         "build": "turbo run build",
+         "lint": "turbo run lint",
+         "typecheck": "turbo run typecheck"
+       }
+     }
+     ```
+
+   - Create README with:
+     * Project structure explanation
+     * Setup instructions (pnpm install)
+     * How to run web app (cd apps/next && pnpm dev)
+     * How to run mobile app (cd apps/expo && pnpm start)
+     * Shared code location (packages/app)
+     * Platform-specific code guidelines
+     * Deployment instructions (Vercel for web, EAS for mobile)
+
 4. Set up database and ORM:
    - Create database schema/models
    - Set up migration scripts
@@ -73,3 +154,5 @@ When this skill is invoked:
 **Example usage**:
 - `/new-fullstack my-saas-app`
 - `/new-fullstack` (will prompt for name)
+
+**Note**: For Solito projects, automatically invoke the `solito` skill after project creation to provide specialized guidance for cross-platform development, navigation patterns, and best practices.

package/.claude/skills/solito/SKILL.md

@@ -0,0 +1,604 @@
+---
+name: solito
+description: This skill should be used when working on Solito projects (Expo + Next.js with shared navigation). It provides specialized knowledge for cross-platform navigation, monorepo structure, shared component patterns, platform-specific code handling, and common pitfalls. Use this skill when building universal apps, implementing navigation, creating shared UI components, or debugging cross-platform issues.
+---
+
+# Solito Cross-Platform Development Skill
+
+A specialized skill for building universal applications using Solito, combining Expo (React Native) and Next.js with shared navigation and component libraries.
+
+## When to Use This Skill
+
+Invoke this skill when:
+- Building universal apps (web + mobile) with shared code
+- Implementing cross-platform navigation
+- Creating shared UI components that work on web and native
+- Setting up monorepo structure for Solito projects
+- Handling platform-specific code (web-only or native-only features)
+- Implementing authentication across platforms
+- Debugging navigation or routing issues
+- Optimizing bundle sizes for web and native
+
+## What is Solito?
+
+Solito enables developers to share navigation code between React Native (Expo) and Next.js. Instead of maintaining separate routing logic for web and mobile, Solito provides a unified navigation layer that respects platform-specific patterns while sharing as much code as possible.
+
+**Key Benefits:**
+- Single source of truth for navigation
+- File-system routing for native apps (via Expo Router)
+- Shared UI components with platform-specific optimizations
+- Unified API for links and navigation
+- Type-safe routing with TypeScript
+
+## Before You Start: Essential Solito Tips
+
+### Project Structure First
+
+**Solito projects use monorepo architecture.** Always structure your project correctly from the start:
+
+```
+my-app/
+  apps/
+    expo/          # React Native mobile app
+    next/          # Next.js web app
+  packages/
+    app/           # Shared UI components & navigation
+    api/           # Shared API client (optional)
+  package.json     # Workspace configuration
+```
+
+**See `references/monorepo-setup.md` for detailed workspace configuration.**
+
+### Use Solito Starter Template
+
+The official Solito starter saves hours of configuration:
+
+```bash
+npx create-solito-app@latest my-app
+```
+
+Choose your preferred package manager (pnpm recommended for monorepos).
+
+### Navigation is Different
+
+**Don't use Next.js Link or React Navigation Link directly.** Use Solito's unified components:
+
+```tsx
+import { Link } from 'solito/link'
+
+// ✅ CORRECT: Works on both web and native
+<Link href="/profile">
+  <Text>View Profile</Text>
+</Link>
+
+// ❌ WRONG: Next.js-only
+import Link from 'next/link'
+
+// ❌ WRONG: React Navigation-only
+import { Link } from '@react-navigation/native'
+```
+
+**See `references/navigation-patterns.md` for detailed routing patterns.**
+
+## Core Development Principles
+
+### 1. Shared by Default, Platform-Specific When Needed
+
+**80% of your code should live in `packages/app`.** Only create platform-specific code when absolutely necessary.
+
+```tsx
+// packages/app/features/home/screen.tsx
+// ✅ GOOD: Shared screen component
+export function HomeScreen() {
+  return (
+    <View>
+      <Text>Welcome!</Text>
+      <Link href="/profile">
+        <Text>Go to Profile</Text>
+      </Link>
+    </View>
+  )
+}
+```
+
+Platform-specific code should be minimal:
+
+```tsx
+// packages/app/components/map.tsx
+import { Platform } from 'react-native'
+
+export function Map() {
+  // ✅ GOOD: Platform detection for necessary differences
+  if (Platform.OS === 'web') {
+    return <WebMapComponent />
+  }
+  return <NativeMapComponent />
+}
+```
+
+### 2. Think in Features, Not Platforms
+
+**Organize by feature domain, not by platform:**
+
+```
+packages/app/
+  features/
+    home/
+      screen.tsx       # Home screen
+      components/      # Home-specific components
+    profile/
+      screen.tsx       # Profile screen
+      components/
+    auth/
+      login-screen.tsx
+      register-screen.tsx
+  components/         # Shared UI components
+  provider/           # Navigation provider
+  navigation/         # Navigation configuration
+```
+
+**Not organized by platform:**
+```
+❌ BAD:
+packages/app/
+  web/
+    screens/
+  native/
+    screens/
+```
+
+### 3. Navigation is Central
+
+**Design your navigation structure early.** Solito uses file-system routing on native and Next.js App Router on web.
+
+**Navigation mapping:**
+```tsx
+// apps/next/app/profile/page.tsx (web route)
+import { ProfileScreen } from 'app/features/profile/screen'
+
+export default ProfileScreen
+
+// apps/expo/app/profile.tsx (native route)
+import { ProfileScreen } from 'app/features/profile/screen'
+
+export default ProfileScreen
+```
+
+Both platforms render the same `ProfileScreen` component from `packages/app`.
+
+**See `references/navigation-patterns.md` for routing patterns, params, and navigation hooks.**
+
+## Development Workflow
+
+### Local Development
+
+**Run both platforms simultaneously:**
+
+Terminal 1 - Web:
+```bash
+cd apps/next
+pnpm dev
+```
+
+Terminal 2 - Mobile:
+```bash
+cd apps/expo
+pnpm start
+```
+
+Press `i` for iOS simulator, `a` for Android emulator, or scan QR code for physical device.
+
+### Making Changes
+
+1. **Create shared component** in `packages/app/components/`
+2. **Create screen** in `packages/app/features/[feature]/screen.tsx`
+3. **Add routes** in both `apps/next/app/` and `apps/expo/app/`
+4. **Test on both platforms** to verify cross-platform behavior
+
+### Common Commands
+
+```bash
+# Install dependencies (from root)
+pnpm install
+
+# Run web dev server
+cd apps/next && pnpm dev
+
+# Run Expo dev server
+cd apps/expo && pnpm start
+
+# Type checking
+pnpm typecheck
+
+# Lint all packages
+pnpm lint
+
+# Build for production
+pnpm build
+```
+
+## Styling with NativeWind
+
+NativeWind brings Tailwind CSS to React Native, enabling shared styling across platforms.
+
+```tsx
+import { View, Text } from 'react-native'
+
+// ✅ GOOD: Tailwind classes work on both platforms
+export function Card() {
+  return (
+    <View className="bg-white rounded-lg p-4 shadow-md">
+      <Text className="text-xl font-bold">Title</Text>
+      <Text className="text-gray-600">Description</Text>
+    </View>
+  )
+}
+```
+
+**Platform-specific styles when needed:**
+```tsx
+<View className="p-4 web:p-6 native:p-2">
+  {/* Different padding on web vs native */}
+</View>
+```
+
+### Design Tokens
+
+**Use shared design tokens in `packages/app/design/tokens.ts`:**
+
+```tsx
+export const colors = {
+  primary: '#3B82F6',
+  secondary: '#10B981',
+  background: '#FFFFFF',
+  text: '#1F2937',
+}
+
+export const spacing = {
+  xs: 4,
+  sm: 8,
+  md: 16,
+  lg: 24,
+  xl: 32,
+}
+```
+
+## Authentication Patterns
+
+**Share auth logic across platforms:**
+
+```tsx
+// packages/app/lib/auth.ts
+import { createContext, useContext } from 'react'
+
+interface AuthContextType {
+  user: User | null
+  signIn: (email: string, password: string) => Promise<void>
+  signOut: () => Promise<void>
+}
+
+export const AuthContext = createContext<AuthContextType>(null!)
+
+export function useAuth() {
+  return useContext(AuthContext)
+}
+```
+
+**Use in components:**
+```tsx
+import { useAuth } from 'app/lib/auth'
+
+export function ProfileScreen() {
+  const { user, signOut } = useAuth()
+
+  return (
+    <View>
+      <Text>Welcome, {user?.name}</Text>
+      <Button onPress={signOut}>Sign Out</Button>
+    </View>
+  )
+}
+```
+
+**Popular auth solutions:**
+- **Clerk** - Excellent Solito integration, works on both platforms
+- **Supabase** - Self-hosted option with good RN support
+- **Custom JWT** - Full control, requires more setup
+
+## API Integration
+
+**Share API client in `packages/api/`:**
+
+```tsx
+// packages/api/client.ts
+const API_URL = process.env.NEXT_PUBLIC_API_URL
+
+export async function fetchUser(id: string) {
+  const response = await fetch(`${API_URL}/users/${id}`)
+  return response.json()
+}
+```
+
+**Use with tRPC for type-safety:**
+```tsx
+// packages/api/trpc.ts
+import { initTRPC } from '@trpc/server'
+
+const t = initTRPC.create()
+
+export const appRouter = t.router({
+  getUser: t.procedure
+    .input(z.string())
+    .query(async ({ input }) => {
+      return db.user.findUnique({ where: { id: input } })
+    }),
+})
+
+export type AppRouter = typeof appRouter
+```
+
+**tRPC works seamlessly across web and native with full type-safety.**
+
+## State Management
+
+**Recommended: Zustand** (lightweight, works great with Solito)
+
+```tsx
+// packages/app/store/user.ts
+import { create } from 'zustand'
+
+interface UserState {
+  user: User | null
+  setUser: (user: User | null) => void
+}
+
+export const useUserStore = create<UserState>((set) => ({
+  user: null,
+  setUser: (user) => set({ user }),
+}))
+```
+
+**Use in components:**
+```tsx
+import { useUserStore } from 'app/store/user'
+
+export function ProfileScreen() {
+  const user = useUserStore((state) => state.user)
+
+  return <Text>Welcome, {user?.name}</Text>
+}
+```
+
+**Other options:**
+- **Jotai** - Atomic state management
+- **Redux Toolkit** - For complex state needs
+- **React Context** - For simple global state
+
+## Platform-Specific Code
+
+**Use platform detection sparingly:**
+
+```tsx
+import { Platform } from 'react-native'
+
+export function VideoPlayer() {
+  if (Platform.OS === 'web') {
+    return <video src={url} controls />
+  }
+
+  // Use native video component
+  return <Video source={{ uri: url }} />
+}
+```
+
+**Better: Use platform-specific files:**
+
+```
+packages/app/components/
+  video-player.tsx         # Shared interface
+  video-player.web.tsx     # Web implementation
+  video-player.native.tsx  # Native implementation
+```
+
+```tsx
+// video-player.tsx
+export { VideoPlayer } from './video-player.native'
+```
+
+Metro bundler and Next.js will automatically resolve the correct file.
+
+**See `references/platform-specific.md` for detailed patterns.**
+
+## Common Pitfalls to Avoid
+
+**Critical mistakes and their solutions are documented in `references/common-pitfalls.md`. Key pitfalls include:**
+
+1. Using Next.js Link or React Navigation Link directly
+2. Hardcoding absolute URLs (use relative paths)
+3. Not handling navigation params correctly
+4. Importing from wrong packages (next/link vs solito/link)
+5. Forgetting to configure navigation provider
+6. Not testing on both platforms regularly
+7. Overusing platform-specific code
+
+Review `references/common-pitfalls.md` before implementing navigation or shared components.
+
+## Performance Optimization
+
+### Bundle Size
+
+**Keep packages/app lean:**
+- Avoid large dependencies in shared code
+- Use dynamic imports for heavy features
+- Split platform-specific dependencies
+
+```tsx
+// ✅ GOOD: Dynamic import for heavy feature
+const HeavyChart = dynamic(() => import('./heavy-chart'))
+```
+
+### Navigation Performance
+
+**Preload screens for better UX:**
+```tsx
+import { useRouter } from 'solito/router'
+
+export function HomeScreen() {
+  const router = useRouter()
+
+  // Preload profile screen on hover/focus
+  const handlePreload = () => {
+    router.push('/profile', undefined, { shallow: true })
+  }
+
+  return (
+    <Link href="/profile" onHoverIn={handlePreload}>
+      <Text>Profile</Text>
+    </Link>
+  )
+}
+```
+
+### Image Optimization
+
+**Use Next.js Image on web, optimized Image on native:**
+
+```tsx
+// packages/app/components/optimized-image.tsx
+import { Platform } from 'react-native'
+import NextImage from 'next/image'
+import { Image as RNImage } from 'react-native'
+
+export function OptimizedImage({ src, width, height, alt }) {
+  if (Platform.OS === 'web') {
+    return <NextImage src={src} width={width} height={height} alt={alt} />
+  }
+
+  return <RNImage source={{ uri: src }} style={{ width, height }} />
+}
+```
+
+## Testing Strategy
+
+### Unit Tests
+
+**Test shared logic in packages/app:**
+
+```tsx
+// packages/app/lib/__tests__/format.test.ts
+import { formatCurrency } from '../format'
+
+describe('formatCurrency', () => {
+  it('formats USD correctly', () => {
+    expect(formatCurrency(1234.56, 'USD')).toBe('$1,234.56')
+  })
+})
+```
+
+### Component Tests
+
+**Use React Native Testing Library:**
+
+```tsx
+import { render, screen } from '@testing-library/react-native'
+import { HomeScreen } from '../screen'
+
+test('renders welcome message', () => {
+  render(<HomeScreen />)
+  expect(screen.getByText('Welcome!')).toBeTruthy()
+})
+```
+
+### E2E Tests
+
+**Playwright for web, Detox for native:**
+
+```typescript
+// apps/next/e2e/home.spec.ts
+import { test, expect } from '@playwright/test'
+
+test('navigates to profile', async ({ page }) => {
+  await page.goto('/')
+  await page.click('text=Profile')
+  await expect(page).toHaveURL('/profile')
+})
+```
+
+## Deployment
+
+### Web (Next.js)
+
+**Deploy to Vercel (recommended):**
+
+```bash
+cd apps/next
+vercel deploy
+```
+
+Configure environment variables in Vercel dashboard.
+
+### Mobile (Expo)
+
+**Build with EAS:**
+
+```bash
+cd apps/expo
+
+# Install EAS CLI
+npm install -g eas-cli
+
+# Configure project
+eas build:configure
+
+# Build for iOS
+eas build --platform ios
+
+# Build for Android
+eas build --platform android
+
+# Submit to stores
+eas submit
+```
+
+**Over-the-air updates:**
+```bash
+eas update --branch production
+```
+
+## References
+
+This skill includes detailed reference documentation:
+
+- `references/navigation-patterns.md` - Link usage, router hooks, params, navigation state
+- `references/monorepo-setup.md` - Workspace configuration, package structure, dependencies
+- `references/platform-specific.md` - Platform detection, conditional rendering, file extensions
+- `references/common-pitfalls.md` - Import issues, navigation bugs, platform quirks
+
+Load these references as needed to inform implementation decisions.
+
+## Additional Resources
+
+**Solito Documentation:**
+- Official Docs: https://solito.dev/
+- Solito Starter: https://github.com/nandorojo/solito
+- Example Apps: https://github.com/nandorojo/solito/tree/master/example-monorepos
+
+**Related Technologies:**
+- Expo Router: https://docs.expo.dev/router/introduction/
+- Next.js App Router: https://nextjs.org/docs/app
+- NativeWind: https://www.nativewind.dev/
+- React Navigation: https://reactnavigation.org/
+
+**State Management:**
+- Zustand: https://github.com/pmndrs/zustand
+- Jotai: https://jotai.org/
+- Redux Toolkit: https://redux-toolkit.js.org/
+
+**Authentication:**
+- Clerk: https://clerk.com/
+- Supabase: https://supabase.com/
+- NextAuth.js: https://next-auth.js.org/
+
+---
+
+**Remember:** Share code by default, create platform-specific code only when necessary. Design your navigation structure early, test on both platforms regularly, and keep `packages/app` as the single source of truth for your application logic.