vistaz

vistaz counts page views without prescribing how the number should look. Its browser client handles cooldown-based deduplication, while a server endpoint owns the database credentials, increments, reads, rankings, and optional SVG badges.

The package hosts no analytics service. The application chooses the endpoint and owns the data, normally in an Upstash Redis database.

The two-sided architecture

The first visit inside a cooldown sends POST to increment. Later visits send GET, so a refresh does not inflate the count. The default cooldown is 24 hours and storage falls back to memory when localStorage is unavailable.

Put credentials on the server

import { createRouteHandlers, createUpstashAdapter } from 'vistaz/server';

const views = createUpstashAdapter({
  url: import.meta.env.UPSTASH_REDIS_REST_URL,
  token: import.meta.env.UPSTASH_REDIS_REST_TOKEN,
});

export const { GET, POST } = createRouteHandlers(views);

Use replaceable environment values and keep the REST token inside the server or serverless route. It must never be embedded in browser JavaScript.

A completely static Astro deployment cannot host this endpoint. Use Astro server output with an adapter, another serverless host, or an external API and point the client at its absolute URL.

Choose the client surface

import { trackView } from 'vistaz';

const count = await trackView('articles/welcome');

import { defineVistazCounter } from 'vistaz/element';

defineVistazCounter();

<vistaz-counter slug="articles/welcome"></vistaz-counter>

React applications can use useViews. Native clients can supply an absolute endpoint and a compatible storage implementation. For another database, implement the ViewsAdapter interface and pass it to the same handlers.

Counts, rankings, and failure behavior

With the bundled Upstash adapter, all route totals live in one Redis sorted set. The server surface can return individual counts or a ranking such as the ten most-viewed pages. Badge responses work anywhere an image can be embedded, but every badge request counts and its presentation is not as flexible as native text.

trackView avoids throwing network failures into the interface and resolves 0 instead. Treat zero as “zero or temporarily unavailable” when that distinction matters to the product.

vistaz requires Node.js 20 or newer. The browser-facing core has no runtime dependency, while the package’s server adapter uses @upstash/redis; React remains an optional peer.