diy-analytics

Local Development

Run diy-analytics locally for feature development, running the test suite, or contributing to the open-source repository.

Prerequisites

  • Node.js v18.17.0 or higher (Node 20+ recommended)
  • Git for version control
  • PostgreSQL 14+ — a local install, a Docker container, or a cloud database on Neon/Supabase

Setup

1. Clone the repository

bash
1git clone https://github.com/heysagnik/diy-analytics.git 2cd diy-analytics

2. Install dependencies

bash
npm install

3. Start a local PostgreSQL instance

If Docker is installed, launch a PostgreSQL 16 container with a single command:

bash
1docker run --name diy-postgres \ 2 -e POSTGRES_PASSWORD=password \ 3 -e POSTGRES_DB=diy-analytics \ 4 -p 5432:5432 \ 5 -d postgres:16-alpine

4. Configure environment variables

Create your .env.local:

bash
cp .env.local.example .env.local

Set the minimal required variables:

bash
1# Local PostgreSQL connection 2DATABASE_URL=postgres://postgres:password@localhost:5432/diy-analytics?sslmode=disable 3 4# Local development server URL 5NEXT_PUBLIC_SITE_URL=http://localhost:3000 6 7# Optional soft quota 8DATABASE_STORAGE_CAP_MB=512

5. Apply schema migrations

bash
npm run db:migrate

This initializes all tables — workspaces, projects, pageviews, events, and errors.

6. Start the development server

bash
npm run dev

Visit http://localhost:3000. You'll land on the initial setup form to create your workspace owner credentials.

CLI scripts

CommandDescription
npm run devStarts the local Next.js development server with hot module replacement
npm run buildBuilds the production bundle and validates TypeScript types
npm testRuns the Jest unit and integration test suite
npm run db:migrateApplies all pending SQL migrations against DATABASE_URL
npm run db:generateGenerates new SQL migration files after updating src/lib/schema/
npx drizzle-kit studioLaunches Drizzle Studio, an interactive web GUI for your database

Drizzle Studio

To explore, query, and edit database records in real time during development:

bash
npx drizzle-kit studio

Drizzle Studio opens at https://local.drizzle.studio, connected to your local database.

Contributing

We welcome pull requests and issue reports.

  1. Fork the repository and create a feature branch (git checkout -b feature/amazing-feature).
  2. Verify all tests pass with npm test and npm run build.
  3. Commit your changes and open a pull request on GitHub.

Next steps

Connecting Your Website

Learn how to install the tracking script on web applications.

Database Setup & Pooling

Learn about production connection pooling with Neon and Supabase.