CONTRIBUTING.md

Contributing

These are instructions for getting started on a Mac/unix machine. Windows instructions TBD.

Dependencies

Install these dependencies if you don't already have them:

• git
• A Node version manager, to install the Node version this project targets (Node 24+):
  • Mise
  • Vite+
  • fnm

Download

Clone the source code with HTTP:

git clone https://github.com/APL-Innovation-Lab/meeting-room-prototype

or with SSH:

git clone git@github.com:APL-Innovation-Lab/meeting-room-prototype

Setup

The environment variables this project needs are documented in .env.schema — that file is the source of truth for what you must provide. To set up, copy the template to a local .env and fill it in:

cp .env.example .env

Mapbox access token

You'll need a Mapbox access token for VITE_APP_MAPBOX_TOKEN. Generate your own free one — you don't need to ask anyone for the shared library token. A free Mapbox account is plenty for local development.

VITE_APP_MAPBOX_TOKEN is a public token: mapbox-gl runs in the browser, so the token ships in the client bundle and is visible to anyone who loads the app. That's by design and can't be hidden. What actually protects it is restricting it in the Mapbox dashboard — so create a dedicated, restricted token rather than reusing your account's default one:

1. Sign up for a free Mapbox account (or sign in).

2. Go to your access tokens page and click Create a token.

3. Give it a name (e.g. apl-meeting-room-local). Leave the public scopes at their defaults; you don't need any secret scopes.

4. Under URL restrictions, add http://localhost:5173 (the dev server) so the token only works from your machine. Add your deployment URL too if you're deploying.

5. Click Create token, copy the pk.… value, and paste it into your .env:

   # .env
   VITE_APP_MAPBOX_TOKEN="pk.your_token_here"

If you'd rather use the shared Austin Public Library token instead, ask Mark Malstrom for it in the Open Austin Slack — but generating your own is faster and avoids passing the shared token around.

Varlock validates your .env against the schema automatically when you run the dev server or build. To check it on its own:

npm run env:check

Configuration

install with your toolchain manager (Mise shown here):

cd meeting-room-prototype
mise install

Install NPM dependencies:

npm install

And run the dev server:

node --run dev

Visual Studio Code

It's recommended to use Visual Studio Code as your integrated development environment when working on this prototype for the best development experience. There are several files in this repo's .vscode root-level folder which are intended to enhance this experience with additional settings to make development smooth in VS Code.

Extensions

It's also recommended that you install these extensions for VS Code:

• Oxc for format-on-save (Oxfmt) and lint (Oxlint) support
• TypeScript (Native Preview) for native TypeScript language support
• npm Intellisense for autocomplete in package.json and quick npm script actions in the sidebar
• Tailwind CSS Intellisense for:

Inline color swatches

Hover-on-class style definition expansion

Class name completion

• TODO Highlight for highlighting TODO, FIXME, and MARK comments in code
• Vitest for integrating unit tests into VS Code