Building PyCharter Package¶

Building the Package with UI¶

To build a package that includes pre-built UI static files (like Airflow):

1. Build the UI First¶

# Build the UI static files (recommended)
pycharter ui build
# or, from the repository root
cd src/pycharter/ui && npm run build

The production build writes to out/; packaging copies that tree to src/pycharter/ui/static/ (see setup.py).

2. Build the Python Package¶

# Build source distribution
python -m build --sdist

# Build wheel
python -m build --wheel

# Or both
python -m build

The custom build commands in setup.py will: - Check if src/pycharter/ui/static/ exists (with index.html) - Run npm run build under src/pycharter/ui/ when needed and copy out/ → static/ - Include static/ in the wheel/sdist per pyproject.toml package data

3. Verify Package Contents¶

# Check what's included
python -m zipfile -l dist/pycharter-*.whl | grep 'pycharter/ui/static'

Installation After Building¶

Users who install from the built package:

pip install dist/pycharter-*.whl
pycharter ui serve  # Works immediately!

The static files are included in the package, so no build step is needed.

Development vs Production¶

Development (Source)¶

UI source files in src/pycharter/ui/src/
Run pycharter ui dev for hot reload
No static files needed

Production (Package)¶

Pre-built static files in src/pycharter/ui/static/
Included in Python package
Served via pycharter ui serve
No npm/node required for end users

CI/CD Integration¶

For automated builds, add to your CI:

# Example GitHub Actions
- name: Install Node.js
  uses: actions/setup-node@v3
  with:
    node-version: '18'

- name: Build UI
  run: |
    cd src/pycharter/ui
    npm ci
    npm run build

- name: Build Python package
  run: python -m build

Troubleshooting¶

"UI static files not found" after installation¶

Cause: Package was built without UI static files.

Solution: 1. Build UI: pycharter ui build 2. Rebuild package: python -m build 3. Reinstall: pip install --force-reinstall dist/pycharter-*.whl

Build fails with "npm not found"¶

Cause: Node.js not installed in build environment.

Solution: Install Node.js or build UI separately before packaging.