@rsemihkoca/fal-extended

All-in-one fal.ai package with client and server proxy including upload progress tracking.

📦 One Package, Two Powers

``bash
npm install @rsemihkoca/fal-extended
`

This single package includes:
- 🎯 Client - Browser/Node.js client with upload progress
- 🔒 Proxy - Server proxy with storage handlers

🚀 Quick Start

$3

`typescript
import { fal } from '@rsemihkoca/fal-extended';

// Configure with your proxy
fal.config({
proxyUrl: 'http://localhost:3000/api/fal/proxy'
});

// Upload with progress
const url = await fal.storage.upload(file, {
onProgress: (e) => {
console.log(${e.progress}% - ${e.type});
if (e.currentPart) {
console.log(Part ${e.currentPart}/${e.totalParts});
}
}
});
`

$3

`typescript
import express from 'express';
import * as fal from '@rsemihkoca/fal-extended/proxy/express';

const app = express();
app.use(express.json());

// Single line setup!
app.use(${fal.route}/storage/upload, fal.storageHandler);
app.use(fal.route, fal.handler);

app.listen(3000);
`

📚 Import Paths

`typescript
// Client
import { fal } from '@rsemihkoca/fal-extended';
// or
import { fal } from '@rsemihkoca/fal-extended/client';

// Proxy - Express
import * as fal from '@rsemihkoca/fal-extended/proxy/express';

// Proxy - Next.js
import * as fal from '@rsemihkoca/fal-extended/proxy/nextjs';

// Proxy - Hono
import * as fal from '@rsemihkoca/fal-extended/proxy/hono';

// Proxy - Core
import * as fal from '@rsemihkoca/fal-extended/proxy';
`

✨ Features

$3

- ✅ All original fal.ai client APIs
- 🆕 Upload progress callbacks
- 🆕 Multipart upload progress (>90MB files)
- 🆕 Real-time upload tracking
- 🆕 Part-by-part progress for large files

$3

- ✅ All original proxy features
- 🆕 Storage upload handlers
- 🆕 Single handler design
- 🆕 Automatic multipart detection
- 🆕 Secure credential handling
- 🆕 Framework support (Express, Next.js, Hono, Remix, SvelteKit)

📖 Examples

$3

`typescript
import { fal } from '@rsemihkoca/fal-extended';
import { useState } from 'react';

function FileUploader() {
const [progress, setProgress] = useState(0);
const [status, setStatus] = useState('');

const handleUpload = async (file: File) => {
const url = await fal.storage.upload(file, {
onProgress: (e) => {
setProgress(e.progress);
setStatus(e.currentPart
? Uploading part ${e.currentPart}/${e.totalParts}
: e.type
);
}
});

return url;
};

return (



);
}
`

$3

`typescript
import express from 'express';
import cors from 'cors';
import * as fal from '@rsemihkoca/fal-extended/proxy/express';

const app = express();

// Middleware
app.use(cors());
app.use(express.json());

// Logging (optional)
app.use((req, res, next) => {
console.log(${req.method} ${req.url});
next();
});

// fal.ai routes
app.use(${fal.route}/storage/upload, fal.storageHandler);
app.use(fal.route, fal.handler);

// Start server
app.listen(3000, () => {
console.log('🚀 Proxy server running on http://localhost:3000');
console.log(📡 Storage endpoint: ${fal.route}/storage/upload);
console.log(📡 General proxy: ${fal.route});
});
`

$3

`bash


.env

FAL_KEY=your-fal-key-here

Or use separate key ID and secret

FAL_KEY_ID=your-key-id
FAL_KEY_SECRET=your-key-secret
`

🔐 Security

NEVER expose FAL_KEY in the browser!

✅ Correct:
`typescript
// Client - uses proxy (credentials stay on server)
fal.config({ proxyUrl: 'https://your-server.com/api/fal/proxy' });
`

❌ Wrong:
`typescript
// Client - exposes credentials!
fal.config({ credentials: 'fal-key-xxx' });
`

📊 Upload Flow

`
┌──────────┐ ┌─────────┐ ┌────────┐
│ Client │─────────────────▶│ Proxy │────────────────▶│ fal.ai │
│ (Browser)│ No credentials │ (Server)│ With FAL_KEY │ API │
└──────────┘ └─────────┘ └────────┘
│ │
│ ◀───── signed URL ──────────┤
│
▼
┌──────────┐
│ Storage │ Direct upload (S3/CDN)
│ (Fast!) │ No proxy overhead!
└──────────┘
`

📄 Documentation

- Client README
- Proxy README
- Storage Upload Guide

🔗 Framework Examples

$3

`typescript
// app/api/fal/[[...path]]/route.ts
export { GET, POST, PUT, DELETE } from '@rsemihkoca/fal-extended/proxy/nextjs';
`

$3

`typescript
import { Hono } from 'hono';
import * as fal from '@rsemihkoca/fal-extended/proxy/hono';

const app = new Hono();
app.use(${fal.route}/storage/upload/*, fal.storageHandler);
app.use(${fal.route}/*, fal.handler);
`

📦 Package Size

This package includes both client and proxy code. If you only need one:

`typescript
// Tree-shaking will remove unused code in production builds

// Only import what you need
import { fal } from '@rsemihkoca/fal-extended/client'; // Client only
import * as fal from '@rsemihkoca/fal-extended/proxy/express'; // Proxy only
``

🆚 Comparison

| Feature | Original fal.ai | @rsemihkoca/fal-extended |
|---------|----------------|--------------------------|
| Basic client | ✅ | ✅ |
| Server proxy | ✅ | ✅ |
| Upload progress | ❌ | ✅ |
| Multipart progress | ❌ | ✅ |
| Storage handlers | ❌ | ✅ |
| Single handler | ❌ | ✅ |

📜 License

MIT

🤝 Contributing

Based on @fal-ai/client. Contributions welcome!

🐛 Issues

Report issues at: https://github.com/rsemihkoca/fal-extended/issues