Skip to content

Quick Start

You need Node 24 or newer (see Requirements). The runnable app lives in the app/ folder. Clone only 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 ci
npm run dev

Vite prints a local URL (http://localhost:5173 by default). Open it to see the demo app.

The sparse checkout 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.md always come along.

  • App only: 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.

Projects

Each app you build is a project: a folder in app/projects/ with its own settings, layers, data and images. One install can hold as many as you like. The kit comes with one, app/projects/demo/.

Create your own with a display name:

npm run new "City Parcels"
npm run dev city-parcels

npm run new copies the starter template (app/templates/basic/) into app/projects/city-parcels/, and sets the project's title and storage id (branding.title, branding.appId) from the name. If the folder exists, it adds -2, -3, and so on. The starter has every basemap, the standard popups, no layers, a short info page, the default logo, and Layers, Legend and Basemap in the side panel.

Commands that work on a project take its folder name. Without one, they use the only project; with several, they stop and list them; with none, they tell you to run npm run new.

npm scripts

Run these from inside app/:

Script What it does
npm run new "My Map" Create a project from the starter template
npm run dev [project] Start the Vite dev server with hot reload
npm run build [project] Type-check and build the project into app/dist/<project>/. It ends with a size report: the total, how much of it is your layer files, the app's code (with its gzipped size), and other files such as basemap thumbnails. Then the API key check runs. Only the widgets the project places are bundled
npm run preview [project] Serve the built project locally (correct MIME types and webroot)
npm run typecheck Type-check the kit and every project
npm run lint Run ESLint
npm run test Run the tests (Node's built-in runner, no extra install)

Where to edit

Everything you customize lives in your project's folder, app/projects/<project>/:

File Purpose
settings.json The main config: branding, map, UI, widget settings and placement, commercial use
theme.json Colors: a preset plus per-token overrides
layers.json Your data layers
layers/ Your data files
basemaps.json The basemaps users can switch between
symbology.json Reusable named symbology
popups.tsx Popup templates (React components)
info.md The "About this app" modal content
public/ Logo, favicon and other files served as-is

The five .json files are plain JSON (no comments). In npm run dev, saving one reloads the page, and a mistake in any of them (a typo in a key, a wrong value) is reported in the terminal and over the page with the file and the exact spot; see Concepts. Widgets live in app/widgets/ and are shared by every project; each project places the ones it uses. You should rarely need to touch app/src/, which is the shell. See Concepts for where the line falls.

Tip

Hover any setting in VS Code to see what it does, its default and a link to its docs page. Autocomplete lists the keys and values a spot takes.

Starting from a clean slate

A clean slate is a new project: npm run new "My Map". It opens on an empty map with Layers, Legend and Basemap in the side panel, and the Layers panel reads "No layers yet. Add your data in your project's layers.json." The demo stays as it is, as a reference for every layer type and widget.

Then, in your project's folder:

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

Make it your own repo

Your clone's origin still points at the kit's repository, and you can't push there. Pick one of these to give your commits a home.

Create an empty repository on GitHub, with 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. If you delete them, every later git pull upstream main that touches them will 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 see how the pieces connect.