code/skills/builtins/fullstack-scaffold/SKILL.md

metadata

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`)