Build Guide¶

Fastest local setup¶

From the repo root:

pip install -e ".[dev]"

If you plan to work on the React frontend too:

cd frontend
npm install
npm run build
cd ..

Run the test suite¶

python -m pytest -q

Run a demo app¶

Auth portal:

cd examples/auth_portal
python app.py

Operations + finance portal:

cd examples/operations_finance_portal
python app.py

By default the server uses http://127.0.0.1:8050. To use another port:

# PowerShell
$env:DATABRICKS_APP_PORT=8061
python app.py

Build a publishable package¶

Install the release tools once:

pip install build twine

Then from the repo root:

python -m build
python -m twine check dist/*

If the checks pass, upload to PyPI:

python -m twine upload dist/*

Build the documentation site locally¶

Install docs tooling:

pip install -e ".[docs]"

Run the docs server:

python -m mkdocs serve

Open:

http://127.0.0.1:8000

Build the static docs site:

python -m mkdocs build

If mkdocs serve is not recognized, use the python -m mkdocs ... form above. That runs MkDocs from the same Python environment where the docs extra was installed and avoids PATH issues on Windows.

If Windows reports access denied while cleaning site/, close any process serving the docs and run:

python -m mkdocs build

What needs rebuilding?¶

Python-only changes: reinstall with pip install -e ".[dev]" if needed, then run tests.
Frontend source changes under frontend/src: run npm run build so brickflowui/frontend/dist is updated before publishing.
Docs, examples, and tests: no special build step required.