Self-hosting & local development

Run widgets.pro on your own infrastructure or set up a local development environment.

This page is for developers who want to run widgets.pro on their own infrastructure — self-hosting, contributing to the platform, or building custom widgets locally.

If you just want to use widgets.pro, you don't need any of this — sign up at widgets.pro or grab the native apps instead.

Prerequisites

Node.js 22 or later.
Yarn 4 (the project uses Yarn Berry with workspaces).
Git.
PostgreSQL — local instance or a hosted DB (Neon, Supabase, RDS).

Clone and install

git clone https://github.com/widgets-pro/widgets.pro.git
cd widgets.pro
yarn install

Environment setup

Copy the example environment file and fill in the values:

cp .env.example .env.local

Required variables:

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`BETTER_AUTH_SECRET`	Secret used by Better Auth for session signing
`NEXT_PUBLIC_API_URL`	API endpoint, default `http://localhost:4001`

Optional variables for OAuth providers, Stripe, email transports, and integrations are documented in .env.example.

Database migrations

yarn workspace @wdg/api db:push

This applies the current Drizzle schema to your database. To open Drizzle Studio for inspection: yarn workspace @wdg/api db:studio.

Start the services

In separate terminals:

yarn web                            # Next.js on port 3000
yarn workspace @wdg/api start:dev   # NestJS API on port 4000 (HTTPS) / 4001 (HTTP)
yarn native                         # Expo dev server (mobile)

Open http://localhost:3000 to use the web app.

Next steps

Project structure — understand the codebase.
Widget Blueprint Protocol — how widgets render across platforms.