How to Run the awesome‑gpt‑image‑2 Repository: Complete Local Setup Guide

To run awesome‑gpt‑image‑2 locally, clone the repository, install dependencies with npm install, configure your .env file with Supabase credentials, and start the Vite dev server with npm run dev.

The awesome‑gpt‑image‑2 repository by freestylefly is a Vite‑powered React application that showcases GPT‑Image2 prompts through a visual gallery, complete with user authentication, billing integrations, and serverless API endpoints. This guide walks through running the code in freestylefly/awesome‑gpt‑image‑2 from clone to production build, with all technical details drawn directly from the source.

Prerequisites and Repository Structure

Before running the code, understand how the project is organized. The codebase splits into three distinct layers:

Layer	Responsibility	Key Files
Frontend	React UI, routing, localization, tracking	src/main.jsx, src/styles.css, src/community.jsx
Backend (API)	Vercel serverless functions for auth, billing, image generation	api/generate-image.js, api/me.js, api/billing/ folder
Infrastructure	Supabase auth/database, Stripe, Alipay, GA4	src/supabaseClient.js, .env.example

The entry point for the React application is [src/main.jsx](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx), which initializes localization, Google Analytics 4, and the root component tree.

Step‑by‑Step: Running awesome‑gpt‑image‑2 Locally

1. Clone and Install Dependencies

Start by cloning the repository and installing Node.js dependencies:

git clone https://github.com/freestylefly/awesome-gpt-image-2.git
cd awesome-gpt-image-2
npm install

The package.json specifies React 19, Vite 7, and SDKs for Supabase and Stripe.

2. Configure Environment Variables

Copy the template file and fill in your credentials:

cp .env.example .env

Edit .env to include at minimum these Supabase variables:

VITE_SUPABASE_URL=<your-supabase-url>
VITE_SUPABASE_ANON_KEY=<your-anon-key>
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>

Optional variables in .env.example include:

• CIYUAN_API_KEY – for image generation proxy
• Stripe keys (STRIPE_SECRET_KEY, VITE_STRIPE_PUBLISHABLE_KEY)
• Alipay configuration
• VITE_GA4_ID – for Google Analytics tracking

The Supabase client initialization lives in [src/supabaseClient.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js), which reads these variables at runtime.

3. Pre‑generate Static Data (Automated)

The predev script runs automatically before npm run dev to build derived assets:

Script	Purpose
npm run generate:site-data	Builds data/cases.json and related gallery assets
npm run generate:style-skill	Creates the style‑library skill package for AI agents

4. Start the Development Server

npm run dev

Vite launches on http://localhost:5173 with hot‑module replacement enabled. The dev server proxies /api/* requests to the serverless functions defined in the api/ directory.

5. Test the API Endpoints Locally

To exercise the serverless functions directly, use Vercel's local runtime:

npx vercel dev

This serves the /api/ folder on a local Vercel‑like environment. Test the image generation endpoint with:

curl -X POST http://localhost:5173/api/generate-image \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a futuristic city skyline, ultra-realistic, 4k"}'

The handler in [api/generate-image.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js) forwards this prompt to the GPT‑Image2 service and returns the generated image URL.

Building and Deploying

Production Build

Generate optimized static assets:

npm run build

Vite outputs to dist/, ready for deployment to Vercel, Netlify, or any static host.

Running Tests

Execute the included unit tests for API helpers:

npm test

Generate and Install the Style Skill

For Claude Code, Codex, or other agent integrations:

npm run generate:style-skill   # outputs to agents/skills/gpt-image-2-style-library

npm run install:skill          # installs into local agent folders

The generated skill package lives at agents/skills/gpt-image-2-style-library and provides structured prompt templates that AI coding agents can import.

Key Configuration Files

File	Purpose
[package.json](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/package.json)	Scripts, dependencies, Node entry points
[src/main.jsx](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx)	React bootstrap, i18n, GA4 initialization
[api/me.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/me.js)	Authentication state endpoint
.env.example	Complete template for all environment variables

Summary

• Clone and install: git clone → npm install
• Configure: Copy .env.example → add Supabase URL and keys
• Develop: npm run dev starts Vite on port 5173
• Test APIs: Use npx vercel dev or curl against /api/generate-image
• Build: npm run build produces deployable dist/ output
• Extend: Generate agent skills with npm run generate:style-skill

Frequently Asked Questions

What is the minimum setup to run awesome‑gpt‑image‑2?

You need Node.js, the cloned repository, npm install, and a .env file with VITE_SUPABASE_URL, VITE_SUPABASE_ANON_KEY, and SUPABASE_SERVICE_ROLE_KEY. These three variables enable the core gallery UI and authentication flow. Billing and analytics features require additional optional variables.

Can I run awesome‑gpt‑image‑2 without Supabase?

No. According to the source code in [src/supabaseClient.js](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js), the Supabase client initializes at module load and is required for authentication and database operations. The application will fail to start without valid Supabase credentials.

How do I test the image generation API locally?

Start the dev server with npm run dev, then POST to http://localhost:5173/api/generate-image with a JSON body containing your prompt. Alternatively, run npx vercel dev to invoke the serverless function through Vercel's local runtime.

What Node.js version does awesome‑gpt‑image‑2 require?

The package.json does not specify an explicit Node.js engine constraint, but dependencies like Vite 7 and React 19 require Node.js 18 or newer. Use node -v to verify your version before running npm install.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}