How to Set Up freestylefly/awesome-gpt-image-2 Locally: Complete Installation Guide

To set up awesome-gpt-image-2 locally, clone the repository, copy .env.example to .env and configure your Supabase credentials, run npm install, execute npm run generate:style-skill to build the required JSON assets, and start the Vite development server with npm run dev at http://localhost:5173.

The awesome-gpt-image-2 project is a Vite-based React application that showcases GPT Image 2.5 capabilities through an interactive style library interface. Setting up this repository locally involves configuring Supabase authentication credentials, generating specialized skill assets using built-in scripts, and optionally integrating Google Analytics tracking. This guide walks through the exact setup process using the actual source file structure from the freestylefly/awesome-gpt-image-2 codebase.

Prerequisites

Before installation, ensure you have Node.js 16+ installed on your system. You will also need a Supabase project with the URL and anonymous key available, as the application stores authentication data via Supabase as configured in src/supabaseClient.js.

Step-by-Step Installation

1. Clone the Repository

Fetch the source code from GitHub to your local development environment.

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

2. Configure Environment Variables

The application requires specific credentials to connect with Supabase services. Create your environment file by copying the provided template.

cp .env.example .env

Edit the .env file to include the following required values:

• SUPABASE_URL: Your Supabase project URL
• SUPABASE_ANON_KEY: Your Supabase anonymous public API key
• GOOGLE_ANALYTICS_REFRESH_TOKEN: Optional token for analytics integration

The repository does not ship with sensitive values included. The src/supabaseClient.js file initializes the Supabase client using these environment variables for authentication and data persistence.

3. Install Dependencies

Install all required packages including Vite, React, the Supabase client library, and the custom skill-library package defined in package.json.

npm install

4. Generate Style-Skill Assets

Before running the application, you must compile the style definitions into JSON format for the frontend to consume.

npm run generate:style-skill

This command executes scripts/generate-style-skill.mjs, which processes the source style definitions and outputs compiled skill JSON files. These assets are essential for the React components mounted in src/main.jsx to render properly.

5. Install the Skill Globally (Optional)

If you want to use the CLI-based skill (gpt-image-2-style-library) outside the web interface or for AI agent integration, install it globally.

npm run install:skill

This runs scripts/install-style-skill.mjs, which copies the generated skill into the global skills folder for system-wide access.

6. Start the Development Server

Launch the Vite hot-reload development server to run the application locally.

npm run dev

The application will be accessible at http://localhost:5173. The entry point at src/main.jsx mounts the React UI, configures routing, and connects to the Supabase backend using the credentials defined in your .env file.

7. Configure Google Analytics (Optional)

To enable usage tracking, obtain a refresh token through Google's OAuth flow.

npm run ga4:oauth

Follow the prompted URL to authorize access, then paste the returned token into your .env file as GOOGLE_ANALYTICS_REFRESH_TOKEN or add it as a Vercel environment secret for production deployments. This process utilizes scripts/ga4-oauth.mjs to handle the authentication handshake.

Key Project Files

Understanding these core files helps with troubleshooting and customization:

• package.json: Declares npm scripts including generate:style-skill, install:skill, and ga4:oauth, plus dependencies for the Vite React architecture.
• src/supabaseClient.js: Initializes the Supabase client using environment variables for backend authentication.
• src/main.jsx: The React application entry point that renders the UI and dynamically loads generated style skills.
• scripts/generate-style-skill.mjs: Compiles raw style definitions into the structured JSON format required by the frontend.
• .env.example: Template containing all required environment variable keys without sensitive values.

Summary

• Clone the repository and copy .env.example to .env to configure your local environment.
• Install dependencies with npm install to pull in Vite, React, and Supabase packages as defined in package.json.
• Run npm run generate:style-skill to execute scripts/generate-style-skill.mjs and build the required JSON assets.
• Start local development at http://localhost:5173 using npm run dev, which launches the Vite server.
• Optionally install the global CLI skill with npm run install:skill or configure Google Analytics via npm run ga4:oauth using the scripts provided.

Frequently Asked Questions

What is the purpose of the style-skill scripts?

The scripts/generate-style-skill.mjs file compiles raw style definitions into a structured JSON format consumed by the React frontend components, while scripts/install-style-skill.mjs makes these skills available globally for CLI usage or integration with AI agent workflows.

Do I need Google Analytics to run the application locally?

No. The GOOGLE_ANALYTICS_REFRESH_TOKEN is completely optional for local development. The application runs fully without analytics tracking; you only need to run npm run ga4:oauth and configure scripts/ga4-oauth.mjs if you specifically want to collect usage data.

Which environment variables are required for basic functionality?

You must provide SUPABASE_URL and SUPABASE_ANON_KEY in your .env file, as src/supabaseClient.js depends on these to initialize the authentication client. All other variables, including the Google Analytics refresh token, are optional enhancements.

Can I use package managers other than npm?

Yes. While this guide uses npm install and npm run commands, the package.json follows standard Node.js conventions and supports pnpm install or yarn install interchangeably for dependency management and script execution.

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