# How to Set Up Local Development with Supabase and Vite for awesome-gpt-image-2

> Set up local development with Supabase and Vite for awesome-gpt-image-2. Configure environment variables, start Supabase locally, and run Vite for efficient API proxying.

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

---

**To set up local development with Supabase and Vite, configure environment variables split between browser-exposed and server-only secrets, start the local Supabase container with `supabase start`, and run the Vite dev server which proxies API requests to a local Node process.**

Setting up local development with Supabase and Vite for the awesome-gpt-image-2 project requires orchestrating a React frontend bundled by Vite, a local Supabase PostgreSQL instance, and server-side API handlers that bypass Row-Level Security. This architecture uses environment variable prefixes to safely expose configuration to the browser while keeping sensitive service-role keys server-side according to the repository source code.

## Configure Environment Variables for Local Development

The project relies on a strict separation between variables exposed to the browser and those kept server-side.

Create a local environment file by copying the template:

```bash
cp .env.example .env

```

Edit `.env` to include values provided by the local Supabase CLI:

```dotenv

# Browser-exposed variables (VITE_ prefix required)

VITE_SUPABASE_URL=http://127.0.0.1:54321
VITE_SUPABASE_ANON_KEY=your-anon-key

# Server-only secrets (never exposed to browser)

SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
SUPER_ADMIN_EMAILS=you@example.com

```

**Vite** automatically loads `.env` files and injects any variable prefixed with `VITE_` into the browser build via `import.meta.env`. Variables without this prefix remain available only to the Node process handling API requests, as implemented in [`vite.config.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/vite.config.js).

## Start the Local Supabase Instance

The database layer runs inside Docker containers managed by the Supabase CLI, providing Postgres, Auth, and Storage services locally.

Install the CLI globally and initialize the local stack:

```bash
npm install -g supabase
supabase start

```

The `supabase start` command automatically applies migrations found in `supabase/migrations/`, including schema definitions for user credits, membership plans, and Alipay integrations defined in files like [`202605090001_user_credits.sql`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/202605090001_user_credits.sql). After the containers initialize, the CLI outputs a public URL and anonymous key—paste these values into your `.env` file as `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY`.

## Launch the Vite Development Server with API Proxy

Unlike standard Vite setups, this project requires the `scripts/vite-local-api.mjs` proxy to handle server-side API routes locally.

Start the full development stack:

```bash
npm install
npm run dev

```

The `npm run dev` command executes `node scripts/vite-local-api.mjs`, which performs three critical actions:

- Spawns a **Node API server** on a random available port, passing all server-side environment variables including `SUPABASE_SERVICE_ROLE_KEY`
- Configures Vite to proxy any request matching `/api/*` to this local Node server
- Maintains hot-module replacement for the React frontend while keeping API routes functional

You can verify the proxy works by navigating to `http://localhost:5173/api/me`—this should return the current Supabase user payload by hitting the [`api/me.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/me.js) handler.

## Connect the Frontend to Supabase

The browser-side Supabase client reads the injected environment variables to authenticate and query the database.

In [`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js), the client initialization uses `createClient` from `@supabase/supabase-js`:

```javascript
import { createClient } from '@supabase/supabase-js';

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;

export const supabase = createClient(supabaseUrl, supabaseAnonKey);

export async function getCurrentUser() {
  const { data, error } = await supabase.auth.getUser();
  if (error) throw error;
  return data.user;
}

```

This client handles authentication and public database queries subject to Row-Level Security policies. Import this module into any UI component—such as [`src/community.jsx`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/community.jsx)—to interact with Auth or fetch data using the anon key.

## Implement Server-Side API Handlers

Privileged operations that bypass Row-Level Security—such as creating user credits or handling Stripe webhooks—run in the `api/` folder using a service-role client.

The server-side Supabase initialization in [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js) uses the restricted key:

```javascript
import { createClient } from '@supabase/supabase-js';

const supabase = createClient(
  process.env.VITE_SUPABASE_URL,
  process.env.SUPABASE_SERVICE_ROLE_KEY
);

export default supabase;

```

**Service-role keys** bypass all security policies, enabling administrative functions like RPC calls and table mutations. Keep these keys out of the browser by ensuring they lack the `VITE_` prefix and are only referenced in server-side files under the `api/` directory.

When the frontend calls `/api/favorites`, Vite's proxy forwards the request to the local Node process executing [`api/favorites.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/favorites.js), maintaining parity with the production Vercel deployment structure.

## Summary

- **Environment split**: Use `VITE_*` prefixes for browser variables and plain `SUPABASE_*` for server secrets in `.env`
- **Database startup**: Run `supabase start` to launch Postgres and Auth containers with automatic migration execution from `supabase/migrations/`
- **Dev server**: Execute `npm run dev` to run `scripts/vite-local-api.mjs`, which starts both the Vite frontend and the Node API proxy
- **Client setup**: Import from [`src/supabaseClient.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/src/supabaseClient.js) to use the anon-key client restricted by Row-Level Security
- **Server setup**: Use [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js) with the service-role key for privileged operations requiring RLS bypass

## Frequently Asked Questions

### What is the difference between VITE_SUPABASE_ANON_KEY and SUPABASE_SERVICE_ROLE_KEY?

**VITE_SUPABASE_ANON_KEY** is a public key safe for browser exposure that respects Row-Level Security policies, while **SUPABASE_SERVICE_ROLE_KEY** is a secret administrative key kept server-side in [`api/_lib/supabase.js`](https://github.com/freestylefly/awesome-gpt-image-2/blob/main/api/_lib/supabase.js) that bypasses all security restrictions. Never expose the service-role key to the frontend, as it grants full database access regardless of policies.

### How do I run database migrations when setting up local Supabase development?

When you execute `supabase start`, the CLI automatically runs all SQL files in `supabase/migrations/` against the local Postgres container. Migrations define tables, functions, and security policies. If you modify schema files, stop the container with `supabase stop` and restart to reapply migrations, or use `supabase db reset` for a clean slate.

### Can I set up local development with Supabase and Vite without Docker?

No. The Supabase local development workflow requires Docker to run Postgres, GoTrue (Auth), and other services. The `supabase` CLI orchestrates these containers automatically. Without Docker, you would need to connect to a remote Supabase project instead of running `supabase start` locally.

### Why does the Vite setup use a proxy script instead of standard API routes?

The `scripts/vite-local-api.mjs` proxy allows the frontend to call `/api/*` endpoints exactly as it would in production on Vercel, while actually running a local Node server during development. This maintains URL parity between environments and ensures server-side code can access private environment variables like `SUPABASE_SERVICE_ROLE_KEY` without exposing them through Vite's client-side bundling process.