Getting Started

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• package.json
• vite.config.ts
• index.html
• App.tsx
• services/hfService.ts
• components/SettingsModal.tsx

This guide provides all the necessary information to set up, run, configure, and deploy the Peinture (AI Image Gen) application. Peinture is a sleek, dark-themed AI image generator built with React, TypeScript, and Tailwind CSS. It functions as a static Single Page Application (SPA) that interfaces with Hugging Face models to generate images from text prompts.

The application is built using Vite and features multi-model support, prompt optimization, and a local history gallery. All user data, including generated image history and API tokens, is stored exclusively in the browser's localStorage, requiring no backend database for user data management.

Sources: README.md:1-5, 9-24, 52-53

Prerequisites

Before you begin, ensure you have the following software installed on your system:

• Node.js: Version 18 or higher.
• Package Manager: npm, yarn, or pnpm.

Sources: README.md:30-32

Installation and Setup

Follow these steps to get a local development environment running.

1. Clone the Repository

First, clone the project repository from GitHub to your local machine.

git clone https://github.com/Amery2010/peinture.git
cd peinture

Sources: README.md:36-39

2. Install Dependencies

Next, install the project dependencies defined in package.json using your preferred package manager. The primary dependencies are listed below.

npm install

Sources: README.md:41-43

Dependency	Version	Description
react	^19.2.0	A JavaScript library for building user interfaces.
react-dom	^19.2.0	Serves as the entry point to the DOM.
lucide-react	^0.555.0	A library of simply beautiful icons.
react-zoom-pan-pinch	^3.7.0	Provides zoom, pan, and pinch functionality for elements.
vite	^6.2.0	The build tool and development server.
typescript	~5.8.2	A typed superset of JavaScript.

Sources: package.json:12-20

3. Run the Development Server

Start the Vite development server using the dev script.

npm run dev

This command will start a local server, and you can access the application by navigating to http://localhost:3000 in your web browser. The port is explicitly configured in the Vite settings.

Sources: README.md:45-50, package.json:7, vite.config.ts:8

Application Architecture

The application is a standard client-side React SPA bootstrapped by Vite.

The diagram below illustrates the basic startup flow of the application.

• index.html is the main entry point, loading React and other dependencies.
• index.tsx renders the main App component into the root DOM element.
• App.tsx is the core component that manages application state, user inputs, and orchestrates calls to the image generation services.
• services/hfService.ts contains the logic for communicating with external Hugging Face and Pollinations.ai APIs.

Sources: index.html:101, index.tsx:4, 12, App.tsx

Core Scripts

The package.json file defines the following scripts for development and deployment.

Script	Command	Description
dev	vite	Starts the Vite development server.
build	vite build	Bundles the app for production into the dist folder.
preview	vite preview	Serves the production build locally for previewing.

Sources: package.json:6-10

Configuration

Vite Configuration

The project's build and development server settings are managed in vite.config.ts. Key configurations include:

• Server Port: The development server is configured to run on port 3000.
• Path Alias: An alias @ is configured to point to the project's root directory (.).

Sources: vite.config.ts:8, vite.config.ts:17

Hugging Face API Token

The application can operate using public API quotas. For heavier usage, a personal Hugging Face Read Token can be configured to increase rate limits.

Configuration Steps:

1. Click the Settings icon in the application header.
2. Paste your Hugging Face token into the "Hugging Face Token" input field.
3. Click Save.

The token is stored in the browser's localStorage under the key huggingFaceToken. This token is then included as a Bearer token in the Authorization header for all requests to Hugging Face APIs.

Sources: README.md:100-108, components/SettingsModal.tsx:21, 80, services/hfService.ts:60-66

The following diagram shows the sequence of saving and using the Hugging Face token.

Deployment

As a static Single Page Application (SPA), the project can be deployed to any static hosting provider.

Build Process

First, create a production build of the application.

npm run build

This command compiles and bundles all static assets into a dist directory in the project root.

Sources: README.md:87-91, package.json:8

Hosting

The contents of the dist folder can be uploaded to any static hosting service. The README.md recommends Vercel and Cloudflare Pages, which automatically detect the Vite framework and configure the build settings.

For other static hosts (like Nginx, Apache, or AWS S3), a server-side configuration is required to handle client-side routing. All requests that would normally result in a 404 error must be redirected to index.html.

Sources: README.md:52-53, 55-85, 93-97

The deployment flow is summarized in the diagram below.