fullstack-dev

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:

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.