Skip to content

Looking for the HydroServer v1 docs?

These docs now cover HydroServer v2. The v1 docs have moved to hydroserver.org/v1 and are still available. View the v1 version of this page.

The playground hasn't been updated to HydroServer v2 yet

This page uses playground.hydroserver.org in its steps or examples, but the playground is still running HydroServer v1. Until it's updated, the v2 features described here won't work there. Use a HydroServer v2 instance, or follow the v1 version of this page to use the playground.

Building Your First App ​

This tutorial will guide you through how to build a simple web application backed by HydroServer data.

We’ll use the @hydroserver/client TypeScript package to build a small browser app that will:

  • Fetch a page of the first 50 public monitoring sites currently on playground.hydroserver.org
  • Print each MonitoringSite with a location

The API client is written in TypeScript and gives you typed models and typed API methods end-to-end, but of course using the typing features is optional, so vanilla JavaScript will work alongside the client just fine, along with your choice of frontend framework.

Preview ​

HydroServer TypeScript demo app screenshot

Prerequisites ​

  • Node.js 20+
  • A HydroServer account (you can use https://playground.hydroserver.org)

1. Create a new frontend project ​

We’ll use Vite with TypeScript to keep the example focused on the client and framework-agnostic.

bash
npm create vite@latest hydroserver-ts-demo -- --template vanilla-ts
cd hydroserver-ts-demo
npm install
npm install @hydroserver/client

2. Add project files ​

When running locally, proxy HydroServer API routes through Vite so browser requests stay same-origin.

ts
import { defineConfig } from "vite";

export default defineConfig({
  server: { proxy: { "/api": "https://playground.hydroserver.org" } },
});
html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>HydroServer TS Demo App</title>
  </head>
  <body>
    <main class="app">
      <h1>HydroServer TS Demo App</h1>

      <section class="card">
        <h2>Public Monitoring Sites</h2>
        <p id="status" class="muted">Loading...</p>
        <ol id="monitoringSites-list" class="monitoringSite-list"></ol>
      </section>
    </main>

    <script type="module" src="/src/main.ts"></script>
  </body>
</html>
ts
import "./style.css";
import hs, { createHydroServer, type MonitoringSite } from "@hydroserver/client";

await createHydroServer({ host: "" });

const status = document.querySelector<HTMLParagraphElement>("#status")!;
const list = document.querySelector<HTMLOListElement>("#monitoringSites-list")!;

const row = ({ name, latitude, longitude }: MonitoringSite) => {
  const li = document.createElement("li");
  const lat = Number(latitude).toFixed(4);
  const lon = Number(longitude).toFixed(4);
  li.textContent = `${name}: ${lat}, ${lon}`;
  return li;
};

const res = await hs.monitoringSites.list({
  limit: 50,
  sortby: ["name"],
  isPrivate: false,
});

if (!res.ok) {
  status.textContent = res.message;
} else {
  const monitoringSites: MonitoringSite[] = res.data;
  list.replaceChildren(...monitoringSites.map(row));
  status.textContent = `Showing ${monitoringSites.length} public monitoring sites.`;
}
css
:root {
  font-family: "IBM Plex Sans", "Segoe UI", sans-serif;
  color: #0f172a;
  background: #f6fbff;
}

* {
  box-sizing: border-box;
}
body {
  margin: 0;
}

.app {
  max-width: 920px;
  margin: 2rem auto;
  padding: 0 1rem;
}

.card {
  background: #fff;
  border: 1px solid #dbeafe;
  border-radius: 12px;
  padding: 1rem;
}

.muted {
  color: #475569;
  margin-top: 0;
}

.monitoringSite-list {
  margin: 0;
  padding-left: 1.2rem;
  display: grid;
  gap: 0.75rem;
}

With this setup, the client uses host: "" so requests go through the local /api proxy.

What the API client is doing in this code ​

  1. Startup and client wiring
    await createHydroServer({ host: "" }) initializes the client once. After that, hs is available throughout your app.

  2. One API call for monitoring sites hs.monitoringSites.list(...) retrieves the first 50 monitoring sites (limit: 50), ordered by name, and limited to public monitoring sites. Use offset to fetch later pages.

  3. Rendering
    The response data is mapped directly into <li> elements with MonitoringSite name and location text.

  4. Error handling style
    Calls returning ApiResponse should check response.ok and display response.message on failure.

3. Run the app ​

bash
npm run dev

Open the local Vite URL (usually http://localhost:5173) and you should see the first 50 public monitoring sites with their locations.

Notes for production ​

  • If your frontend is served by HydroServer itself, keep host: "" and remove the dev proxy.
  • If your frontend and HydroServer are on different origins, configure CORS and CSRF/session cookie settings on the HydroServer deployment.
  • If you prefer explicit API client instances (instead of the shared hs export), you can use HydroServer.initialize(...) and pass the instance through your app.

Next step ​

For more examples of how to use @hydroserver/client, head over the how-to guide: Use the TypeScript Client.