nextjs-fastapi-dev-container

A minimal, batteries-included dev container for building full-stack apps with Next.js and FastAPI—no local setup required.

---

✨ Features

• ⚡️ Fast tooling via Bun and uv
• 🧠 Linting with ESLint and ruff
• 🎨 Formatting with Prettier and ruff
• 🔍 Static type checking with TypeScript and ty
• 🪝 Automatic checks via pre-commit hooks
• 🛠️ Simple developer workflow via Makefile
• 🐳 Docker-in-Docker support
• 🔁 Persistent shell history across container rebuilds

---

🚀 Getting Started

🚨 Prerequisites

Make sure you have the following dependencies installed:

• Docker
• VS Code with the "Dev Containers" extension

Note: This dev container is made specifically for VS Code, but it should work with any IDE that has a "Dev Containers" plugin.

📦 Setup

1. Clone the repo

git clone https://github.com/rdguzman-swe/fastapi-nextjs-dev-container.git <your-project>

2. Open in VS Code

code <your-project>

3. Reopen in container

   • Cmd/Ctrl + Shift + P
   • Select Dev Containers: Reopen in Container

4. Initialize project

make init

This will scaffold the backend and frontend and install all dependencies.

📌 Usage

Start/open dev container

• Cmd/Ctrl + Shift + P
• Select Dev Containers: Reopen in Container

Stop/close dev container

• Cmd/Ctrl + Shift + P
• Select Dev Containers: Reopen Folder Locally

---

📁 Project Structure

.
├── .devcontainer/           # Dev container config
├── backend/                 # FastAPI app (created on scaffold)
├── frontend/                # Next.js app (created on scaffold)
├── .gitignore
├── .pre-commit-config.yaml  # pre-commit hooks
├── .python-version
├── LICENSE.txt
├── Makefile                 # Developer commands
└── README.md

---

🛠️ Developer Commands

Run make help to see a list of all available commands:

make help

Command	Description
make init	Full setup (scaffold + install)
make scaffold	Create backend & frontend if missing
make frontend	Run Next.js dev server (http://localhost:3000)
make backend	Run FastAPI server (http://localhost:8000)
make post-create	Re-run container setup script

---

🪝 Pre-commit Hooks

This dev container includes pre-commit hooks to automatically run checks before each commit:

Hook	Role
eslint	TypeScript linting
prettier	TypeScript formatting
ruff-check	Python linting
ruff-format	Python formatting
ty	Python type checking

Hooks are automatically installed when the dev container is created.

---

⚙️ Dev Container Details

This dev container is based on Debian 12 and comes with the following tools and VS Code extensions.

⚒️ Preinstalled Tools

• Zsh (Z shell)
• Oh My Zsh!
• Git
• curl
• Bun
• uv
• Python

🧩 VS Code Extensions

• Tailwind CSS
• ESLint
• Prettier
• Python
• Pylance
• Ruff
• ty
• Docker

---

🐍 Python Version

The default Python version for this dev container is Python 3.13. To use a different version, modify the .python-version file as follows:

3.13 -> <your-version>

Make sure to rebuild the dev container to see the changes.

---

📄 License

This project is licensed under the MIT License.