File Structure Overview

Where'd everybody go?

Coming from other programming langauges or more classic JavaScript / HTML + CSS projects, the modular file structure in JavaScript framework-based repositories can be unintuitive. There's some definite advantages here, especially while collaborating with others, and things that appear a more helpful than they first appear, like scoped CSS module. Here's an overview of what's located where.

Root Folder

In the root folder of your WebGeoDa scaffolding, you'll find a number of configuration files, including package.json, which manages the JavaScript package dependencies, meta-information about the project, and map-config.js, which holds your geospatial and tabular data specifications, variable definitions, and a few built-in controls for the interface style. There's also the README, which you may want to customize for your repo, and additional configuration files for Next.js and a few deployment options pre-configured.

Public

Truth in advertising, the public folder holds all of your public facing static assets that won't be bundled together with your WebGeoDa project at build time. Meaning, your data assets (GeoJSONs, CSVs, etc.) live there. Additionally, any images you want to include should be located there, your favicon, and the provided WebGeoDa WebWorker scripts.

Pages

In pages, each JavaScript file, like map.js represents a page path -- eg. yourSite.com/map. index.js represents your homepage, and _app.js is the script that pulls it all together. By adding a new file in pages, you're creating a new Route to the page - read more about how Next.js handles page routing here. Removing a page works the same way, remove that file and the page goes away. By default, you'll have pages for index.js, map.js, and about.js.

In pages you'll also find api, where you can create API endpoints when deploying your WebGeoDa scaffolding on Vercel. This is extremely useful if you want to create a simple data access pipeline right in your project. For more on creating API routes, see making an api.

When adding or removing pages, you'll also want to update the Navigation links. You can find the navigation bar component, MainNav.js located in components > layout. Speaking of which...

Components

The components folder is the home for your JavaScript components, each one a dimutive unit of code that ideally should do a minimal number of things, but do them well. For instance, the Legend component takes a list of colors and labels, then returns a div with those organized in a clear way. Components make life easier by reducing the amount of code you ever need to think about at once.

By default, WebGeoDa scaffolding provides folders for layout and map components. In addition to each JavaScript component, most are paired with a CSS Module (eg. Legend.module.css). This CSS is scoped just for that component, and imported at the top of each one. This allows for fewer concerns about conflicting styles, and the same benefits of a smaller amount of code in any single file. Oh, since it came up...

Styles

The styles folder has a few different CSS files that define the styles for your WebGeoDa scaffolding. Each page, (eg. About, Home) has its own CSS module, just like your JavaScript components. Additionally, global.css has project-wide styles. This stylesheet is particularly useful for handling things like fonts, interactive elements like buttons, and declaring global CSS colors. Additionally, grid.css is borrowed from Kristofer Joseph's excellent Flexbox Grid style package, which enables the simple and easy-to-use grid layouts on pages.

_webgeoda

This folder has all the WebGeoDa guts, including utilities, data store management, custom React Hooks, and so on. In this folder you'll find:

• build-scripts: Build-time scripts for handling a few things, like constructing your cache-management Service Worker

• constants: Default data store parameters

• hooks: Custom hooks that manage interactions between your data, the data store, and jsGeoDa

• reducers: The core function that handles different actions in the data store

• schemas: Built-in Protobuffer Schemas

• utils: A handful of different utilities, including colors.js (built-in color scales), data.js (a handful of data parsing utilities), map.js (some map helper functions), and so on