How to build, test, and push edge function components
edgee components new
to create a new edge function component and choose your preferred programming language.
This creates a local folder containing sample code and tools to help you get started quickly.
edgee-component.toml
. It contains all the information required to
build, test, and push your component via the Edgee CLI.
Components created via edgee components new
already include a default manifest you can easily customize.
In case you prefer managing the local folder and starting from a blank implementation, feel free to use
edgee components init
to initialize an empty manifest in the current folder.
A typical manifest file for an edge function component looks like this:
manifest-version
: it indicates the expected structure of your manifest file, the only available value for now is 1
.
[component]
: here you define what your component is all about, including its public name and latest version
name
: the name of this component, will be used for URLs and shown on public pages.slug
: the slug of this component, will be used for URLs and shown on public pages.
Note: the slug is used as an identifier by the CLI (for a given organization).
In other words, if you change a component’s slug, you will create a brand new component.
A slug should change only when absolutely necessary.version
: the latest version of this component, will be used when pushing to update or create versions.language
: the programming language used this component, will be used to automate some language-specific
build or compilation details. It’s automatically configured if you start with a starter template.category
: for edge function components, the value should be edge-function
.subcategory
: the available value is wasm-function
.description
: the description of this component, will be shown on public pages.documentation
: the documentation URL for this component (could also point to a public repository).repository
: the repository URL for this component (e.g. on GitHub).icon-path
: the image used on public pages to represent this component.wit-version
: the WIT interface implemented by this component. When a new WIT version is available,
update this field to the latest version and the Edgee CLI will take care of updating all WIT dependencies for you.[component.build]
: here you define how the component is built and where the resulting Wasm file is located.
command
: the command to compile this component into Wasm, depends on your programming language of choice.output-path
: the local file path where your compiled Wasm binary is stored, will be used for local testing and pushing
(make sure this is aligned with the build command defined above).[component.settings.X]
: here you define as many settings as needed (see Reusability and settings below)
title
: text that will be shown in the web console to identify this setting.type
: valid values are string
, number
, or bool
.required
: (optional) a bool value to indicate whether this setting is required or not, false by default.description
: (optional) text that will be shown in the web console to describe this setting.options
: (optional) the allowed values for this setting.secret
: (optional) a bool value to indicate whether this setting value should be encrypted, false by default.edgee components new
, most fields come with good defaults and you only need to customize
your component’s name, description, documentation URL, repository URL, and settings.
wasi:http/incoming-handler@0.2.0
to handle incoming HTTP requestswasi:http/outgoing-handler@0.2.0
to make outgoing HTTP requests (if needed)x-edgee-component-settings
HTTP header, encoded as JSON.
Don’t worry, this is already implemented in the sample code provided when using edgee components new
.
edgee_path
: exact path match such as /api/auth
.edgee_path_prefix
: path prefix match such as /api/
(both /api/users
and /api/posts
will match).settings
, containing all the configuration parameters,
API credentials, or dynamic information needed for your edge function to operate correctly.
For example, a simple API edge function might expect api_key
and allowed_origins
,
while a content serving edge function might expect content_type
and template_id
.
You can configure the expected settings for your component by adding the following for each setting in your manifest file:
title
and type
are mandatory to define a setting.
In this case, example-name
is the key your business logic will use to get its value from the settings.number
or bool
, all settings are treated as strings when your component receives them.
For now, you’ll need to parse them into the correct type. In the future, our WIT definitions will handle types automatically as well.x-edgee-component-settings
HTTP header.
The sample code provided when using edgee components new
already provides some utility code to parse
headers, settings, and body from the incoming HTTP request.
For example:
edgee components new
the default build script
should be a great starting point. By default, the output of this command will be a new Wasm file in the current folder.
edgee components build
in the future.For example, you need to explicitly configure debug flags for your preferred language:cargo build --release
by default,
but you can enable debugging symbols by removing the --release
flag from the build command in your manifest file.
(Please note that this will increase the size of your Wasm file considerably, up to 40x)clang
to compile the Wasm file with the -Os
flag by default,
but you can change this to -O0
in your manifest file.-no-debug
flag to disable them and optimize
the size and performance of your Wasm file.--watch
flag to automatically rebuild your component on source code changes.x-edgee-component-settings
header.
edgee components push ORG_ID
.
Congratulations! Your edge function component is now available on the Edgee Component Registry at https://www.edgee.cloud/{organization}/{component}
.
In case you pushed a private component, its page is only visible to you.
You can also view and edit it at https://www.edgee.cloud/~/registry/{organization}
.
https://www.edgee.cloud/~/registry/{organization}
and select your component to edit it.
Here you can archive or delete it with the corresponding buttons.
Please note that:
edgee_path
: For exact path matches (e.g., /api/auth
)edgee_path_prefix
: For path prefix matches (e.g., /api/
matches all paths starting with /api/
)