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
pycharter ui build
# or
cd ui && npm run build

This creates ui/static/ with all the built files.

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 ui/static/ exists - Build the UI if needed (if node_modules exists) - Include static files in the package

3. Verify Package Contents¶

# Check what's included
python -m zipfile -l dist/pycharter-*.whl | grep 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 ui/src/
Run pycharter ui dev for hot reload
No static files needed

Production (Package)¶

Pre-built static files in 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 ui
    npm install
    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.