NiceGUI Project Template

Prerequisites

pipx is used to install tools like copier independent of other tools' or projects' dependencies:

1. install pipx according to the documentation here.
2. install copier with pipx: pipx install copier (tested with copier==9.7.1).
3. it's recommended to use a virtual environment. If you don't have virtualenv installed, install it with: pipx install virtualenv.
4. if you want to use Poetry for managing your project's dependencies, install Poetry: pipx install copier (tested with poetry==2.2.1).

Quickstart

1. generate your project:

copier copy git@github.com:zauberzeug/nicegui-template.git path/to/project

2. explore your new project:

cd path/to/project

3. initialize a git repo:

git init

Now you can connect your local repository to GitHub by creating a new repository. Pay attention to not add a README.md, etc. since your project already has all of this. GitHub then gives you the necessary commands to connect the origin to your local project. Look out for the part "…or push an existing repository from the command line" and run those commands.

4. create a virtual environment:

virtualenv .venv
# add -p $PATH_TO_PYTHON_EXECUTABLE to specify a python version, for example:
virtualenv .venv -p $PYENV_ROOT/versions/3.12.10/bin/python

source .venv/bin/activate # to activate your virtual environment

5. install standard dependencies to start working:

# with Poetry
poetry lock
poetry install --with dev

# without poetry
pip install -r requirements-dev.txt

6. if you added pre-commit in step 1, do:

pre-commit install
git add .
git commit -m "initial commit"

7. start your project:

./main.py

Available Questions / Options

name	type	options	default	explanation
project name	str		-	the project's name as stated in the pyproject.toml
module name	str		same as project name	the name of the main module in the root directory of the project
project description	str		-	used in the pyproject.toml
use poetry	boolean	true / false	false	use Poetry to manage the project's dependencies and virtual environment
python versions	str	3.8 to 3.13	[3.9, 3.10, 3.11, 3.12]	defines the required and supported python versions
use precommit	boolean	true / false	false	use pre-commit to check your changes before committing
use rosys	boolean	true / false	false	add RoSys framework to dependencies
include contributing	boolean	true / false	true	include CONTRIBUTING.md with development guidelines (only asked if AI instructions disabled)
include ai instructions	boolean	true / false	true	include AI agent instructions (AGENT.md, .github/copilot-instructions.md, .cursor/*, CONTRIBUTING.md)

Contributing Guidelines

When include_contributing is enabled (default when AI instructions are disabled), a CONTRIBUTING.md file is generated with:

• Development setup instructions
• Coding style guidelines
• Workflow and testing guidelines
• Pull request checklist

AI Instructions

When include_ai_instructions is enabled (default), the template generates files to help AI coding assistants (GitHub Copilot, Cursor, etc.) understand your project better:

• CONTRIBUTING.md - Development guidelines and coding standards (mandatory, serves as the detailed reference)
• AGENTS.md - Focused AI agent guidelines with principles and AI-specific patterns
• .github/copilot-instructions.md - Brief GitHub Copilot instructions that reference the main files plus detailed review instructions (because it's the most common and straight forward AI review tool when using GitHub)
• .cursor/rules - Brief Cursor AI quick reference
• .cursor/commands/*.md - Custom Cursor commands (review-code, check-style, suggest-tests, explain-code, simplify)

Structure Philosophy: Following the NiceGUI approach, CONTRIBUTING.md contains the comprehensive coding standards and workflow, while AGENTS.md focuses on AI-specific principles. Tool-specific files (.cursor/rules, .github/copilot-instructions.md) are kept brief and reference the main files.