Zoning Map PoC

This mapping application shows zoning and other related data on a map of NYC. It is intended as a proof of concept for using React, Deck.gl, Chakra, and other related technologies.

Running the project locally

Make sure you're using the correct version of Node

The .nvmrc file tells you which version of node you should be using to run the project. If you're using nvm and already have the correct version installed, you can switch by running nvm use from the root of this repo.

Install dependencies

Once you have cloned this repo, install the necessary dependencies:

npm i

Set up your .env file to point to a running instance of the Zoning API

This project relies on data from a companion PoC API known as the "Zoning API". You will need to set up a .env file pointing to a URL where an instance of the Zoning API is hosted. The easiest way to do this is to clone that repo and run it locally. To do that, follow these steps:

1. Go to the GitHub repo for Zoning API
2. Follow the steps there to clone the project, run the API, and run its database using docker compose
3. Leave that Zoning API and its database running in a separate terminal, and navigate back to where you cloned this repo.
4. Back in your cloned copy of this repo, create a file called .env in the root folder of the project and copy the contents of sample.env into that new file. The default value in sample.env should set the Zoning API URL variable to the correct value for your locally running instance of Zoning API

Run the project

Finally, to run this project locally:

npm run dev

Pulling data from Zoning API

This app relies heavily on data from the Zoning API backend application. It makes use of some front end libraries to make pulling data and managing the state of that data easier:

• Axios - A framework-agnostic HTTP client for javascript and typescript applications
• TanStack Query - This is a general purpose asynchronous state management library for React. You can read more about what problems TanStack Query strives to solve here. It provides useful state management such as caching and managing loading states.
• Kubb - A code generation library that reads OpenAPI specification documents and generates typescript "client" libraries (sometimes also referred to as "SDKs"). It features a set of plugins to generate code for various JS/TS libraries, including Axios and TanStack Query. By pointing Kubb at the OpenAPI document for Zoning API, we can avoid writing a lot of boilerplate code.

Regenerating the Zoning API client code

When the OpenAPI spec file for Zoning API changes, we will need to regenerate the client code in this repo. To do that, simply run npm run generate. Kubb is configured to put all generated code in /src/gen. Note that even though that code is generated, we do want to commit it and includes updates in PRs as necessary. A developer should never make manually changes or additions to code in the /src/gen folder. It should be purely what is outputted by Kubb.

You may see an error in your terminal after running npm run generate referring to the "path" argument being undefined. The root cause of this is still being looked into but it doesn't seem to affect the generated code so you can safely ignore it for now.

Unless you think the contents of the Zoning API OpenAPI spec file have changed since the last time the client code was generated, you can safely skip this step.

Using the Zoning API client code

Once you have this application configured to point to a running instance of Zoning API, you can start to pull in data. To query data from the Zoning API in our React code, we only need to import and call the hooks generated by Kubb. The Providers component makes sure our entire application is wrapped by TanStack Query's QueryClientProvider component, so we should be able to call the hooks within any component. To query data, simply import the hook corresponding to the data you need from the /src/gen folder and call it within your React component.

import { useGetLandUses } from "./gen" // Update relative import path based on your component's file location

// Within your component code
const { isLoading, error, data, isFetching } = useGetLandUses();

In this example, the actual data returned from the API will be on the data property of the object returned by the hook. useGetLandUses is a hook generated by Kubb, but under the hood, it is using TanStack Query's useQuery hook. To learn more about what these hooks return, check out TanStack Query's documentation, particularly these Query Basics