{"id":36956598,"url":"https://github.com/jaehyeon-kim/nicegui-fastapi-template","last_synced_at":"2026-01-13T14:01:32.100Z","repository":{"id":324462676,"uuid":"1095427306","full_name":"jaehyeon-kim/nicegui-fastapi-template","owner":"jaehyeon-kim","description":"A template for rapidly building full-stack web applications in Python, featuring a FastAPI backend, a NiceGUI frontend, PostgreSQL, and Docker.","archived":false,"fork":false,"pushed_at":"2025-12-11T21:22:18.000Z","size":2579,"stargazers_count":79,"open_issues_count":0,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-13T02:03:58.554Z","etag":null,"topics":["docker","fastapi","full-stack","jwt-authentication","nicegui","postgresql","python","template","web-application"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jaehyeon-kim.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-13T03:18:54.000Z","updated_at":"2025-12-12T18:24:26.000Z","dependencies_parsed_at":"2025-12-13T04:00:36.343Z","dependency_job_id":null,"html_url":"https://github.com/jaehyeon-kim/nicegui-fastapi-template","commit_stats":null,"previous_names":["jaehyeon-kim/nicegui-fastapi-demo","jaehyeon-kim/nicegui-fastapi-template"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/jaehyeon-kim/nicegui-fastapi-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaehyeon-kim%2Fnicegui-fastapi-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaehyeon-kim%2Fnicegui-fastapi-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaehyeon-kim%2Fnicegui-fastapi-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaehyeon-kim%2Fnicegui-fastapi-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaehyeon-kim","download_url":"https://codeload.github.com/jaehyeon-kim/nicegui-fastapi-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaehyeon-kim%2Fnicegui-fastapi-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28387596,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T13:42:20.960Z","status":"ssl_error","status_checked_at":"2026-01-13T13:42:03.276Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fastapi","full-stack","jwt-authentication","nicegui","postgresql","python","template","web-application"],"created_at":"2026-01-13T14:01:31.035Z","updated_at":"2026-01-13T14:01:32.089Z","avatar_url":"https://github.com/jaehyeon-kim.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FastAPI and NiceGUI Full-Stack Template\n\nThis repository provides a template for building full-stack web applications using **FastAPI** for the backend and **NiceGUI** for the frontend. It includes a complete setup for a PostgreSQL database, JWT authentication, and a clean project structure, making it an excellent starting point for demos, prototypes, and internal tools.\n\n## Why FastAPI and NiceGUI?\n\nCombining FastAPI and NiceGUI allows for the rapid development of web applications entirely in Python, which is a significant advantage for teams that want to avoid switching contexts between Python for the backend and JavaScript for the frontend.\n\n- **FastAPI** is a modern, high-performance web framework for building APIs. It offers automatic interactive documentation, data validation powered by Pydantic, and an intuitive syntax that accelerates development.\n\n- **NiceGUI** is a user-friendly, Python-based UI framework. It allows you to build web frontends without writing any HTML, CSS, or JavaScript. This is ideal for backend developers, data engineers, data scientists, and anyone who needs to create an interactive UI quickly.\n\nThis combination is perfect for **demo applications** because it enables a single developer to build and showcase a complete, interactive, and robust full-stack application in a fraction of the time it would take with traditional frameworks.\n\n## Features\n\n- **Modern Backend**: A robust backend powered by FastAPI.\n- **Interactive Frontend**: A simple and clean UI built with NiceGUI.\n- **Database Integration**: PostgreSQL database managed with Docker and accessed using SQLModel.\n- **Authentication**: JWT token-based security for API endpoints.\n- **Project Structure**: A clear separation between backend and frontend source code.\n- **Automatic API Docs**: Interactive API documentation available out-of-the-box.\n- **Containerized DB**: Easy-to-manage PostgreSQL instance running in Docker.\n\n💡 **Version 2.0: Unified Application Architecture**\n\nThe initial version was designed with a distinct separation between a FastAPI backend and a NiceGUI frontend, which communicated over HTTP. This new version consolidates the application, leveraging the fact that NiceGUI is built on top of FastAPI. The result is a more tightly integrated structure that allows the UI and API logic to coexist in the same process.\n\n**Key Architectural Changes:**\n\n- **Single FastAPI Instance:** The separate FastAPI server process has been removed. The application now operates on the single FastAPI instance provided by `nicegui.app`.\n- **Direct Function Calls:** UI event handlers no longer make HTTP requests (`httpx`) to the backend. They now import and call the necessary Python functions from the repository layer directly, removing the network layer for UI-to-backend communication.\n- **Preserved API Endpoints:** The original API, intended for external clients, is maintained. It is mounted using FastAPI's `APIRouter` onto the main NiceGUI application, ensuring that JSON endpoints remain available.\n- **Consolidated Codebase:** The `frontend` and `backend` directories have been merged into a single application package (e.g., `app` or `src`). A `run.py` script at the project root now serves as the single entry point.\n- **Shared Logic:** Business logic, such as permission checks and database operations, has been centralized in the repository layer, where it is called by both the UI event handlers and the API endpoints.\n\nThis updated architecture provides a more direct and cohesive way to build full-stack applications where the UI and backend logic are tightly coupled.\n\n## Getting Started\n\nFollow these instructions to get the project running on your local machine.\n\n### Prerequisites\n\n- Python 3.10+\n- Docker and Docker Compose\n- Git\n\n### Setup Instructions\n\n1.  **Clone the Repository**\n\n    ```bash\n    git clone https://github.com/jaehyeon-kim/nicegui-fastapi-template.git\n    cd nicegui-fastapi-demo\n    ```\n\n2.  **Create a Virtual Environment and Install Dependencies**\n\n    Choose one of the following methods:\n\n    #### Option A: Using `uv`\n\n    a. **Install `uv` (if you haven't already)**\n\n    ```bash\n    # On macOS/Linux\n    curl -LsSf https://astral.sh/uv/install.sh | sh\n\n    # On Windows\n    irm https://astral.sh/uv/install.ps1 | iex\n    ```\n\n    b. **Create and Activate a Virtual Environment**\n\n    ```bash\n    # Create the virtual environment\n    uv venv venv\n\n    # Activate it (on macOS/Linux)\n    source venv/bin/activate\n\n    # Or activate it (on Windows)\n    venv\\Scripts\\activate\n    ```\n\n    c. **Install Dependencies**\n\n    ```bash\n    uv pip install -r requirements.txt\n    ```\n\n    #### Option B: Using `pip`\n\n    a. **Create and Activate a Virtual Environment**\n\n    ```bash\n    # Create the virtual environment\n    python -m venv venv\n\n    # Activate it (on macOS/Linux)\n    source venv/bin/activate\n\n    # Or activate it (on Windows)\n    .\\venv\\Scripts\\activate\n    ```\n\n    b. **Install Dependencies**\n\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n3.  **Configure Environment Variables**\n\n    Create a `.env` file in the project root by copying the example file.\n\n    ```bash\n    cp .env.example .env\n    ```\n\n    You can modify the `.env` file if needed, but the default values are configured to work with the Docker Compose setup.\n\n4.  **Start the PostgreSQL Database**\n\n    Run the following command to start the PostgreSQL database container in the background.\n\n    ```bash\n    docker-compose up -d\n    ```\n\n5.  **Run the Application**\n    Start the development server by executing the `app.py` script directly from your terminal.\n\n    ```bash\n    python app.py\n    ```\n\n    This command calls the `ui.run()` function at the bottom of the script, which starts the web server. Because the `reload=True` parameter is used, the server will automatically restart whenever you make code changes.\n\n### Accessing the Application\n\nOnce the server is running, you can access the following URLs:\n\n**Application Frontend**: [http://localhost:8000](http://localhost:8000)\n\n- The main user interface built with NiceGUI.\n\n![](./images/demo.gif)\n\n**API Docs (Swagger UI)**: [http://localhost:8000/docs](http://localhost:8000/docs)\n\n- Interact with and test the API endpoints directly from your browser.\n\n![](./images/docs.png)\n\n**Alternate API Docs (ReDoc)**: [http://localhost:8000/redoc](http://localhost:8000/redoc)\n\n- View a clean and concise API documentation.\n\n![](./images/redoc.png)\n\n### Stopping and Cleaning Up\n\nWhen you are finished, you can stop the services and clean up the environment.\n\n1.  **Stop the Uvicorn Server**\n    Press `Ctrl+C` in the terminal where the application is running.\n\n2.  **Stop the Database Container**\n    To stop the PostgreSQL container, run:\n\n    ```bash\n    docker-compose down\n    ```\n\n3.  **Deactivate the Virtual Environment**\n    ```bash\n    deactivate\n    ```\n\n## License\n\nThis project is licensed under the MIT License. See the `LICENSE` file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaehyeon-kim%2Fnicegui-fastapi-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaehyeon-kim%2Fnicegui-fastapi-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaehyeon-kim%2Fnicegui-fastapi-template/lists"}