Helios is built to deploy on Vercel with no framework configuration and no build step. The static front-end (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.
index.html, index_def.js, CSS, and client-side JS modules) is served as-is, and the two serverless functions under /api (geocode.js and timezone.js) are picked up automatically by Vercel’s zero-config function detection. The only setup required beyond importing the repository is setting three environment variables and pinning the Node.js runtime version.
Steps
Push to GitHub and connect to Vercel
Push your Helios repository to GitHub (or GitLab / Bitbucket). Then open the Vercel dashboard and click Add New → Project. Select the Helios repository from the list and click Import.You do not need to configure a build command or output directory — Vercel will detect that this is a static project with serverless functions and configure itself accordingly.
Set environment variables
Before completing the import (or at any time via Settings → Environment Variables), add the following three variables. Make sure they are enabled for the Production, Preview, and Development environments as needed.
All three keys are required for full production reliability. If the primary provider for either function is unreachable, Helios falls back to the secondary provider automatically — but that fallback will also fail if its key is missing.
| Variable | Purpose | Provider |
|---|---|---|
OPENCAGE_KEY | Geocoding fallback — used by api/geocode.js when Nominatim cannot resolve a location | opencagedata.com |
IPGEOLOCATION_KEY | UTC-offset lookup — primary timezone provider used by api/timezone.js | ipgeolocation.io |
TIMEZONEDB_KEY | UTC-offset fallback — used by api/timezone.js when ipgeolocation.io is unavailable | timezonedb.com |
Pin the Node.js version
Go to Settings → General in your Vercel project and set the Node.js Version to 24.x. This matches the Using an older Node.js version may cause the serverless functions to behave unexpectedly, since they rely on ES module syntax (
engines constraint in package.json:"type": "module" in package.json).Redeploy
If you set environment variables after the initial deployment, go to the Deployments tab and click Redeploy on the most recent deployment (or simply push a new commit). Vercel will rebuild and re-deploy the project with the new environment variables injected into the function runtime.Once the deployment is live, your Vercel-assigned URL (e.g.
https://helios-asientos.vercel.app) will serve the full application — static front-end and serverless API functions together.How the serverless functions work
The browser never calls any third-party geocoding or timezone API directly. All external API calls are made server-side, keeping your keys out of the client bundle./api/geocode — Resolves a city and country name to a latitude/longitude pair. It first queries the Nominatim OpenStreetMap API (which requires a valid User-Agent header that can only be set server-side). If Nominatim returns no results, the function falls back to OpenCage using OPENCAGE_KEY.
/api/timezone — Returns the UTC offset (in hours) for a given latitude and longitude. It queries ipgeolocation.io first using IPGEOLOCATION_KEY. If that call fails, it falls back to TimeZoneDB using TIMEZONEDB_KEY.
Both functions respond with simple JSON objects. The front-end calls them as same-origin fetch requests (/api/geocode?city=…&country=… and /api/timezone?lat=…&lon=…), so no CORS configuration is needed on either the client or the server.
Environment variable reference
| Variable | Purpose | Provider URL |
|---|---|---|
OPENCAGE_KEY | Geocoding fallback for api/geocode.js | opencagedata.com |
IPGEOLOCATION_KEY | Primary timezone lookup for api/timezone.js | ipgeolocation.io |
TIMEZONEDB_KEY | Timezone fallback for api/timezone.js | timezonedb.com |