fullstack-workflow

This skill provides a comprehensive architectural pattern for developers building fullstack features within the Inbox Zero ecosystem. It enforces a strict separation of concerns, ensuring consistency across the codebase while streamlining the development lifecycle from data fetching to UI mutations. By leveraging established patterns like server actions for mutations and SWR for client-side state management, this workflow minimizes bugs and improves maintainability in feature-rich applications. It is ideal for software engineers working on complex Next.js projects who require a reliable template for high-performance data operations.

• Standardized data flow: Uses GET API routes for read-only data, wrapped with authentication middleware like withAuth or withEmailAccount for security.

• Mutative operations: Utilizes next-safe-action to define type-safe server actions, complete with Zod schemas for input validation and Sentry metadata for observability.

• Client-side optimization: Implements SWR hooks for efficient, performant data fetching and caching on the frontend.

• Form management: Integrates React Hook Form with zodResolver to ensure robust client-side validation before invoking server-side actions.

• Error handling: Features custom error toast utilities to gracefully manage and surface operational errors to the end-user.

• Always structure new features by splitting concerns: define validation schemas first, then the server action, followed by the API route and the corresponding SWR hook.

• Ensure all API routes are protected by the existing middleware to maintain secure access to email accounts and user contexts.

• Use the provided action clients (e.g., actionClient, actionClientUser) to ensure the correct context (userId or emailAccountId) is injected into every mutation.

• Leverage type inference by defining return types using Awaited<ReturnType<typeof getData>> for full IDE support and runtime safety.

• Keep logic separated; keep business logic in the server action and UI state logic in custom React hooks.