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

> Run awesome-gpt-image-2 locally. Follow this guide to clone the repo, install dependencies, configure Supabase, and start the dev server for easy setup.

- Repository: [苍何/awesome-gpt-image-2](https://github.com/freestylefly/awesome-gpt-image-2)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/main.jsx), [`src/styles.css`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/styles.css), [`src/community.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/community.jsx) |
| **Backend (API)** | Vercel serverless functions for auth, billing, image generation | [`api/generate-image.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/generate-image.js), [`api/me.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/me.js), `api/billing/` folder |
| **Infrastructure** | Supabase auth/database, Stripe, Alipay, GA4 | [`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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)](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:

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

```

The [`package.json`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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:

```bash
cp .env.example .env

```

Edit `.env` to include at minimum these **Supabase variables**:

```text
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)](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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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

```bash
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:

```bash
npx vercel dev

```

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

```bash
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)](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:

```bash
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:

```bash
npm test

```

### Generate and Install the Style Skill

For Claude Code, Codex, or other agent integrations:

```bash
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`](https://github.com/freestylefly/awesome-gpt-image-2/tree/main/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)](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)](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)](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)](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`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/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`.