Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/V3RNE42/helios/llms.txt

Use this file to discover all available pages before exploring further.

Helios is not a purely static application. The browser calls two same-origin endpoints — /api/geocode and /api/timezone — which are Vercel serverless functions that hold your third-party API keys and proxy requests to geocoding and timezone providers. Because of this, you must serve the project with vercel dev rather than a plain static server. Running python -m http.server or opening index.html directly will serve the HTML and JavaScript, but any attempt to resolve a city name or fetch a UTC offset will fail with a 404.
The front-end must be served over HTTP, not opened as a file:// URL. index_def.js is loaded as a native ES module (<script type="module">), and browsers block ES module imports from file:// origins. Always use vercel dev (or any HTTP server that also handles the /api routes).

​
Prerequisites

  • Node.js 24.x — required by the engines field in package.json.
  • Vercel CLI — install globally with npm install -g vercel if you do not have it already.
  • API keys for the three providers listed in step 3.

​
Steps

1

Clone the repository

Clone the Helios repository from GitHub and move into the project directory:
git clone https://github.com/V3RNE42/helios.git && cd helios
2

Install dependencies

Helios has a single development dependency — Vitest for unit tests. Install it with:
npm install
There are no runtime npm dependencies; all other libraries (SunCalc, Spin.js, jsPDF, html2canvas) are loaded from CDN or bundled directly in the repository.
3

Copy the environment template

Copy the provided environment template to a local .env file:
cp .env.example .env
Then open .env and fill in the three API keys. The file looks like this:
# Copy to .env for local `vercel dev`, and set the same values as
# Environment Variables in the Vercel project dashboard for production.
# The previous keys were committed to git history and should be rotated.

# https://opencagedata.com/  — geocoding fallback (api/geocode.js)
OPENCAGE_KEY=

# https://ipgeolocation.io/  — timezone lookup (api/timezone.js)
IPGEOLOCATION_KEY=

# https://timezonedb.com/    — timezone fallback (api/timezone.js)
TIMEZONEDB_KEY=
All three keys are required for full functionality. See the table in the Deployment page for links to each provider’s sign-up page.
Running npm test (Vitest) does not require any API keys. The test suite only exercises computeRouteSections in routeSolar.js, which is a pure function with no network calls or DOM dependencies.
4

Start the development server

Start the Vercel development server:
vercel dev
vercel dev does two things simultaneously: it serves the static front-end files (index.html, index_def.js, CSS, etc.) and it spins up the /api/geocode and /api/timezone serverless functions locally — reading the keys from your .env file. Both the UI and the API run on the same origin, so there are no CORS issues.You will be prompted to link the project to a Vercel account on first run. You can link it to an existing project or create a new one; either way, the local dev server works the same.
5

Open the app

Navigate to http://localhost:3000 in your browser. You will see the Helios wizard:
  1. Preferences — choose sun or shade, whether you can switch seats, and whether to display results in local time.
  2. Origin — enter your departure city, country, date, and time.
  3. Destination — enter your arrival city, country, date, and time.
Click Submit. Helios will geocode both cities via /api/geocode, fetch UTC offsets via /api/timezone, compute solar events along the route, and display your seat recommendation — left or right — for each segment of the journey.

​
Running the tests

To run the unit test suite without a server or API keys: 
npm test
Vitest will execute routeSolar.test.js, which covers the computeRouteSections function in isolation. This is useful for verifying that the core solar-routing logic is working correctly after any change to routeSolar.js or trigo.js.

Build docs developers (and LLMs) love

Get started for freeTalk to us