Contributing

Thank you for your interest in contributing to Spatial.Properties. This guide covers development setup for the three main projects and explains the standard contribution workflow.

Development setup

CLI (Python)

The spatialpack CLI is the core tool for building, validating, and managing Spatial Packs.

Requirements: Python 3.11+, pip

# Clone the repository
git clone https://github.com/spatial-properties/spatial.properties.git
cd spatial.properties

# Install the CLI in development mode with all extras
cd cli
pip install -e ".[full,dev]"

# Verify the install
spatialpack --help

# Run the test suite
pytest

The [full] extras install GDAL, GeoPandas, and other optional dependencies. The [dev] extras install pytest and development tools. If you are only working on a specific feature, you can install the base package without [full] and add dependencies as needed.

Frontend (Viewer)

The web viewer is a React + TypeScript application built with Vite, using Kepler.GL for map visualization.

Requirements: Node.js 18+, npm

cd kepler-gl-vis
npm install
npm run dev

The development server starts at http://localhost:5173. You need a MapboxAccessToken environment variable for the map to render:

export MapboxAccessToken=pk.your-mapbox-token-here

Documentation site

The docs site is built with Astro Starlight and deployed to docs.spatial.properties.

Requirements: Node.js 18+, npm

cd docs-site
npm install
npm run dev

The development server starts at http://localhost:4321 with hot reload. Run npm run build to verify the production build passes, including the banned-pattern checker.

Other projects

The repository contains additional projects with their own setup requirements:

• Backend (backend/) — FastAPI Python application with Supabase integration
• Landing page (landing/) — Next.js 14 marketing site
• Infrastructure (infra/) — Terraform configurations for AWS deployment

These projects have their own setup instructions in their respective directories.

Workflow

Spatial.Properties follows a standard fork-and-pull-request workflow.

1. Fork the repository on GitHub.
2. Clone your fork locally.
3. Create a branch for your changes:

   git checkout -b feature/my-improvement

4. Make your changes and write tests where applicable.
5. Run the test suite for the project you modified (see Running Tests below).
6. Commit with a descriptive message:

   git commit -m "feat(cli): add support for GML input format"

7. Push to your fork and open a pull request against master.

The project uses structured GSD phases for internal planning, but external contributors follow the standard PR workflow described above.

Code style

Each project has its own conventions documented in a CLAUDE.md file at the project root. These files serve as the coding style reference for both human and AI contributors:

• CLI: cli/CLAUDE.md — Python conventions, Click patterns, CRS handling
• Frontend: Root CLAUDE.md — React/TypeScript conventions, Kepler.GL integration patterns
• Documentation: docs-site/CLAUDE.md — Writing style, terminology, page structure rules

Running tests

CLI

cd cli
pytest

Run a specific test file:

pytest tests/test_pipeline.py -v

Frontend

cd kepler-gl-vis
npm test

Documentation site

The docs site does not have unit tests. The build itself is the test — it validates content structure, component imports, and banned patterns:

cd docs-site
npm run build

A successful build confirms all pages render, all imports resolve, and no banned content patterns are present.