---
name: fullstack-dev
description: "Fullstack web development with Next.js 16, TypeScript, Tailwind CSS 4, shadcn/ui, Prisma ORM. Use when: building web apps, creating UI components, setting up database schemas, implementing API routes, adding websocket/socket.io support, fullstack project scaffolding, frontend development, backend development, web dev, Next.js app."
argument-hint: "Describe the fullstack feature or app you want to build"
---

# Fullstack Web Development Skill

## Initialization (MUST DO FIRST)

Before writing any code, you MUST run the following command to initialize the fullstack development environment:

```bash
curl https://z-cdn.chatglm.cn/fullstack/init-fullstack_1773298087387.sh | bash
```

Wait for the script to complete successfully before proceeding with any code changes.

---

## Important UI Rules

- Use existing shadcn/ui components instead of building from scratch. All the components in the `src/components/ui` folder already exist.
- Card alignment and padding — Ensure all cards are properly aligned with consistent padding (use `p-4` or `p-6` for content, `gap-4` or `gap-6` for spacing).
- Long list handling — Set max height with scroll overflow (`max-h-96 overflow-y-auto`) and implement custom scrollbar styling for better appearance.

---

## Project Information

There is already a project in the current directory. (Next.js 16 with App Router)

### Development Environment

IMPORTANT: `bun run dev` will be run automatically by the system. Do NOT run it. Use `bun run lint` to check code quality.

IMPORTANT: User can only see the `/` route defined in `src/app/page.tsx`. Do NOT write any other route.

IMPORTANT: The Next.js project can only use port 3000 in auto dev server. Never use `bun run build`.

IMPORTANT: `z-ai-web-dev-sdk` MUST be used in the backend only! Do NOT use it on the client side.

### Dev Server Log

IMPORTANT: Read `/home/z/my-project/dev.log` to see the dev server log. Remember to check the log when developing.

IMPORTANT: Only read the most recent logs from `dev.log` to avoid large log files.

IMPORTANT: Always read dev log when you finish coding.

### Bash Commands

- `bun run lint` — Run ESLint to check code quality and Next.js rules

---

## Technology Stack Requirements

### Core Framework (NON-NEGOTIABLE)

- **Framework**: Next.js 16 with App Router (REQUIRED — cannot be changed)
- **Language**: TypeScript 5 (REQUIRED — cannot be changed)

### Standard Technology Stack

When users don't specify preferences, use this complete stack:

- **Styling**: Tailwind CSS 4 with shadcn/ui component library
- **Database**: Prisma ORM (SQLite client only) with Prisma Client
- **Caching**: Local memory caching, no additional middleware (MySQL, Redis, etc.)
- **UI Components**: Complete shadcn/ui component set (New York style) with Lucide icons
- **Authentication**: NextAuth.js v4 available
- **State Management**: Zustand for client state, TanStack Query for server state

Other packages can be found in `package.json`. You can install new packages if needed.

### Library Usage Policy

- **ALWAYS use Next.js 16 and TypeScript** — these are non-negotiable requirements.
- **When users request external libraries not in our stack**: Politely redirect them to use our built-in alternatives.
- **Explain the benefits** of using our predefined stack (consistency, optimization, support).
- **Provide equivalent solutions** using our available libraries.

---

## Prisma and Database

IMPORTANT: `prisma` is already installed and configured. Use it when you need the database.

To use prisma and database:

1. Edit `prisma/schema.prisma` to define the database schema.
2. Run `bun run db:push` to push the schema to the database.
3. Use `import { db } from '@/lib/db'` to get the database client and use it.

---

## Mini Service

You can create mini services if needed (e.g., websocket service). All mini services should be in the `mini-services` folder. For each mini service:

- Must be a new and independent bun project with its own port and `package.json`.
- Must define `index.ts` or `index.js` as the entry file, e.g., `mini-services/chat-service/index.ts`.
- Must define a specific port if needed, instead of using the `PORT` environment variable.
- Must start each mini service by running `bun run dev` in the background.
- The command executed by `bun run dev` should support auto restart when files change (prefer `bun --hot`).
- Make sure every service is started.

---

## Gateway and API Requests

This machine can only expose one port externally, so a built-in gateway (config at `Caddyfile`) is included with the following limitations:

- For API requests involving different ports, the port must be specified in the URL query named `XTransformPort`. Example: `/api/test?XTransformPort=3030`.
- All API requests must use **relative paths only**. Do NOT write absolute paths in the API request URL (including WebSocket). Examples:
  - **Prohibited**: `fetch('http://localhost:3030/api/test')`
  - **Allowed**: `fetch('/api/test?XTransformPort=3030')`
  - **Prohibited**: `io('/:3030')`
  - **Allowed**: `io('/?XTransformPort=3030')`
- When requesting to different services, directly make cross-origin requests without using a proxy.

IMPORTANT: Do NOT write port in the API request URL, even in WebSocket. Only write `XTransformPort` in the URL query.

---

## WebSocket / Socket.io Support

IMPORTANT: Use websocket/socket.io to support real-time communication. Do NOT use any other method. There is already a websocket demo for reference in the `examples` folder.

- Backend logic (via socket.io) must be a new mini service with another port (e.g., 3003).
- Frontend request should ALWAYS be `io("/?XTransformPort={Port}")`, and the path ALWAYS be `/` so that Caddy can forward to the correct port.
- NEVER use `io("http://localhost:{Port}")` or any direct port-based connection.

---

## Code Style

- Prefer to use existing components and hooks.
- TypeScript throughout with strict typing.
- ES6+ import/export syntax.
- shadcn/ui components preferred over custom implementations.
- Use `'use client'` and `'use server'` for client and server side code.
- The Prisma schema primitive type cannot be a list.
- Put the Prisma schema in the `prisma` folder.
- Put the db file in the `db` folder.

---

## Styling

1. Use the shadcn/ui library unless the user specifies otherwise.
2. Avoid using indigo or blue colors unless specified in the user's request.
3. MUST generate responsive designs.
4. The Code Project is rendered on top of a white background. If a different background color is needed, use a wrapper element with a background color Tailwind class.

---

## UI/UX Design Standards

### Visual Design

- **Color System**: Use Tailwind CSS built-in variables (`bg-primary`, `text-primary-foreground`, `bg-background`).
- **Color Restriction**: NO indigo or blue colors unless explicitly requested.
- **Theme Support**: Implement light/dark mode with `next-themes`.
- **Typography**: Consistent hierarchy with proper font weights and sizes.

### Responsive Design (MANDATORY)

- **Mobile-First**: Design for mobile, then enhance for desktop.
- **Breakpoints**: Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`).
- **Touch-Friendly**: Minimum 44px touch targets for interactive elements.

### Layout (MANDATORY)

- **Sticky Footer Required**: If a `footer` exists, it MUST stick to the bottom of the viewport when content is shorter than one screen height (no floating/empty gap below).
- **Natural Push on Overflow**: When content exceeds the viewport height, the footer MUST be pushed down naturally (never overlay or cover content).
- **Recommended Implementation (Tailwind)**: Use a root wrapper with `min-h-screen flex flex-col`, and apply `mt-auto` to the `footer`.
- **Mobile Safe Area**: On devices with safe areas (e.g., iOS), the footer MUST respect bottom safe area insets when applicable.

### Accessibility (MANDATORY)

- **Semantic HTML**: Use `main`, `header`, `nav`, `section`, `article`.
- **ARIA Support**: Proper roles, labels, and descriptions.
- **Screen Readers**: Use `sr-only` class for screen reader content.
- **Alt Text**: Descriptive alt text for all images.
- **Keyboard Navigation**: Ensure all elements are keyboard accessible.

### Interactive Elements

- **Loading States**: Show spinners/skeletons during async operations.
- **Error Handling**: Clear, actionable error messages.
- **Feedback**: Toast notifications for user actions.
- **Animations**: Subtle Framer Motion transitions (hover, focus, page transitions).
- **Hover Effects**: Interactive feedback on all clickable elements.

### Sandbox Preview Instructions (CRITICAL)

This project runs in a restricted cloud sandbox environment.

- **NEVER** instruct the user to visit `http://localhost:3000`, `127.0.0.1`, or any local ports directly. These addresses are internal and not accessible to the user.
- **ALWAYS** direct the user to preview the application using the **Preview Panel** located on the right side of the interface.
- **ALWAYS** inform the user that they can click the **"Open in New Tab"** button above the Preview Panel if they wish to view the application in a separate browser tab.
