How to Get Started with the Vite + TypeScript Web Application in awesome-gpt-image-2

Clone the repository, install dependencies with npm ci, generate static assets via npm run generate:site-data, and launch the dev server with npm run dev to run the GPT-Image-2 demo on localhost:5173.

The freestylefly/awesome-gpt-image-2 repository provides a Vite-powered React front-end that demonstrates GPT-Image-2 capabilities. Getting started with this Vite TypeScript web application requires understanding its three-layer architecture and automated build pipeline. The project uses ES modules throughout and supports TypeScript migration with minimal configuration changes.

Project Architecture Overview

The codebase splits responsibilities across three distinct layers according to the source code analysis.

Build and Tooling Layer

The build and tooling layer configures Vite and the React plugin in vite.config.js. This file sets the publicDir to serve static assets and enables hot module replacement during development. Vite handles all TypeScript compilation automatically when you rename files from .jsx to .tsx.

Application Code Layer

The application code layer contains the React components in the src/ directory. Key files include:

• src/main.jsx — The entry point that mounts the React root and loads the gallery UI
• src/community.jsx — Implements the community page with WeChat QR integration
• src/supabaseClient.js — Provides authentication helpers for Supabase integration

Data Generation Scripts Layer

The data generation scripts layer pre-processes content before the UI consumes it. The scripts/generate-site-data.mjs file generates data/style-library.json and case indexes that populate the gallery. These scripts run automatically before the dev server starts via npm predev hooks.

Step-by-Step Setup Guide

Follow these steps to get the Vite TypeScript web application running locally.

Install Dependencies

Run the following command to install Vite, React, and all required packages:

npm ci

This installs the React-Vite plugin and ES module dependencies defined in package.json.

Generate Static Data

The application requires pre-built JSON data to render the style library. Run:

npm run generate:site-data
npm run generate:style-skill

These commands execute scripts/generate-site-data.mjs and related modules to populate the data/ directory with style-library.json and image assets. Alternatively, these run automatically when you execute npm run dev due to the predev script hook.

Configure Environment Variables

Create a .env file in the repository root with the following Vite-prefixed variables:

VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_anon_key
VITE_GA_MEASUREMENT_ID=your_ga_id

Vite injects these at build time. Access them in your code using import.meta.env.VITE_SUPABASE_URL.

Start the Development Server

Launch the Vite dev server with:

npm run dev

The server starts on localhost:5173 by default. Vite serves src/ as ES modules and exposes the data/ folder as static files via the publicDir configuration.

Adding TypeScript Support

While the project ships with .jsx files, converting to TypeScript requires minimal effort thanks to Vite's native support.

File Structure Changes

Rename existing files from .jsx to .tsx or add new .ts modules. Vite automatically compiles TypeScript without additional plugins because @vitejs/plugin-react includes TypeScript support. For example, rename src/main.jsx to src/main.tsx and update the imports.

TypeScript Configuration

Create a tsconfig.json in the repository root to enable strict type checking:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*.tsx", "src/**/*.ts"]
}

With this configuration, Vite type-checks code during npm run dev and production builds.

Understanding the Build Pipeline

The package.json defines a script pipeline that automates data generation:

{
  "scripts": {
    "predev": "npm run generate:site-data && npm run generate:style-skill",
    "dev": "vite",
    "prebuild": "npm run generate:site-data && npm run generate:style-skill",
    "build": "vite build",
    "preview": "vite preview"
  }
}

The predev and prebuild hooks ensure static data is fresh before starting the server or creating a production bundle. The build command outputs optimized assets to dist/, while preview serves this folder locally for verification.

Summary

• The three-layer architecture separates Vite configuration, React components, and data generation scripts for maintainability.
• Key files include vite.config.js for build settings, src/main.jsx for the React entry point, and scripts/generate-site-data.mjs for static asset generation.
• Environment variables must use the VITE_ prefix and reside in a .env file for runtime access via import.meta.env.
• TypeScript migration involves renaming .jsx files to .tsx and optionally adding a tsconfig.json file.
• Development workflow uses npm run dev (with automatic data generation) and npm run build for production.

Frequently Asked Questions

Do I need to manually run the data generation scripts before starting the dev server?

No. The package.json includes a predev hook that automatically runs npm run generate:site-data && npm run generate:style-skill before npm run dev executes. However, you can run them manually if you need to refresh the data without restarting the server.

Can I use TypeScript in this project even though it uses .jsx files?

Yes. The project already includes "type": "module" in package.json and the React Vite plugin handles TypeScript compilation natively. Simply rename files from .jsx to .tsx and add a tsconfig.json to enable strict type checking. Vite will hot-reload TypeScript components without additional configuration.

What environment variables are required to run the application locally?

You need three Vite-prefixed variables in your .env file: VITE_SUPABASE_URL and VITE_SUPABASE_ANON_KEY for authentication, plus VITE_GA_MEASUREMENT_ID for Google Analytics. The scripts/ga4-oauth.mjs script can help obtain valid GA4 tokens if needed for tracking.

How do I build the application for production deployment?

Run npm run build to create an optimized production bundle in the dist/ directory. The prebuild hook ensures static data is generated first. Use npm run preview to serve the dist/ folder locally and verify the build before deploying to your hosting platform.

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