This page walks you through running Betterflow on your local machine from scratch. By the end you will have a fully functional development server atDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/betterspacx/app/llms.txt
Use this file to discover all available pages before exploring further.
localhost:3000 ready for editing and contributing. The only hard requirement is pnpm — the project enforces this through a preinstall hook, so attempting to use npm or Yarn will exit immediately with an error.
Prerequisites
Before you begin, make sure the following are available on your machine:- Node.js 18 or later — Betterflow uses Next.js 16 and React 19, both of which require a current Node.js runtime.
- pnpm — The project’s
package.jsonuses apreinstallhook (only-allow pnpm) that blocks all other package managers. Install it withnpm install -g pnpmif you don’t have it yet.
Installation
Clone the repository
Clone the Betterflow repository from GitHub and navigate into the project directory.
Copy the environment file
Copy the example environment file to create your local
.env. For local development, no values need to be filled in immediately — see the note below about which variables are truly required.Start the development server
Start the Next.js development server. The You should see output similar to:
--webpack flag is included in the dev script to keep the build pipeline consistent.Open the app
Open your browser and navigate to http://localhost:3000. The Betterflow editor will load and you can start uploading screenshots immediately.
Environment Variables
Core editor features work without any environment variables configured. You can upload images, apply backgrounds, add frames, use 3D transforms, animate, and export PNG/JPG/video entirely without setting up external services.
.env.example file documents every available variable. Here is a summary of what is required versus optional for local development:
| Variable | Required for local dev? | Purpose |
|---|---|---|
NEXT_PUBLIC_SITE_URL | Optional | Sets the canonical site URL; defaults to http://localhost:3000 |
NEXT_PUBLIC_FIREBASE_API_KEY | Optional | Firebase project API key |
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN | Optional | Firebase Auth domain |
NEXT_PUBLIC_FIREBASE_PROJECT_ID | Optional | Firebase project ID |
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET | Optional | Firebase Storage bucket |
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID | Optional | Firebase messaging sender ID |
NEXT_PUBLIC_FIREBASE_APP_ID | Optional | Firebase app ID |
NEXT_PUBLIC_R2_PUBLIC_URL | Optional | Public URL for your Cloudflare R2 bucket (needed for hosted background images) |
NEXT_PUBLIC_R2_CUSTOM_DOMAIN | Optional | Custom domain in front of R2 |
NEXT_PUBLIC_CDN_URL | Optional | CDN URL for serving R2 assets |
R2_ACCESS_KEY_ID | Optional | R2 API access key |
R2_SECRET_ACCESS_KEY | Optional | R2 API secret key |
R2_BUCKET_NAME | Optional | Name of the R2 storage bucket |
CLOUDFLARE_ACCOUNT_ID | Optional | Your Cloudflare account ID |
R2_ACCOUNT_ID | Optional | R2-specific account ID |
R2_API_TOKEN | Optional | R2 API token |
NEXT_PUBLIC_POSTHOG_KEY | Optional | PostHog analytics API key |
NEXT_PUBLIC_POSTHOG_HOST | Optional | PostHog host (defaults to https://us.i.posthog.com) |
GOOGLE_SITE_VERIFICATION | Optional | Google Search Console verification token |
CLEANUP_SECRET | Optional | Secret token for the cache cleanup API route |
What’s Next
Self-Hosting
Deploy Betterflow to Vercel or Docker for production use.
Environment Variables
Full reference for every configuration option.