gs-nextjs-web-client_skill

Overview

This skill is a practical guide for building Next.js 15+ and React 19+ frontends using Clean Architecture principles. It enforces a clear boundary: UI components receive DTOs from server actions and never import backend Entities or Use Cases directly. The guide covers component organization, server vs client components, forms, tables, naming conventions, and detection commands.

How this skill works

It defines a data flow where components call server actions and receive DTOs back, keeping application domain logic behind the feature boundary. Server components are the default for data fetching and rendering; client components are used only for interactivity and mutations, calling server actions via a client helper. The skill includes examples for forms (React Hook Form + Zod), tables, error handling, and file naming patterns to keep code consistent.

When to use it

• Creating UI components, pages, layouts or lists that fetch and render data
• Building interactive forms or mutation flows that require client-side behavior
• Organizing a Next.js project to follow Clean Architecture boundaries
• Adding tables or reusable display components typed with DTOs
• Standardizing component and hook naming across the app

Best practices

• Always import DTOs and actions from a feature index; never import backend Entities or Use Cases directly
• Default to server components for rendering; create explicit -client files for interactive behavior
• Type props with DTOs (e.g., items: CategoryDTO[]) instead of domain entities
• Handle action responses as [result, err] tuples and surface errors to the UI
• Follow the naming conventions: PascalCase for components, -client/-server suffixes, use-kebab for hooks, kebab-case for page folders

Example use cases

• Server-rendered category list: server component calls listCategoriesAction and maps CategoryDTOs into a table
• Interactive create form: a -client component uses useServerAction to call createCategoryAction and displays toast feedback
• Form validation: use React Hook Form with zodResolver and execute server action on submit, mapping errors to form.setError
• Reusable table component: accept DTO arrays and render consistent headers and rows
• Detection scripts: run grep checks to find accidental imports from backend or Entity usage