---
name: fullstack-scaffold
description: Scaffold complete fullstack projects with proper structure. Generates package.json, requirements.txt, Dockerfiles, and config files for any framework.
language: any
tags: scaffold, fullstack, project, structure, framework
---
# Fullstack Project Scaffolding

When generating a fullstack application, always produce a complete, runnable project — not just snippets.

## Project structure rules

### Python (Flask/FastAPI/Django/Streamlit/Gradio)
```
project-name/
├── app.py              # Entry point (HF Spaces expects app.py)
├── requirements.txt    # Pinned dependencies
├── README.md           # With HF Space frontmatter if deploying
├── .env.example        # Document required env vars
├── src/
│   ├── __init__.py
│   ├── routes/         # API routes
│   ├── models/         # Data models
│   ├── services/       # Business logic
│   └── utils/          # Helpers
├── tests/
│   └── test_app.py
└── static/             # Static assets (if web framework)
```

### Next.js / React (Vite)
```
project-name/
├── package.json        # name, version, scripts, deps
├── next.config.js      # (Next.js only) output: 'standalone'
├── vite.config.js      # (Vite only)
├── tsconfig.json       # (TypeScript)
├── Dockerfile          # Multi-stage build for HF Spaces
├── .dockerignore
├── README.md
├── public/
│   └── (static assets)
└── src/
    ├── app/            # Next.js App Router
    ├── pages/          # Next.js Pages Router (legacy)
    ├── components/     # Reusable components
    ├── lib/            # Utilities, helpers
    ├── hooks/          # Custom hooks
    ├── styles/         # Global CSS
    └── types/          # TypeScript types
```

### Express / NestJS
```
project-name/
├── package.json
├── Dockerfile
├── .dockerignore
├── README.md
├── src/
│   ├── index.js        # Entry — app.listen(7860, '0.0.0.0')
│   ├── routes/
│   ├── middleware/
│   ├── controllers/    # NestJS only
│   ├── services/
│   └── models/
└── tests/
```

## Port and host rules (critical for HF Spaces)

- All servers MUST listen on `0.0.0.0` (not `localhost` or `127.0.0.1`)
- All servers MUST use port `7860` (HF Spaces default)
- For sub-servers (Gradio subprocess), use 7861, 7862, etc.

## Dockerfile rules

For JS/TS projects, generate a Dockerfile:
- Use `node:20-slim` as base
- Multi-stage build: deps → builder → runner
- For SPAs (React/Vue), serve with nginx on port 7860
- For Next.js, use `output: 'standalone'` and copy `.next/standalone`
- Run as non-root user

For Python projects, the HF Space SDK auto-generates the runtime — no Dockerfile needed unless using Docker SDK.

## package.json rules

- Always include `name`, `version`, `private: true`
- Scripts: `dev`, `build`, `start` (start must bind 0.0.0.0:7860)
- Pin major versions: `"react": "^18.3.0"` not `"react": "latest"`
- Dev dependencies: TypeScript, types, build tools, linters
- Production dependencies: runtime libraries only

## requirements.txt rules

- Pin with `>=` to allow patch updates: `flask>=3.0.0`
- Group by category (web, db, ml, dev) with comments
- Always include the framework (flask, fastapi, gradio, etc.)
- Never include stdlib modules

## README.md rules

For HF Spaces, include frontmatter:
```yaml
---
title: App Name
emoji: 🚀
colorFrom: blue
colorTo: purple
sdk: gradio  # or docker, static, streamlit
app_file: app.py  # or index.html, Dockerfile
pinned: false
---
```

## Don't include

- `node_modules/`
- `.next/` (build output)
- `__pycache__/`
- `.venv/`, `venv/`
- Lock files (let HF install fresh)
- `.env` (only `.env.example`)