@rsemihkoca/fal-extended

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

📦 One Package, Two Powers

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

Client-Side (Browser/React/Vue/etc)

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}`);
    }
  }
});

Server-Side (Express/Next.js/etc)

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

// 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

Client Features

• ✅ 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

Proxy Features

• ✅ 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

React with Progress Bar

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 (
    <div>
      <progress value={progress} max={100} />
      <p>{status}</p>
    </div>
  );
}

Complete Server Setup

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}`);
});

Environment Variables

# .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:

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

❌ Wrong:

// 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

Next.js App Router

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

Hono

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:

// 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