The fal.ai JS client

About the Project

The fal-serverless JavaScript/TypeScript Client is a robust and user-friendly library designed for seamless integration of fal serverless functions in Web, Node.js, and React Native applications. Developed in TypeScript, it provides developers with type safety right from the start.

Getting Started

The serverless-js library serves as a client for fal serverless Python functions. For guidance on creating your functions, refer to the quickstart guide.

Client Library

This client library is crafted as a lightweight layer atop platform standards like fetch. This ensures a hassle-free integration into your existing codebase. Moreover, it addresses platform disparities, guaranteeing flawless operation across various JavaScript runtimes.

Note: Ensure you've reviewed the fal-serverless getting started guide to acquire your credentials and register your functions.

1. Start by configuring your credentials:

import * as fal from '@fal-ai/serverless-js';

fal.config({
  // Can also be auto-configured using environment variables:
  // Either a single FAL_KEY or a combination of FAL_KEY_ID and FAL_KEY_SECRET
  credentials: 'FAL_KEY_ID:FAL_KEY_SECRET',
});

2. Retrieve your function id and execute it:

const result = await fal.run('my-function-id');

The result's type is contingent upon your Python function's output. Types in Python are mapped to their corresponding types in JavaScript.

The fal client proxy

Although the fal client is designed to work in any JS environment, including client-side, it is not recommended to store your credentials in your client source code. The common practice is to use your own server to serve as a proxy to serverless APIs. Luckily fal supports that out-of-the-box with plug-and-play proxy functions for the most common engines/framrworks.

For example, if you are using Next.js, you can:

1. Instal the proxy library npm install --save @fal-ai/serverless-proxy
2. Add the proxy as an API endpoint of your app, see an example here in pages/api/_fal/proxy.ts

   export { handler as default } from '@fal-ai/serverless-proxy/nextjs';

3. Configure the client to use the proxy:

   import * as fal from '@fal-ai/serverless-js';
   fal.config({
     requestMiddleware: fal.withProxy({
       targetUrl: '/api/_fal/proxy',
     }),
   });

4. Make sure your server has FAL_KEY as environment variable with a valid API Key. That's it! Now your client calls will route through your server proxy, so your credentials are protected.

See libs/proxy for more details.

The example Next.js app

You can find a minimal Next.js + fal application examples in apps/demo-nextjs-app/.

1. Run npm install on the repository root.
2. Create a .env.local file and add your API Key as FAL_KEY environment variable (or export it any other way your prefer).
3. Run npx nx serve demo-nextjs-app to start the Next.js app.

Roadmap

See the open feature requests for a list of proposed features and join the discussion.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Make sure you read our Code of Conduct
2. Fork the project and clone your fork
3. Setup the local environment with npm install
4. Create a feature branch (git checkout -b feature/add-cool-thing) or a bugfix branch (git checkout -b fix/smash-that-bug)
5. Commit the changes (git commit -m 'feat(client): added a cool thing') - use conventional commits
6. Push to the branch (git push --set-upstream origin feature/add-cool-thing)
7. Open a Pull Request

Check the good first issue queue, your contribution will be welcome!

License

Distributed under the MIT License. See LICENSE for more information.