Skip to content

Quick Start

The entire runnable app lives in the app/ subdirectory. Clone just what you need with a sparse checkout (Git 2.27+), then work inside app/:

git clone --filter=blob:none --sparse https://github.com/ericsamsoncarto/conness-gis.git
cd conness-gis
git sparse-checkout set app convert-data-python
cd app
npm install
npm run dev

Vite prints a local URL (default http://localhost:5173). Open it and you'll see the demo app!

This skips the docs and planning folders but keeps the full git history, so you can still pull updates. Root files like README.md and LICENSE always come along.

  • App only — use git sparse-checkout set app if you don't need convert-data-python/.
  • Everything — a plain git clone https://github.com/ericsamsoncarto/conness-gis.git works too.

npm scripts

All scripts run from inside app/:

Script What it does
npm run dev Start the Vite dev server with hot reload
npm run build Type-check and build a production bundle into app/dist/
npm run preview Serve the built dist/ locally (correct MIME types + webroot)
npm run typecheck Type-check without emitting
npm run lint Run ESLint
npm run reset Strip the demo down to a blank app (see below)

Where to edit

Everything you customize lives at the root of app/ — the user surface:

File Purpose
app/settings.ts The main config: branding, map, basemaps, UI, widget placement
app/theme.ts Colors: a preset plus per-token overrides
app/layers.ts Your data layers
app/symbology.ts Reusable named symbology
app/popups.tsx Popup templates (React components)
app/info.md The "About this app" modal content
app/widgets/ Your custom widgets

You should rarely need to touch anything under app/src/ — that's the shell. See Concepts for the boundary.

Starting from a clean slate

The demo ships with ~10 example layers and most widgets turned on. When you're ready to build your own app, run this once on a fresh clone:

npm run reset

It lists every change and asks before doing anything (npm run reset -- --yes skips the prompt).

Removed Kept
All data files in app/layers/ Branding, app/theme.ts, map view, basemaps
All layers in layers.ts (a commented example is left) UI settings, popups, context menu
Named styles in symbology.ts The search geocoder (just unplaced)
Search layers, top-bar widgets, floating widgets, legend Layer list + basemap in the side panel
Geolocate + terrain controls Zoom/compass + globe controls

Warning

This deletes the demo data and can't be undone except through git.

After a reset, npm run dev opens an empty map with Layers and Basemap in the side panel, and the Layers panel reads "No layers yet. Add your data in app/layers.ts." If your clone's git origin still points at the kit repo, reset also prints a heads-up pointing to Make it your own repo below.

Then:

  1. Rebrand. Set branding.title and branding.logo in app/settings.ts (see Branding), and pick a color preset or tweak tokens in app/theme.ts (see Theme).
  2. Point the map somewhere. Update map.center and map.zoom.
  3. Add your data. Drop files in app/layers/ and add entries to app/layers.ts (see Adding Layers). Add widgets back as you need them.

Make it your own repo

Your clone's git origin still points at the kit's repository, and you can't push there. Give your commits a home of your own — pick one:

Create an empty repository on GitHub (no README, license, or .gitignore, so the first push doesn't conflict), then from your clone:

git remote rename origin upstream
git remote add origin https://github.com/<you>/<your-app>.git
git push -u origin main

Your clone keeps its sparse checkout, and you can pull kit updates any time with:

git pull upstream main

Your new repo also contains the kit's docs/ and plans/ folders — the sparse checkout only hides them on disk. Leave them in place: deleting them makes every future git pull upstream main that touches them conflict.

Option B — one-click copy

Click Use this template on the kit's GitHub page to create your own repository, then clone that. It's the simplest route, but it copies the whole repo (no sparse checkout) and starts with fresh history, so you can't pull kit updates later.

Contributing back to the kit

Both options are for building your own app. To contribute a fix or feature to Conness GIS itself, fork the kit's repository on GitHub and open a pull request from your fork.

Next: read Concepts to understand how the pieces connect.