# Flask Setup Guide Flask is a lightweight web framework for Python. It lets you build web applications — pages people can visit in a browser, forms they can fill out, and data they can interact with. If you have never built a website before, that is okay. Flask handles the hard parts of web development so you can focus on what your app does. ## Quick Setup If you have not used `uv` before, review the [Packages and uv](/resources/packages.guide) guide first. Open your terminal, navigate to your project folder, and run: ```bash uv init uv add flask ``` Create a file called `app.py`: ```python from flask import Flask app = Flask(__name__) @app.route("/") def home(): return "Hello, world!" ``` Run it: ```bash uv run flask run --debug ``` Open your browser to `http://127.0.0.1:5000` and you should see "Hello, world!" on the page. The `--debug` flag makes Flask reload automatically when you save changes, so you do not need to restart the server every time. Press `Ctrl+C` in your terminal to stop the server. ## How Flask Works Flask connects **URLs** to **Python functions**. When someone visits a URL, Flask runs the matching function and sends the result back to the browser. ```python @app.route("/about") def about(): return "This is the about page." ``` Visit `http://127.0.0.1:5000/about` and you see "This is the about page." Each `@app.route()` is called a **route** — it maps a URL path to a function. ## Adding HTML Templates Returning plain strings gets old fast. Flask uses **templates** (HTML files with placeholders) to build real web pages. Create a `templates/` folder and add a file called `home.html`: ```html {{ title }}

{{ title }}

Welcome to my app!

``` Update `app.py` to use the template: ```python from flask import Flask, render_template app = Flask(__name__) @app.route("/") def home(): return render_template("home.html", title="My App") ``` The `{{ title }}` parts are placeholders that Flask fills in with the values you pass to `render_template()`. ## Recommended Project Structure ``` my-project/ ├── app.py # Your Flask app (routes and views) ├── helpers.py # Your business logic (data processing, etc.) ├── templates/ # HTML templates │ ├── base.html # Shared layout (header, footer, nav) │ ├── home.html │ └── ... ├── static/ # CSS, images, JavaScript │ └── style.css ├── data/ # Data files (CSV, JSON, etc.) ├── pyproject.toml # Dependencies (created by uv) └── README.md ``` Put your routes in `app.py` and your core logic in `helpers.py` (or a separate module). This keeps your code organized and makes it easier for you to explain what you built. ## Project Ideas Here are some ideas that are realistic for a 3-week timeline. Pick one that interests you and scope it down to the simplest version that works. **Campus Event Board** — A page that lists upcoming events. Users can add new events through a form. Store events in a JSON file or simple database. *MVP: one page that lists events, one form that adds them.* **Quiz App** — A web app that presents multiple-choice questions and tracks your score. Load questions from a data file. *MVP: show one question at a time, track right/wrong, show final score.* **Recipe or Bookmark Manager** — Save and organize links or recipes. Add tags or categories. *MVP: a form to add items, a page to list them, and the ability to delete.* **Personal Dashboard** — A single page that pulls together information you care about (weather, to-do list, quotes, class schedule). *MVP: display 2-3 sections with hardcoded or file-based data.* ## Tutorials and Resources - [Flask Quickstart](https://flask.palletsprojects.com/en/stable/quickstart/) — the official first steps guide, covers routes, templates, and the development server - [Flask Official Tutorial](https://flask.palletsprojects.com/en/stable/tutorial/) — builds a complete blog app from scratch with database, auth, and deployment - [DigitalOcean: How To Make a Web Application Using Flask](https://www.digitalocean.com/community/tutorials/how-to-make-a-web-application-using-flask-in-python-3) — beginner-friendly walkthrough with clear explanations - [Real Python: Build a Scalable Flask Web Project](https://realpython.com/flask-project) — covers project layout, templates, blueprints, and static files ## Agent Prompts Use these prompts with your coding agent (Cursor, Claude Code, etc.) to get started. Copy and paste them, then modify to fit your project. **Brainstorm and plan your app:** ```text Read my project.spec.md. I want to build a Flask web app that [describe your idea]. Help me think through the pages I will need, what data the app will store, and what the simplest working version looks like. Ask me questions to narrow it down. ``` **Scaffold your project:** ```text Read my project.spec.md and set up a Flask project based on my plan. Create app.py with the basic routes, a base.html template with a simple layout, and one page template for the home page. Explain each file you create so I understand how they connect. ``` **Learn Flask concepts as you build:** ```text I just added a new route to my Flask app but I do not understand how templates work yet. Look at my app.py and templates/ folder, then explain how render_template connects my Python code to the HTML. Show me how to pass a list of items to a template and loop through them. ``` **Add a form:** ```text I need a page where users can submit data through a form. Look at my app.py and show me how to create a route that handles both GET (show the form) and POST (process the submission) requests. Explain what each part does. Use a simple HTML form — no JavaScript needed. ```