543b9208eb
* chore(client): rename function module * chore: allow client to be created multiple times singleton client is not the default but it still present as a compatibility layer * chore: update docs * feat(client): improved result typing * chore: update demo app code * chore: updated reference docs * chore: update proxy code * chore: alpha release * chore: fix lint staged rule * chore: clean-up docs * chore: reference docs updated
103 lines
4.9 KiB
Markdown
103 lines
4.9 KiB
Markdown
# The fal.ai JS client
|
|
|
|
|
|
|
|
|
|
|
|
|
|
## About the Project
|
|
|
|
The fal JavaScript/TypeScript Client is a robust and user-friendly library designed for seamless integration of fal endpoints in Web, Node.js, and React Native applications. Developed in TypeScript, it provides developers with type safety right from the start.
|
|
|
|
## Getting Started
|
|
|
|
The `@fal-ai/client` library serves as a client for fal apps hosted on fal. For guidance on consuming and creating apps, refer to the [quickstart guide](https://fal.ai/docs).
|
|
|
|
### 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 [getting started guide](https://fal.ai/docs) to acquire your credentials, browser existing APIs, or create your custom functions.
|
|
|
|
1. Install the client library
|
|
```sh
|
|
npm install --save @fal-ai/client
|
|
```
|
|
2. Start by configuring your credentials:
|
|
|
|
```ts
|
|
import { fal } from "@fal-ai/client";
|
|
|
|
fal.config({
|
|
// Can also be auto-configured using environment variables:
|
|
credentials: "FAL_KEY",
|
|
});
|
|
```
|
|
|
|
3. Retrieve your function id and execute it:
|
|
```ts
|
|
const result = await fal.run("user/app-alias");
|
|
```
|
|
|
|
The result's type is contingent upon your Python function's output. Types in Python are mapped to their corresponding types in JavaScript.
|
|
|
|
See the available [model APIs](https://fal.ai/models) for more details.
|
|
|
|
### The fal client proxy
|
|
|
|
Although the fal client is designed to work in any JS environment, including directly in your browser, **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 fal APIs. Luckily fal supports that out-of-the-box with plug-and-play proxy functions for the most common engines/frameworks.
|
|
|
|
For example, if you are using Next.js, you can:
|
|
|
|
1. Instal the proxy library
|
|
```sh
|
|
npm install --save @fal-ai/server-proxy
|
|
```
|
|
2. Add the proxy as an API endpoint of your app, see an example here in [pages/api/fal/proxy.ts](https://github.com/fal-ai/fal-js/blob/main/apps/demo-nextjs-page-router/pages/api/fal/proxy.ts)
|
|
```ts
|
|
export { handler as default } from "@fal-ai/server-proxy/nextjs";
|
|
```
|
|
3. Configure the client to use the proxy:
|
|
```ts
|
|
import { fal } from "@fal-ai/client";
|
|
fal.config({
|
|
proxyUrl: "/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](./libs/proxy/) for more details.
|
|
|
|
### The example Next.js app
|
|
|
|
You can find a minimal Next.js + fal application examples in [apps/demo-nextjs-page-router/](https://github.com/fal-ai/fal-js/blob/main/apps/demo-nextjs-page-router).
|
|
|
|
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-page-router` to start the Next.js app (`demo-nextjs-app-router` is also available if you're interested in the app router version).
|
|
|
|
Check our [Next.js integration docs](https://fal.ai/docs/integrations/nextjs) for more details.
|
|
|
|
## Roadmap
|
|
|
|
See the [open feature requests](https://github.com/fal-ai/fal-js/labels/enhancement) 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](https://github.com/fal-ai/fal-js/blob/main/CODE_OF_CONDUCT.md)
|
|
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](https://conventionalcommits.org)
|
|
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](https://github.com/fal-ai/fal-js/labels/good+first+issue), your contribution will be welcome!
|
|
|
|
## License
|
|
|
|
Distributed under the MIT License. See [LICENSE](https://github.com/fal-ai/fal-js/blob/main/LICENSE) for more information.
|