Getting started

Runlight is web analytics that installs into your app. It takes five minutes to get from npm install to your first visit.

Runlight is a library that runs inside an app you already have. It stores what it counts in your database and serves its dashboard from your own domain at /runlight, so there is no Runlight account to create and your data never passes through a server of ours.

This page sets up the TypeScript library, which needs an app that can serve routes, such as Next.js, Nuxt, SvelteKit, Astro, Remix, Express, NestJS, Fastify, Koa, Hono, or anything else that handles a web Request. It runs on Node 22 or later, Bun, Deno, or Cloudflare Workers.

Runlight also comes in versions for PHP, Python, Ruby and Rails, Go, Java, .NET, Elixir, and Rust. Each one serves the same dashboard from the same tables, and its page has the steps for that language.

WordPress, Drupal, and Craft sites take a plugin that runs Runlight inside the CMS or sends their visits to a Runlight you run elsewhere. For one dashboard over several sites, or for a site whose app cannot run Runlight, run the standalone server. A Webflow site sends its visits to the standalone server with one script tag.

1. Install

npm install @runlight/sdk better-sqlite3

better-sqlite3 is the SQLite driver. For Postgres, MySQL, MariaDB, Turso, Cloudflare D1, or Bun’s own SQLite, see Configuration.

2. Create the instance

Create one file and import it wherever you need Runlight.

import { runlight } from "@runlight/sdk";
import { sqlite } from "@runlight/sdk/sqlite";

export const rl = runlight({
  store: sqlite({ path: "./data/runlight.db" }),
  site: { name: "example.com", hostnames: ["example.com"], timezone: "Europe/London" },
});

The tables are created on first use. The database file is yours, so back it up like any other.

3. Mount the routes

In Next.js (App Router), one catch-all route serves the tracker and the dashboard and receives each visit.

import { rl } from "@/lib/runlight";

export const { GET, POST, PUT, PATCH, DELETE, OPTIONS } = rl.routes();

Other frameworks take one or two lines too, as Install shows.

4. Add the script

Put this on every page, just before </head>.

<script defer src="/runlight/s.js"></script>

The script is under 2 KB gzipped and posts to your own domain without setting any cookies.

5. Sign in

The dashboard is private, so set a long random token in your environment.

RUNLIGHT_TOKEN=a-long-random-string

Then open /runlight/?token=a-long-random-string once. Runlight sets a cookie holding a digest of the token (never the token itself) and sends you on to the dashboard.

With no token set, the dashboard is open only while NODE_ENV is development, as it is under next dev. Everywhere else it answers 503 until you set one.

Visit any page of your site and you will see yourself under “here now” within seconds.

6. Schedule the hourly check

Call a check once an hour. It rotates the daily salt, sends email reports, deletes visits a site no longer keeps, and adds up finished days. Scheduled check shows how to set it up. On Vercel it is four lines of vercel.json.

Next

• Tracking covers custom events, single page apps, clicks with no code, and the settings on the script tag.
• Goals covers conversions and revenue.
• Short links puts links on your own domain and counts them like visits.
• Privacy lists exactly what Runlight stores and what it leaves out.