Tom Boullay
89 lines
2.5 KiB
Markdown
89 lines
2.5 KiB
Markdown
# upload-GLTF
|
|
|
|
A secure web interface for uploading 3D assets (GLTF/GLB + textures) and automatically pushing them to a GitHub repository via the GitHub API. Built for La Fabrik Durable.
|
|
|
|
## Stack
|
|
|
|
- **Next.js 16** (App Router) + React 19 + TypeScript
|
|
- **Three.js** (@react-three/fiber + @react-three/drei) for 3D preview
|
|
- **Tailwind CSS** for styling
|
|
- **Octokit** for pushing via the GitHub API
|
|
- **Vercel** for hosting
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
git clone https://github.com/La-Fabrik-Durable/upload-GLTF.git
|
|
cd upload-GLTF
|
|
npm install
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Copy `.env.example` to `.env.local` and fill in the values:
|
|
|
|
```env
|
|
UPLOAD_SECRET_KEY=your-secret-key-here
|
|
GITHUB_TOKEN=ghp_your-github-personal-access-token
|
|
GIT_BRANCH=main
|
|
GIT_REPO_URL=https://github.com/your-org/your-repo.git
|
|
```
|
|
|
|
| Variable | Description | Required |
|
|
|----------|-------------|----------|
|
|
| `UPLOAD_SECRET_KEY` | Secret key for upload authentication | Yes |
|
|
| `GITHUB_TOKEN` | GitHub Personal Access Token (scope `repo`) | Yes |
|
|
| `GIT_BRANCH` | Target branch (default: main) | No |
|
|
| `GIT_REPO_URL` | Target GitHub repository URL | Yes |
|
|
|
|
> To create a token: GitHub > Settings > Developer settings > Personal access tokens > Generate new token (classic) with the `repo` scope.
|
|
|
|
## Usage
|
|
|
|
### Development
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
Access the app at `http://localhost:3000`
|
|
|
|
### Production (Vercel)
|
|
|
|
Deploy to Vercel and configure environment variables in the dashboard.
|
|
|
|
## How it works
|
|
|
|
1. The user enters their access key
|
|
2. They select a folder containing:
|
|
- `model.glb` or `model.gltf` (required)
|
|
- Textures: `roughness`, `normal`, `metalness`, `color`, `displace` (`.png/.jpg/.webp`, optional)
|
|
3. The model is displayed in a 3D preview
|
|
4. On clicking "Upload & Push to GitHub", each file is sent to the `/api/upload` endpoint
|
|
5. The API validates the file and pushes it directly to the GitHub repo via the API (no git CLI needed)
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
app/
|
|
├── api/upload/route.ts # API: validation + GitHub push via Octokit
|
|
├── globals.css # Tailwind + Google Fonts
|
|
├── layout.tsx # Root layout
|
|
└── page.tsx # Home page
|
|
components/
|
|
├── UploadZone.tsx # UI: key input, folder picker, validation, upload
|
|
├── ModelViewer.tsx # Lazy wrapper for the 3D viewer
|
|
└── SceneViewer.tsx # Three.js Canvas
|
|
```
|
|
|
|
## Supported Formats
|
|
|
|
| Type | Extensions |
|
|
|------|------------|
|
|
| 3D Models | `.glb`, `.gltf` |
|
|
| Textures | `.png`, `.jpg`, `.jpeg`, `.webp` |
|
|
|
|
## License
|
|
|
|
MIT
|