FashionistaAI is a React + Vite web app with an Express upload API that transforms an outfit photo into four AI-styled looks using Cloudinary Generative Replace, Generative Background Replace, Generative Restore, Generative Recolor, signed server-side upload, and eager transformations.
- Fashion retail and lookbooks — Let shoppers upload a photo and preview the same outfit in business, sporty, streetwear, or formal contexts without a separate photo shoot for each style.
- Personal styling and inspiration apps — Give users four distinct wardrobe directions from one image, then let them recolor a top or bottom interactively before sharing or saving.
- Cloudinary GenAI integration reference — Study a minimal full-stack sample that chains multiple generative effects, handles HTTP 423 polling while derivatives generate, and pre-warms variants with eager transforms at upload time.
- React 19 — UI components and state
- Vite 6 — frontend dev server and production build
- Express 4 — secure image upload API
- TypeScript — typed frontend and shared logic
- Vitest + Testing Library — unit and component tests
- @cloudinary/url-gen — transformation URL builder
- @cloudinary/react —
AdvancedImagedelivery component - Cloudinary Node SDK — signed
upload_streamon the server
upload_stream— streams the uploaded file from Express to Cloudinary using your API key and secret (signed upload; no upload preset required in this app)eager— pre-generates all four styled variants as named transformations when the source image is uploadedeager_async— runs eager transformations asynchronously so the upload response returns immediately while derivatives are still processinggen_replace— swaps detected garments (shirt and pants) with style-specific prompts such as “suit jacket for upper body” or “sport shorts for lower body”gen_background_replace— replaces the scene background using a natural-language prompt per style (office, gym, street, gala)gen_restore— reduces noise and imperfections after generative editsgen_recolor— recolors a specific detected object (shirt or pants) via natural-language prompt without affecting the rest of the imagec_fill— crops and scales delivered images to a fixed 500×500 square for the preview grid and source thumbnail
Before you begin, ensure you have the following:
- Node.js 20 or newer (22 LTS recommended — see
.nvmrc) - npm 10 or newer
- A Cloudinary account with access to Generative AI transformations (Gen Replace, Gen Background Replace, Gen Restore, Gen Recolor)
Create a .env file at the project root. Start from the template:
cp .env.example .envThen set these variables:
| Variable | Required | Description |
|---|---|---|
CLOUDINARY_CLOUD_NAME |
Yes | Cloud name used by the Express server for signed uploads |
CLOUDINARY_API_KEY |
Yes | API key for server-side upload authentication |
CLOUDINARY_API_SECRET |
Yes | API secret for server-side upload authentication — keep server-only, never expose to the browser |
VITE_CLOUDINARY_CLOUD_NAME |
Yes | Cloud name used by the React app when building transformation delivery URLs with @cloudinary/url-gen |
PORT |
No | Express API port (default: 8000) |
Example .env contents:
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
VITE_CLOUDINARY_CLOUD_NAME=your_cloud_name
PORT=8000
Notes:
VITE_-prefixed variables are embedded in the frontend bundle at build time. Set them before runningnpm run buildfor production.- Server credentials (
CLOUDINARY_API_KEY,CLOUDINARY_API_SECRET) are read only byserver.jsand are never sent to the client.
npm installCopy .env.example to .env and fill in all required Cloudinary values listed above.
npm run dev:allThis runs:
- Vite frontend at http://localhost:3000 — proxies
/apirequests to the backend - Express backend at http://localhost:8000 — handles
POST /api/generateuploads
In your browser, go to http://localhost:3000.
- Click Choose File and select a photo of a person wearing a shirt and pants.
- Wait for the upload spinner to finish — four style tiles appear labeled business casual, sporty, streetwear, and elegant.
- Click any generated look to open the recolor dialog.
- Choose Top or Bottom, pick a color, and click Change Item Color to apply
gen_recolor.
npm run dev # terminal 1 — Vite on port 3000
npm start # terminal 2 — Express on port 8000| Command | Description |
|---|---|
npm run dev:all |
Start Vite and Express concurrently |
npm run dev |
Start Vite frontend only |
npm start |
Start Express backend with nodemon |
npm run build |
Type-check and build production frontend to dist/ |
npm run preview |
Serve the production build locally |
npm run test |
Run Vitest in watch mode |
npm run test:ci |
Run all tests once with coverage |
npm run lint |
Run ESLint |
| Step | Action |
|---|---|
| Build | Run npm run build with production VITE_CLOUDINARY_CLOUD_NAME set |
| Host frontend | Deploy the dist/ folder to your static host; ensure /api routes proxy to your Express server |
| Host backend | Deploy server.js with CLOUDINARY_* secrets configured in your host's environment |
| Health check | Confirm GET /api/health returns {"status":"ok"} |
| Smoke test | Upload an outfit image and verify four styled tiles load (may take several seconds while GenAI derivatives finish; the app retries on HTTP 423) |
See VERIFICATION.md for the full build, test, and Cloudinary functionality checklist.
- UPGRADE.md — dependency upgrade log and architecture notes
- GITHUB_METADATA.md — GitHub About description and topic tags for this repository
Connect with other developers on Twitter, Discord, or the Community Forums.
Learn more about Cloudinary GenAI at ai.cloudinary.com.