Skip to content

Quick Start

Get a themed, data-rich map running locally in a couple of minutes.

Prerequisites

  • Node.js 20 or newer (ships with npm)
  • Git

Run it

The entire runnable app lives in the app/ subdirectory. Clone the repo, then work inside app/:

git clone https://github.com/ericsamsoncarto/conness-gis.git
cd conness-gis/app
npm install
npm run dev

Vite prints a local URL (default http://localhost:5173). Open it and you'll see the demo app: a globe-projected world map, a layer list and legend on the left, draw/measure/bookmark tools in the top bar, and a search box floating over the map.

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

Opening dist/index.html directly won't work

The build uses ES modules, which browsers block over file://. To preview a build, use npm run preview (not a double-click). To deploy, point a static host (Cloudflare Pages, Netlify, GitHub Pages) at app/dist/ with build command cd app && npm install && npm run build.

Where to edit

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

File Purpose
app/settings.ts The main config: branding, theme, map, basemaps, UI, widget placement
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 data layers so you can see every feature working. When you're ready to build your own app:

  1. Empty the layers. Open app/layers.ts and replace the layers array with [] (or just your own entries). The map will render with no overlays — no errors.
  2. Trim the widget placements. In app/settings.ts, remove any widget from topBarWidgets / leftPanelWidgets / floatingWidgets you don't want.
  3. Rebrand. Set branding.title, branding.logo, and the color tokens (see Branding & Theme).
  4. Point the map somewhere. Update map.center and map.zoom.

That's it — there's no separate "blank" template to clone. One repo, and you delete what you don't need.

Next: read Concepts to understand how the pieces connect.