Fleek Functions
Fleek Functions are code snippets that are executed server-side using Fleek Network’s on-chain cloud infrastructure.
These aim to offer a more economical, high-performance, and scalable solution for running server-side code compared to well-known options like Lambda functions, thanks to the Fleek Network architecture.
Fleek Functions make it possible for users to create serverless apps with lightning-fast performance at a much lower cost. Fleek Functions support TypeScript and JavaScript-based functions.
Create a draft function
To create your first Fleek Function, you must first draft the code and then configure the deployment settings accordingly. To follow the instructions, open your terminal, and change directory to your liking.
For our example, we’ll create a file named “my-first-function.js”, you can choose any name:
touch my-first-function.js
Open your favourite text editor and declare a function. We’ll write a simple function that returns the text “Hello world!” -
export const main = (params) => {
return 'hello world';
};
You are obligated to export a main function. The main signifies the entry point for computations or declarations within the file scope. It’ll not compute or operate if you neglect to declare and export it.
To learn more about what the export declaration is, read the MDN Web docs here.
HTTP requests and responses
Every execution of your Fleek Function receives an HttpRequest argument. It represents the HTTP request made to your function. You can find all the relevant information of your request there.
export const main = (params) => {
const { method, path } = params;
return `${method} request to ${path}`;
};
You can respond either with a string, that will be your HTTP response body, or with an HttpResponse to set your response headers or status.
Check out our docs for more information on the APIs available to your Fleek Function code.
Create a Fleek Function
To create a Fleek Function, we utilize the functions command. You can learn how to use it by appending help:
fleek functions help
For our example, we’ll create a function named “my-first-function”.
fleek functions create --name my-first-function
The --name flag takes a new unique identifier of your project list. It should be descriptive to help you identify it at later stage, e.g. if you have to manage a large number of Fleek Functions within a project.
✅ Success! The function has been successfully created.
> You can create a new deployment using the following command
> Fleek functions deploy
A few examples of valid syntax identifier names are calculator, my-custom-function or add_2. A name does not have to be the same as the function file name, or the export name. A good practice can be to name it in accordance to your project conventions.
Deploy a Fleek Function
At this stage you should have created a draft function file in your local file system and a Fleek Function via the Fleek Platform CLI.
To deploy the Fleek Function, we’ll use the sub-command deploy. You can learn about it by appending help to the functions command.
fleek functions help
In order to deploy a Fleek Function, we need to provide a name and a file path.
In our example, we’ve titled our draft function file “my-first-function.js” and created a Fleek Function called “my-first-function”. It’s important to note that we had the choice to give them different names as the file and Fleek Function names don’t have to match.
Here, we’ll pass those values as arguments to the —name and —path flag.
fleek functions deploy \
--name my-first-function \
--path ~/some/path/my-first-function.js
The response should be similar to:
✅ Success! The deployment has been successfully created.
> You can call this Fleek Function by making a request to the following URL
🤖 Make a request to the following URL
🔗 https://<SLUG>.functions.dev.on-fleek-test.app
Given that our function is a basic ‘Hello World’ program and doesn’t require any parameters, visit the provided invoke URL to execute your function code. However, keep in mind that the functions are deployed into IPFS, requiring a grace period for propagation.
List Fleek Functions
To display all the Fleek Functions you’ve deployed in your Fleek project, execute the following command:
fleek functions list
This command will output a table showing the ID, name, slug, and Fleek Function invocation URL for each of your Fleek Functions.
Update Fleek Functions
To update the source code for a Fleek Function, you’ll have to edit the draft file and re-deploy it, preferencly to the same Fleek Function name. It’s expected, to push edits to the same Fleek Function name to work iteratively.
But since the code for a particular deployment of a Fleek Function is immutable, every update will cause the Fleek Function ID to change. Although, the Slug URL associated to access the resource will remain the same.
Thus, to view a list of all deployments for a function, run the following command:
fleek function deployments --name <Fleek Function Name>
For our example, we’d run:
fleek function deployments --name my-first-function
We can verify that the ID and CID change per deployment of different function iterations.
ID CID Created At
------------------------------------------
clv...1ex baf...h1z 2024-04-22
clv...qb2 baf...un2 2024-02-14
clv...y3l baf...3st 2024-01-06
Content addressing is where we use a hash to access the content, and it allows us to verify that the content we received is the content we asked for. This is one of the principles that help us provide guarantees to end-users who require a high ability for content verification; As a consequence, the immutability of files is critical to this system powered by Fleek Network.
Thus, it’s crucial to remember that the functions are deployed into IPFS, requiring a period for propagation.
Interact with Fleek Functions
To interact with Fleek Functions, you can send requests to the Fleek Function URL using a variety of HTTP methods, such as GET and POST.
Here’s the syntax for simple HTTP GET request via cURL:
curl -X GET \
https://<SLUG>.functions.stg.on-fleek-test.app
Limitations
When writing code for your functions, please keep in mind Fleek Functions currently have a timeout of 15 seconds, and a memory limit of 50 MiB during execution.
Modify properties
After the deployment of a Fleek Function, you can edit the following properties:
- Status: Can switch between ACTIVE or INACTIVE state
- Name: Modify the unique identifier term listed in the project
- Slug: The alias utilized to access the specific function resource
Update the name or slug
You might find it necessary to rename an existing Fleek Function, e.g. if the code it executes now diverges from its initial purpose or to improve clarity.
To modify the name, run:
fleek functions update \
--functionName <NAME> \
--name <NEW-NAME>
As an example, we can modify the name we opted for this demo “my-first-function” to “my-function”.
fleek functions update \
--functionName my-first-function \
--name my-function
Similarly, you can modify the “slug” of the Fleek Function by utilizing the flag —slug instead of —name.
fleek functions update \
--functionName <NAME> \
--slug <NEW-SLUG>
For example, let’s say that the Fleek Function URL we got for the demo “my-first-function” is:
https://big-coffeeshop-little.functions.stg.on-fleek-test.app
If we’d like to modify the slug “big-coffeeshop-little” to another available name, we’d run:
fleek functions update \
--functionName my-first-function \
--slug my-unique-slug
Afterwards, we could interface with our Fleek Function via the URL:
https://my-unique-slug.functions.stg.on-fleek-test.app
Assets
Assets are files that are uploaded alongside your Fleek Function to IPFS and can be accessed by your function code. You can access the IPFS CID of the assets using the fleek.env.ASSETS_CID environment variable.
These assets are useful for storing static files that your function code needs to access, such as images, videos, or other resources. You can upload assets by passing the path to the assets directory using the --assets <path> flag when deploying your Fleek Function.
fleek functions deploy --name my-function --path ./function.js --assets ./assets
To fetch the assets in your function code, you can make a simple HTTP request to our IPFS gateway:
// Example: Fetching an image from your assets
const response = await fetch(
`https://${fleek.env.ASSETS_CID}.flk-ipfs.xyz/images/logo.png`,
);
const imageData = await response.arrayBuffer();
Using private data with Fleek Functions
You can make use of environment variables through any combination of the following:
- Those set within your CLI
- Those imported from a separate file
- Those exported into your local environment
Environment variables set within your CLI
You can pass -e or --env flags to the CLI in order to set simple, non-array environment variables from within the CLI. For example, the following code would set VAR1 as ‘foo’ and VAR2 as ‘bar’ for use within your Fleek Function.
fleek functions deploy --name print-hello-world --path *./function.js --env VAR1='foo' --env VAR2='bar'
Environment variables imported from a separate file
Additionally, you can pass a --envFile flag to the CLI, followed by a file location relative to the current directory, in order to load environment variables from a file. This file should represent variables using a key value pair syntax.
# This is a comment
PORT=3000 # This is also a comment
NAME="Some value"
MULTI_LINE="THIS IS
A MULTILINE"
In the example below, the user’s environment variables are located in an env.list file.
fleek functions deploy --name print-hello-world --path *./function.js --envFile ./env.list
Environment variables exported to your local environment
Lastly, you can use variables exported to your local environment.
If you have exported a variable to your environment with export VAR1=‘foo’and export VAR2=‘bar’, e.g., you can run:
fleek functions deploy --name print-hello-world --path *./function.js --env VAR1 --env VAR2
Using your environment variables
Your environment variables are available under fleek.env. You can test it out with the following function:
export const main = (params) => {
const foo = fleek.env.FOO;
return `foo=${foo}`;
};
Making Fleek Functions private (🧪 Alpha)
If you are interested in making your Fleek Function code private, add the --private flag to your deployment command:
fleek functions deploy --name print-hello-world --path *./function.js --private
Deactivate functions
To deactivate such a Fleek Function, you can run the command below, replacing <fleek_function_name> with the name of the Fleek Function you’re deactivating.
To deactivate a Fleek Function, use the command below:
fleek functions update \
--functionName <NAME> \
--status <STATUS>
As demonstrated in the Managing Fleek Functions table, the available status are ACTIVE or INACTIVE. So, let’s say that we’d like to deactivate the “my-first-function”.
You’d want to run:
fleek functions update \
--functionName my-fleek-function \
--status INACTIVE
If successful, a response should be expected, as follows:
✅ Success! The function has been successfully updated.
Through this action, we’ve deactivated a Fleek Function, choosing not to delete it.
To reactivate a Fleek Function you previously activated, simply run the same command but with the status set to ACTIVE.
Delete a Fleek Function
If you determine that a Fleek Function is no longer useful to you or your project, you can delete it outright by running the following command:
fleek functions delete --name <fleek_function_name>
Should you decide that a Fleek Function is no longer useful to your project, you can delete it by executing the following command:
fleek functions delete \
--name <NAME>
For example, let’s delete the Fleek Function named “my-first-function”:
fleek functions delete \
--name my-first-function
On completion, you’d get a confirmation message:
✅ Success! The function has been successfully deleted.