Primeiros passos

O Runlight é um analytics web que se instala no seu app. Leva cinco minutos para ir do npm install à sua primeira visita.

O Runlight é uma biblioteca que roda dentro de um app que você já tem. Ele guarda o que conta no seu banco de dados e serve o painel no seu próprio domínio, em /runlight, então não há conta no Runlight para criar e seus dados nunca passam por um servidor nosso.

Esta página configura a biblioteca TypeScript, que precisa de um app capaz de servir rotas, como Next.js, Nuxt, SvelteKit, Astro, Remix, Express, NestJS, Fastify, Koa, Hono ou qualquer outro que trate um Request web. Ela roda no Node 22 ou mais recente, Bun, Deno ou Cloudflare Workers.

O Runlight também tem versões para PHP, Python, Ruby e Rails, Go, Java, .NET, Elixir e Rust. Cada um serve o mesmo painel a partir das mesmas tabelas, e a página de cada linguagem traz os passos dela. Sites em WordPress, Drupal e Craft usam um plugin que roda o Runlight dentro do CMS ou envia as visitas para um Runlight que você roda em outro lugar. Para um painel com vários sites, ou para um site cujo app não consegue rodar o Runlight, use o servidor independente.

1. Instale

npm install @runlight/sdk better-sqlite3

better-sqlite3 é o driver do SQLite. Para Postgres, MySQL, MariaDB, Turso, Cloudflare D1 ou o SQLite do próprio Bun, veja Configuração.

2. Crie a instância

Crie um arquivo e importe-o onde precisar do 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" },
});

As tabelas são criadas no primeiro uso. O arquivo do banco de dados é seu, então faça backup dele como de qualquer outro.

3. Monte as rotas

No Next.js (App Router), uma rota catch-all serve o script de rastreamento e o painel e recebe cada visita.

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

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

Outros frameworks também pedem uma ou duas linhas, como mostra Instalação.

4. Adicione o script

Coloque isto em todas as páginas, logo antes de </head>.

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

O script tem menos de 2 KB com gzip e envia os dados para o seu próprio domínio sem definir nenhum cookie.

5. Entre

O painel é privado, então defina um token longo e aleatório no seu ambiente.

RUNLIGHT_TOKEN=a-long-random-string

Depois abra /runlight/?token=a-long-random-string uma vez. O Runlight define um cookie com um digest do token (nunca o próprio token) e leva você ao painel. Sem token definido, o painel só fica aberto enquanto NODE_ENV for development, como acontece com next dev. Em qualquer outro caso ele responde 503 até você definir um.

Visite qualquer página do seu site e, em segundos, você vai se ver no contador "agora".

6. Agende a verificação de hora em hora

Uma verificação que você chama uma vez por hora troca o salt diário e envia os relatórios por email. Ela também apaga as visitas que um site não guarda mais e soma os dias já encerrados, e Verificação agendada mostra como configurá-la. Na Vercel são quatro linhas de vercel.json.

Próximos passos

• Rastreamento cobre eventos personalizados, single page apps, cliques sem código e as configurações na tag do script.
• Metas cobre conversões e receita.
• Links curtos coloca links no seu próprio domínio e os conta como visitas.
• Privacidade lista exatamente o que o Runlight guarda e o que deixa de fora.