Mobility Feeds API UI
This project is built with Next.js using the App Router.
Using node v24.12.0 (npm v11.6.2) (yarn v1.22.22)
Installing packages
It is preferred to install the packages using yarn over npm install
Configuration variables
Next.js can inject all necessary environment variables into the application in development mode and the JS bundle files.
Steps to set environment variables:
- Create a file based on
.env.rename_me with the name .env.development (for dev) or .env (for prod)
- Replace all key values with the desired content.
- Done! You can now start or build the application with the commands described below.
Adding a new environment variable
To add a new environment variable, add the variable name to the .env.{environment} and modify the GitHub actions injecting the value per environment. When adding a new variable, make sure that the variable name is prefixed with NEXT_PUBLIC_ for client-side usage; otherwise, the Next.js app will not read the variable on the client side.
Available Scripts
In the project directory, you can run:
- Runs the app in the development mode:
It will automatically use environment variables located in
.env.development
- Running a production build
It will build then run the application in production and serve it locally using environment variables located in
.env
Since it uses the files from the build, it will not hot reload
Open http://localhost:3000 to view it in the browser.
The page will reload if you make edits.
You will also see any lint errors in the console.
- Launches the test runner in the interactive watch mode:
- Builds the app for production:
It bundles the application in production mode using Next.js optimization.
The build is optimized and ready for deployment.
- Start the production build locally:
Executes linter on sources to review warnings and errors
Firebase integration
This application is powered by Firebase.
To access Firebase commands and features you need to create your own firebase project. Only MobilityData internal engineers have access to MobilityData's firebase projects
Firebase useful commands
npx firebase use {project_name_or_alias}
- Deploy to a
preview channel
npx firebase hosting:channel:deploy {channel_name}
Firebase Remote Configs
Firebase remote configs help us toggle new features on and off. Due to the nature of static pages, there are some nuances. For static pages, the remote configs are called and set at build time and will be the same for the remainder of the static page's cache.
When remote configs change (they rarely do), manually purge the remote-config cache tag in the Vercel dashboard (Storage -> Data Cache) after publishing the change. Redeploying the app is not sufficient on its own — Vercel's Data Cache persists across deployments, so a fresh deployment can still serve the stale remote config value.
Note: purging the remote-config tag also invalidates every static and ISR page site-wide, not just feed pages. The remote config is fetched in the root layout, which every page shares, so purging that one tag marks every statically-generated page for regeneration on its next visit.
What this also means is that client components will be able to access the firebase remote configs using the Context but server components will have to fetch them each time. This isn't a big deal as the firebase remote configs are cached (for 1 hour on the server)
Component and E2E tests
Component and E2E tests are executed with Cypress. Cypress tests are located in the cypress folder.
Cypress useful commands:
- E2E tests require a mock server to run to mock api endpoints
Will start the dev environment with mock server. It's equal to running
yarn run firebase:auth:emulator:dev + yarn run start:dev:mock"
In a different terminal,
- Opens Cypress in the interactive GUI
Git Worktrees
The project includes scripts to manage Git worktrees, allowing you to work on multiple branches simultaneously in separate directories without stashing or switching branches.
Create a new worktree
yarn new-worktree feat/my-feature
This will:
- Create a new branch (
feat/my-feature) and check it out in a sibling directory named wt-feat-my-feature
- Copy
.vscode settings and all .env* files from the main repo
- Hard-link
node_modules from the main repo (fast, minimal extra disk usage) — or run yarn install if none exist
- Open the new worktree in a new VS Code window
If the new branch changes package.json dependencies, run yarn install inside the worktree directory to reconcile.
Remove a worktree
yarn remove-worktree feat/my-feature
This will remove the worktree directory and delete the local branch. The branch must be fully merged before deletion (uses git branch -d).
API Types Generation
The project includes scripts for generating TypeScript types from OpenAPI specifications:
- Generate API types from main database catalog:
- Generate GBFS validator types:
yarn generate:gbfs-validator-types
References