Development

Development Workflow

This guide covers Solo Kit's development workflow, debugging techniques, and best practices for building features efficiently.

🚀 Starting Development

Quick Start

# Start web app (most common)
pnpm dev

# Or be explicit
pnpm dev:web

This starts the Next.js development server with:

Hot reloading - Changes reflect instantly
Turbopack - Ultra-fast bundling
TypeScript checking - Real-time error detection
ESLint integration - Code quality feedback

Development Servers

# Web app only (default)
pnpm dev:web

# Mobile app only
pnpm dev:mobile

# Both apps simultaneously
pnpm dev:all

Expected output:

▲ Next.js 15.5.2 (Turbopack)
- Local:        http://localhost:3020
- Network:      http://192.168.1.100:3000

✓ Ready in 1.2s

🏗️ Project Structure for Development

Development File Types

apps/web/
├── 📄 Pages & Routes
│   ├── app/*/page.tsx          # Next.js pages
│   ├── app/*/layout.tsx        # Layout files
│   └── app/api/*/route.ts      # API routes
├── 🧩 Components
│   ├── components/ui/          # shadcn/ui (don't edit)
│   ├── components/features/    # Feature components
│   └── components/common/      # Reusable components
├── 🎣 Hooks
│   ├── hooks/use-*.ts          # Custom hooks
│   └── lib/hooks/              # Complex hooks
├── 📚 Business Logic
│   ├── lib/actions/            # Server actions
│   ├── lib/queries/            # Data fetching
│   └── lib/utils.ts            # Utilities
└── 🎨 Styling
    ├── app/globals.css         # Global styles
    └── components/**/*.module.css # Component styles

🔄 Development Workflow

1. Feature Development Cycle

# 1. Create new branch
git checkout -b feature/user-profile

# 2. Start development
pnpm dev

# 3. Make changes (hot reload active)
# 4. Test in browser at http://localhost:3020

# 5. Run quality checks (fast - changed files only)
pnpm lint:changed
pnpm type-check:changed

# 6. Commit changes
git add .
git commit -m "feat: add user profile management"

2. Adding New Features

Step-by-step process:

Plan the feature - Identify required components, routes, and data
Backend changes - Update schema and functions in convex/
API layer - Create Convex functions or server actions
UI components - Build necessary components
Pages/routes - Create or update pages
Testing - Test functionality manually and with tests

3. Making Changes

Component Development:

// 1. Create component
// components/features/profile/user-avatar.tsx
interface UserAvatarProps {
  user: { name: string; email: string; avatar?: string };
  size?: 'sm' | 'md' | 'lg';
}

export function UserAvatar({ user, size = 'md' }: UserAvatarProps) {
  return (
    <div className="flex items-center space-x-3">
      {/* Implementation */}
    </div>
  );
}

// 2. Use in page
// app/profile/page.tsx
import { UserAvatar } from '@/components/features/profile/user-avatar';

export default function ProfilePage() {
  return (
    <div>
      <UserAvatar user={currentUser} />
    </div>
  );
}

Backend Development:

// 1. Update schema
// convex/schema.ts
import { defineSchema, defineTable } from 'convex/server';
import { v } from 'convex/values';

export default defineSchema({
  users: defineTable({
    name: v.string(),
    avatarUrl: v.optional(v.string()),
    // ... other fields
  }),
});

// 2. Schema syncs automatically when running npx convex dev

// 3. Create queries
// convex/users.ts
import { query } from './_generated/server';
import { v } from 'convex/values';

export const getById = query({
  args: { userId: v.id('users') },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId);
  },
});

🐛 Debugging

Browser DevTools

React Developer Tools:

Install React DevTools browser extension
Open DevTools → Components tab
Inspect component state and props
Profile performance issues

Network Tab:

Monitor API calls and responses
Check request/response headers
Debug authentication issues
Verify data flow

Next.js Debugging

Server Components:

// Add logging in Server Components
export default async function Page() {
  const data = await getData();
  console.log('Server:', data); // Appears in terminal
  return <div>{data.title}</div>;
}

Client Components:

'use client';
import { useEffect } from 'react';

export function ClientComponent() {
  useEffect(() => {
    console.log('Client:', data); // Appears in browser console
  }, []);
}

Server Actions:

'use server';
export async function updateUser(data: FormData) {
  console.log('Action called:', data); // Terminal
  // Action implementation
}

Backend Debugging

Convex Dashboard:

npx convex dashboard

Opens the Convex dashboard to view data, functions, and logs.

Function Logs:

# View real-time Convex function logs
npx convex logs

Backend State:

# Check backend connection
curl http://localhost:3020/debug

# View function execution logs
npx convex logs --follow

🎯 Development Best Practices

1. Component Development

Colocate related files:

components/features/dashboard/
├── dashboard-layout.tsx
├── dashboard-stats.tsx
├── dashboard-stats.test.tsx
└── dashboard-stats.stories.tsx

Use TypeScript interfaces:

interface DashboardProps {
  user: User;
  stats: DashboardStats;
  onRefresh?: () => void;
}

export function Dashboard({ user, stats, onRefresh }: DashboardProps) {
  // Implementation
}

2. State Management

Server State (Recommended):

// Use Server Components for data fetching
async function UserProfile({ userId }: { userId: string }) {
  const user = await getUserById(userId);
  return <UserCard user={user} />;
}

Client State:

// Use React hooks for UI state
function UserSettings() {
  const [isEditing, setIsEditing] = useState(false);
  const [settings, setSettings] = useState(defaultSettings);

  return (
    <div>
      {isEditing ? <EditForm /> : <DisplaySettings />}
    </div>
  );
}

3. Error Handling

Server Components:

// app/profile/error.tsx
'use client';

export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

Client Components:

import { toastError } from '@/components/Toast';

function handleSubmit(data: FormData) {
  try {
    await updateUser(data);
    toastSuccess({ description: 'Profile updated!' });
  } catch (error) {
    toastError({
      title: 'Error',
      description: 'Failed to update profile',
    });
  }
}

📱 Mobile Development

Starting Mobile Development

# Start mobile development server
pnpm dev:mobile

# Platform-specific
pnpm dev:mobile:ios
pnpm dev:mobile:android

Mobile vs Web Development

Shared Code:

UI components in packages/ui/
Utilities in packages/utils/
Database schemas and queries

Platform-Specific:

Navigation patterns
Platform APIs (camera, location, etc.)
Screen layouts and interactions

Mobile Testing

Expo Go App:

Install Expo Go on your device
Scan QR code from terminal
Test on real device instantly

Simulators:

# iOS Simulator (macOS only)
npx expo run:ios

# Android Emulator
npx expo run:android

⚡ Performance Optimization

Development Performance

Fast Commands (Development):

# Only check changed packages (6-8x faster)
pnpm lint:changed
pnpm type-check:changed
pnpm test:changed

Full Validation (CI/Production):

# Complete validation
pnpm ci
pnpm lint
pnpm type-check

Code Splitting

// Lazy load heavy components
import dynamic from 'next/dynamic';

const HeavyChart = dynamic(
  () => import('@/components/features/analytics/heavy-chart'),
  { loading: () => <div>Loading chart...</div> }
);

Image Optimization

import Image from 'next/image';

function UserAvatar({ src, alt }: { src: string; alt: string }) {
  return (
    <Image
      src={src}
      alt={alt}
      width={40}
      height={40}
      className="rounded-full"
    />
  );
}

🔧 Development Tools

VS Code Integration

Launch Configuration (.vscode/launch.json):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "pnpm dev",
      "serverReadyAction": {
        "pattern": "started server on .+, url: (https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

Useful Extensions:

TypeScript Importer
Auto Import ES6
Tailwind CSS IntelliSense
ESLint
Prettier

Terminal Productivity

Useful Aliases:

# Add to your shell profile
alias sd="pnpm dev"
alias sb="pnpm build"
alias sl="pnpm lint:changed"
alias st="pnpm type-check:changed"

Development Scripts:

# Quick development status
pnpm dev &
npx convex dashboard  # Data browser
code .                # Open in VS Code

🧪 Testing During Development

Manual Testing Workflow

Start development server - pnpm dev
Test core functionality - Sign up, login, main features
Test responsive design - Resize browser, mobile view
Test error states - Invalid inputs, network errors
Test performance - Large datasets, slow networks

Automated Testing

# Run tests in watch mode
pnpm test:watch

# Test specific files
pnpm test user-profile

# Run tests with coverage
pnpm test --coverage

Backend Testing

Test with Demo Data:

# Use Convex dashboard to add test data
npx convex dashboard

# Or run seed functions if configured
npx convex run seed:demo

🔍 Common Development Issues

TypeScript Issues

Problem: Module not found or type errors

# Solutions
pnpm build:packages    # Rebuild shared packages
pnpm type-check        # Check for type errors
rm -rf .next && pnpm dev  # Clear Next.js cache

Problem: Auto-imports not working

// Check tsconfig.json paths
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./apps/web/*"],
      "@packages/ui": ["./packages/ui/src"]
    }
  }
}

Hot Reload Issues

Problem: Changes not reflecting

# Solutions
rm -rf .next/          # Clear Next.js cache
rm -rf node_modules/.cache/  # Clear build cache
pnpm install           # Reinstall dependencies

Problem: CSS changes not updating

# Force reload Tailwind
pnpm dev --turbo --force

Backend Issues

Problem: Convex connection errors

# Check environment
cat .env.local | grep CONVEX

# Test connection
npx convex dashboard

# Re-sync schema
npx convex dev

Performance Issues

Problem: Slow development server

# Use Turbopack (default in dev)
pnpm dev

# Clear all caches
pnpm clean
pnpm install
pnpm dev

🎯 Development Checklist

Before Starting Work

pnpm install - Dependencies up to date
NEXT_PUBLIC_CONVEX_URL configured in .env.local
pnpm dev starts without errors
Database connection works (/debug)

During Development

Hot reload working properly
TypeScript errors resolved
Console free of warnings/errors
Mobile responsiveness tested
Authentication flows working

Before Committing

Code Quality

Components are reusable and well-named
TypeScript interfaces defined
Error handling implemented
Loading states added
Responsive design verified

🚀 Next Steps

With a solid understanding of the development workflow:

Conventions - Learn coding standards and patterns
Common Commands - Master the command-line tools
Troubleshooting - Solve common development issues
Database Guide - Deep dive into database development

Master this development workflow to build features efficiently and maintain high code quality throughout your Solo Kit project.

Development

Development Workflow

This guide covers Solo Kit's development workflow, debugging techniques, and best practices for building features efficiently.

🚀 Starting Development

Quick Start

# Start web app (most common)
pnpm dev

# Or be explicit
pnpm dev:web

This starts the Next.js development server with:

Hot reloading - Changes reflect instantly
Turbopack - Ultra-fast bundling
TypeScript checking - Real-time error detection
ESLint integration - Code quality feedback

Development Servers

# Web app only (default)
pnpm dev:web

# Mobile app only
pnpm dev:mobile

# Both apps simultaneously
pnpm dev:all

Expected output:

▲ Next.js 15.5.2 (Turbopack)
- Local:        http://localhost:3020
- Network:      http://192.168.1.100:3000

✓ Ready in 1.2s

🏗️ Project Structure for Development

Development File Types

apps/web/
├── 📄 Pages & Routes
│   ├── app/*/page.tsx          # Next.js pages
│   ├── app/*/layout.tsx        # Layout files
│   └── app/api/*/route.ts      # API routes
├── 🧩 Components
│   ├── components/ui/          # shadcn/ui (don't edit)
│   ├── components/features/    # Feature components
│   └── components/common/      # Reusable components
├── 🎣 Hooks
│   ├── hooks/use-*.ts          # Custom hooks
│   └── lib/hooks/              # Complex hooks
├── 📚 Business Logic
│   ├── lib/actions/            # Server actions
│   ├── lib/queries/            # Data fetching
│   └── lib/utils.ts            # Utilities
└── 🎨 Styling
    ├── app/globals.css         # Global styles
    └── components/**/*.module.css # Component styles

🔄 Development Workflow

1. Feature Development Cycle

# 1. Create new branch
git checkout -b feature/user-profile

# 2. Start development
pnpm dev

# 3. Make changes (hot reload active)
# 4. Test in browser at http://localhost:3020

# 5. Run quality checks (fast - changed files only)
pnpm lint:changed
pnpm type-check:changed

# 6. Commit changes
git add .
git commit -m "feat: add user profile management"

2. Adding New Features

Step-by-step process:

Plan the feature - Identify required components, routes, and data
Backend changes - Update schema and functions in convex/
API layer - Create Convex functions or server actions
UI components - Build necessary components
Pages/routes - Create or update pages
Testing - Test functionality manually and with tests

3. Making Changes

Component Development:

// 1. Create component
// components/features/profile/user-avatar.tsx
interface UserAvatarProps {
  user: { name: string; email: string; avatar?: string };
  size?: 'sm' | 'md' | 'lg';
}

export function UserAvatar({ user, size = 'md' }: UserAvatarProps) {
  return (
    <div className="flex items-center space-x-3">
      {/* Implementation */}
    </div>
  );
}

// 2. Use in page
// app/profile/page.tsx
import { UserAvatar } from '@/components/features/profile/user-avatar';

export default function ProfilePage() {
  return (
    <div>
      <UserAvatar user={currentUser} />
    </div>
  );
}

Backend Development:

// 1. Update schema
// convex/schema.ts
import { defineSchema, defineTable } from 'convex/server';
import { v } from 'convex/values';

export default defineSchema({
  users: defineTable({
    name: v.string(),
    avatarUrl: v.optional(v.string()),
    // ... other fields
  }),
});

// 2. Schema syncs automatically when running npx convex dev

// 3. Create queries
// convex/users.ts
import { query } from './_generated/server';
import { v } from 'convex/values';

export const getById = query({
  args: { userId: v.id('users') },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId);
  },
});

🐛 Debugging

Browser DevTools

React Developer Tools:

Install React DevTools browser extension
Open DevTools → Components tab
Inspect component state and props
Profile performance issues

Network Tab:

Monitor API calls and responses
Check request/response headers
Debug authentication issues
Verify data flow

Next.js Debugging

Server Components:

// Add logging in Server Components
export default async function Page() {
  const data = await getData();
  console.log('Server:', data); // Appears in terminal
  return <div>{data.title}</div>;
}

Client Components:

'use client';
import { useEffect } from 'react';

export function ClientComponent() {
  useEffect(() => {
    console.log('Client:', data); // Appears in browser console
  }, []);
}

Server Actions:

'use server';
export async function updateUser(data: FormData) {
  console.log('Action called:', data); // Terminal
  // Action implementation
}

Backend Debugging

Convex Dashboard:

npx convex dashboard

Opens the Convex dashboard to view data, functions, and logs.

Function Logs:

# View real-time Convex function logs
npx convex logs

Backend State:

# Check backend connection
curl http://localhost:3020/debug

# View function execution logs
npx convex logs --follow

🎯 Development Best Practices

1. Component Development

Colocate related files:

components/features/dashboard/
├── dashboard-layout.tsx
├── dashboard-stats.tsx
├── dashboard-stats.test.tsx
└── dashboard-stats.stories.tsx

Use TypeScript interfaces:

interface DashboardProps {
  user: User;
  stats: DashboardStats;
  onRefresh?: () => void;
}

export function Dashboard({ user, stats, onRefresh }: DashboardProps) {
  // Implementation
}

2. State Management

Server State (Recommended):

// Use Server Components for data fetching
async function UserProfile({ userId }: { userId: string }) {
  const user = await getUserById(userId);
  return <UserCard user={user} />;
}

Client State:

// Use React hooks for UI state
function UserSettings() {
  const [isEditing, setIsEditing] = useState(false);
  const [settings, setSettings] = useState(defaultSettings);

  return (
    <div>
      {isEditing ? <EditForm /> : <DisplaySettings />}
    </div>
  );
}

3. Error Handling

Server Components:

// app/profile/error.tsx
'use client';

export default function Error({
  error,
  reset,
}: {
  error: Error;
  reset: () => void;
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

Client Components:

import { toastError } from '@/components/Toast';

function handleSubmit(data: FormData) {
  try {
    await updateUser(data);
    toastSuccess({ description: 'Profile updated!' });
  } catch (error) {
    toastError({
      title: 'Error',
      description: 'Failed to update profile',
    });
  }
}

📱 Mobile Development

Starting Mobile Development

# Start mobile development server
pnpm dev:mobile

# Platform-specific
pnpm dev:mobile:ios
pnpm dev:mobile:android

Mobile vs Web Development

Shared Code:

UI components in packages/ui/
Utilities in packages/utils/
Database schemas and queries

Platform-Specific:

Navigation patterns
Platform APIs (camera, location, etc.)
Screen layouts and interactions

Mobile Testing

Expo Go App:

Install Expo Go on your device
Scan QR code from terminal
Test on real device instantly

Simulators:

# iOS Simulator (macOS only)
npx expo run:ios

# Android Emulator
npx expo run:android

⚡ Performance Optimization

Development Performance

Fast Commands (Development):

# Only check changed packages (6-8x faster)
pnpm lint:changed
pnpm type-check:changed
pnpm test:changed

Full Validation (CI/Production):

# Complete validation
pnpm ci
pnpm lint
pnpm type-check

Code Splitting

// Lazy load heavy components
import dynamic from 'next/dynamic';

const HeavyChart = dynamic(
  () => import('@/components/features/analytics/heavy-chart'),
  { loading: () => <div>Loading chart...</div> }
);

Image Optimization

import Image from 'next/image';

function UserAvatar({ src, alt }: { src: string; alt: string }) {
  return (
    <Image
      src={src}
      alt={alt}
      width={40}
      height={40}
      className="rounded-full"
    />
  );
}

🔧 Development Tools

VS Code Integration

Launch Configuration (.vscode/launch.json):

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "pnpm dev",
      "serverReadyAction": {
        "pattern": "started server on .+, url: (https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

Useful Extensions:

TypeScript Importer
Auto Import ES6
Tailwind CSS IntelliSense
ESLint
Prettier

Terminal Productivity

Useful Aliases:

# Add to your shell profile
alias sd="pnpm dev"
alias sb="pnpm build"
alias sl="pnpm lint:changed"
alias st="pnpm type-check:changed"

Development Scripts:

# Quick development status
pnpm dev &
npx convex dashboard  # Data browser
code .                # Open in VS Code

🧪 Testing During Development

Manual Testing Workflow

Start development server - pnpm dev
Test core functionality - Sign up, login, main features
Test responsive design - Resize browser, mobile view
Test error states - Invalid inputs, network errors
Test performance - Large datasets, slow networks

Automated Testing

# Run tests in watch mode
pnpm test:watch

# Test specific files
pnpm test user-profile

# Run tests with coverage
pnpm test --coverage

Backend Testing

Test with Demo Data:

# Use Convex dashboard to add test data
npx convex dashboard

# Or run seed functions if configured
npx convex run seed:demo

🔍 Common Development Issues

TypeScript Issues

Problem: Module not found or type errors

# Solutions
pnpm build:packages    # Rebuild shared packages
pnpm type-check        # Check for type errors
rm -rf .next && pnpm dev  # Clear Next.js cache

Problem: Auto-imports not working

// Check tsconfig.json paths
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./apps/web/*"],
      "@packages/ui": ["./packages/ui/src"]
    }
  }
}

Hot Reload Issues

Problem: Changes not reflecting

# Solutions
rm -rf .next/          # Clear Next.js cache
rm -rf node_modules/.cache/  # Clear build cache
pnpm install           # Reinstall dependencies

Problem: CSS changes not updating

# Force reload Tailwind
pnpm dev --turbo --force

Backend Issues

Problem: Convex connection errors

# Check environment
cat .env.local | grep CONVEX

# Test connection
npx convex dashboard

# Re-sync schema
npx convex dev

Performance Issues

Problem: Slow development server

# Use Turbopack (default in dev)
pnpm dev

# Clear all caches
pnpm clean
pnpm install
pnpm dev

🎯 Development Checklist

Before Starting Work

pnpm install - Dependencies up to date
NEXT_PUBLIC_CONVEX_URL configured in .env.local
pnpm dev starts without errors
Database connection works (/debug)

During Development

Hot reload working properly
TypeScript errors resolved
Console free of warnings/errors
Mobile responsiveness tested
Authentication flows working

Before Committing

Code Quality

Components are reusable and well-named
TypeScript interfaces defined
Error handling implemented
Loading states added
Responsive design verified

🚀 Next Steps

With a solid understanding of the development workflow:

Conventions - Learn coding standards and patterns
Common Commands - Master the command-line tools
Troubleshooting - Solve common development issues
Database Guide - Deep dive into database development

Master this development workflow to build features efficiently and maintain high code quality throughout your Solo Kit project.

Development

On this page

Development

On this page