Skip to main content
This guide will cover how to create a new data collection component, compile it to WebAssembly, test it locally, and push it to the Edgee Component Registry. Before diving into this guide, we highly recommend reviewing these foundational concepts and completing the CLI setup. Data collection components are powered by WebAssembly and allow you to deliver events to analytics platforms and data services. Each data collection component is configured with the settings and credentials needed to send data to a specific service and runs in a sandboxed environment with limited access to OS functionalities.

​
How to create a new data collection component

​
Component bootstrapping

Run edgee components new to create a new data collection component and choose your preferred programming language. This creates a local folder containing sample code and tools to help you get started quickly. 
$ edgee components new
? Enter the component name: my-component
? Select a programming language:
  C
  CSharp
  Go
  JavaScript
  Python
> Rust
  TypeScript
? Select component type:
> Data Collection
  Edge Function
 INFO Downloading sample code for Rust...
 INFO Extracting code...
 INFO Downloading WIT files...
 INFO New project my-component is ready! Check README for dependencies.
Navigate to the new folder to begin customizing your component and implementing its business logic.

​
Component manifest file

Your component’s manifest file is named 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 looks like this: 
manifest-version = 1

[component]
name = "Your Component Name"
slug = "your-component-name"
version = "0.0.1"
language = "Rust"
category = "data-collection"
subcategory = "analytics"
description = "Your component description"
documentation = "https://example.com/link-to-your-documentation"
repository = "https://github.com/your-account/your-repository"
icon-path = "path-to-local-file.png"
wit-version = "1.0.0"

[component.build]
command = "your-build-command"
output-path = "./dc_component.wasm"

[component.settings.example-api-key]
title = "Your API Key"
type = "string"
required = true
secret = true
description = "The API key you need for this component to work"

[component.settings.example-choice]
title = "Your choice setting"
type = "string"
required = true
options = ["value1", "value2", "value3"]
Let’s go through each section and field:
  • 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: the only available value for data collection components is data-collection.
    • subcategory: the available values for now are analytics, warehouse, and attribution.
    • 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.
If you started via 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.

​
Implementing your component

A data collection component must implement the following WIT interface: 
page: func(e: event, settings: dict) -> result<edgee-request, string>;
track: func(e: event, settings: dict) -> result<edgee-request, string>;
user: func(e: event, settings: dict) -> result<edgee-request, string>;
The corresponding method is invoked when a page, track or user event is sent for data collection by the Edgee proxy. These methods receive the incoming event object and a set of settings. They’re expected to return an edgee-request object, which looks like this: 
record edgee-request {
    method: http-method,
    url: string,
    headers: dict,
    forward-client-headers: bool,
    body: string,
}
If you’re curious to dive deeper into the WIT definitions, check out the repository on GitHub. Based on the programming language you chose, you’ll find the corresponding types and unit tests to help you with the implementation. In case you’re having trouble with implementing your component, check out other existing components such as Google Analytics, Segment, Amplitude, Meta CAPI, LinkedIn CAPI, or Amazon S3.
Note: Edgee components don’t perform HTTP calls directly, as they run in a sandboxed environment with no access to network or file system. The intended purpose of a component is to instruct the proxy on which HTTP request to perform to fullfil its data collection duties.For example, the Google Analytics component returns an edgee-request object that points to the official https://www.google-analytics.com/g/collect endpoint, with the correct querystring parameters. Similarly, the Amazon S3 component points to https://{bucket}.s3.amazonaws.com with the correct sigv4 authentication headers.

​
Reusability and settings

To make your Edgee component reusable for other developers and organizations via the Edgee Component Registry, you can define a set of input settings, containing all the API credentials or dynamic information you need to craft the correct edgee-request object. For example, the Google Analytics component only expects a ga_measurement_id setting, while the Segment component expects segment_project_id and segment_write_key. You can configure the expected settings for your component by adding the following for each setting in your manifest file: 
[component.settings.example-name]
title = "Your Pretty Name"
type = "string|number|bool"
required = true|false
description = "Your setting's description"
options ["value1", "value2", "value3"]
secret = true|false
Note: only 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 dict.
Note: even if defined as 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.

​
Build and test locally

When the implementation is ready, compile your component into Wasm: 
$ edgee components build
You can customize the behavior of the build command in the manifest file by changing the target file name and the default build script. If you’ve created a new component with 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.
Note: the Edgee CLI is intended to simplify and make local development uniform across programming languages and component types.While some of the compiling details are still visible today because of long multi-step commands or additional support scripts, our long-term goal is to hide most of that complexity behind edgee components build in the future.For example, you need to explicitly configure debug flags for your preferred language:
  • Rust components use 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)
  • C components use clang to compile the Wasm file with the -Os flag by default, but you can change this to -O0 in your manifest file.
  • Go components include debug symbols by default, but you can add the -no-debug flag to disable them and optimize the size and performance of your Wasm file.
Before pushing your component to the Edgee Component Registry, it’s highly recommended to validate and test the Wasm file locally: 
# validate local Wasm file (this automatically runs on push)
$ edgee components check

# test all event types (page, track, user) with no settings
$ edgee components test
Use the test command to run your local Wasm file with a sample event and provided settings. If no --event-type is provided, it will run the Wasm file with all event types (page, track, and user). This helps ensure your component behaves as expected from the proxy’s perspective, in addition to your unit tests.

​
Using test events

Test events represent the typical structure of an Edgee event. For example, the sample page event looks like the following: 

{
    "uuid": "37009b9b-a572-4615-87c1-09e257331ecb",
    "timestamp": "2025-02-03T15:46:39.283317613Z",
    "type": "page",
    "data": {
        "keywords": [
            "demo",
            "tag manager"
        ],
        "title": "Page with Edgee components",
        "url": "https://demo.edgee.app/analytics-with-edgee.html",
        "path": "/analytics-with-edgee.html",
        "referrer": "https://demo.edgee.dev/analytics-with-js.html"
    },
    "context": {
        "page": {
            "keywords": [
                "demo",
                "tag manager"
            ],
            "title": "Page with Edgee components",
            "url": "https://demo.edgee.app/analytics-with-edgee.html",
            "path": "/analytics-with-edgee.html",
            "referrer": "https://demo.edgee.dev/analytics-with-js.html"
        },
        "user": {
            "edgee_id": "6bb171d5-2284-41ee-9889-91af03b71dc5"
        },
        "client": {
            "ip": "127.0.0.1",
            "locale": "en-us",
            "accept_language": "en-US,en;q=0.9",
            "timezone": "Europe/Paris",
            "user_agent": "Mozilla/5.0 (X11; Linux x86_64)AppleWebKit/537.36 (KHTML, like Gecko) Chrome/132.0.0.0 Safari/537.36",
            "user_agent_version_list": "Not A(Brand;8|Chromium;132",
            "user_agent_mobile": "0",
            "os_name": "Linux",
            "user_agent_architecture": "x86",
            "user_agent_bitness": "64",
            "user_agent_full_version_list": "Not A(Brand;8.0.0.0|Chromium;132.0.6834.159",
            "user_agent_model": "",
            "os_version": "6.12.11",
            "screen_width": 1920,
            "screen_height": 1280,
            "screen_density": 1.5
        },
        "session": {
            "session_id": "1738597536",
            "session_count": 1,
            "session_start": false,
            "first_seen": "2025-02-03T15:45:36.569004889Z",
            "last_seen": "2025-02-03T15:46:39.278740029Z"
        }
    }
}
Please note that you don’t need to manually parse the input event in your business logic. Your handlers will receive it in the form of a native object in your language of choice, thanks to Wasm/WIT’s code generation.
Test events are static objects for now. In the near future, you’ll be able to provide a custom JSON object that better suits your component’s needs.

​
Test HTTP requests

By default, the test command runs your local Wasm file and prints out the resulting edgee-request object. Once you’re happy with the implementation, you can bring your testing one step forward and use the CLI to run the actual HTTP request for you: 
$ edgee components test [options] --make-http-request
Alternatively, if you prefer running the HTTP request yourself, generate the corresponding cURL command: 
$ edgee components test [options] --curl
Note: we recommend using test or staging environments whenever possible to avoid logging test data into production systems or analytics APIs.

​
Push to the registry

When your component is ready for some action, it’s time to push it to the registry. Make sure you went through these steps so far:
  1. Installed and configured the Edgee CLI
  2. Implemented the Edgee WIT interface
  3. Updated your manifest file with the correct build command and settings
  4. Validated the Wasm file with local tests
  5. Decided on the component’s visibility (public or private)
Then run the following command: 
$ edgee components push
 INFO Component org/name does not exists yet!
> Confirm new component creation? Y/n
? Would you like to make this component public or private?
> private
  public
> Describe the new version changelog (optional) [(e) to open nano, (enter) to submit]
> Ready to push org/name@version. Confirm? Y/n
 INFO Uploading Wasm file...
 INFO Creating new version...
 INFO org/name@version pushed successfully!
 INFO URL: https://www.edgee.cloud/~/registry/{organization}/{component}
Your new component will be pushed to the Edgee Component Registry under your Organization. In case your Edgee user is part of multiple Organizations, you can provide the organization identifier via edgee components push ORG_ID. Congratulations! Your 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}.

​
Publish/unpublish components

A public component is visible to anyone in the registry, while private components are only available to a specific organization. During the initial push, you decide between private or public. Every subsequent push command will keep the same visibility. If you need to publish a private component or unpublish a public component after the initial push, you’ll need to declare the visibility change explicitly: 
$ edgee components push --public
Note: unpublishing a public component is only possible as long as the component isn’t used by any project. You can still push the same component as private for a specific organization. This might be useful for special use cases where a component needs ad-hoc customizations.

​
Archive/delete components

After pushing, visit 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:
  • Archived components become invisible on public pages, but can be unarchived. Existing projects using an archived component still work fine.
  • Deleted components simply stop existing and this action is irreversible. If there is at least one Edgee project using a component, you cannot delete it.
Note: even though the web console allows you to edit most fields and creeate new versions, we recommend using the Edgee CLI to push updates and new versions. This way, your manifest file remains the source of truth.

​
Use the component

Once your component is available via the Edgee Component Registry, you can add it to a project and it will start receiving events. First of all, you’ll need to create a project, configure it for your website, and then install the Edgee SDK. To simplify the setup, we recommend using the default Edgee-generated domain and keep routing settings as simple as possible. Visit the Components section of your project and click Add a component. Here you can filter by category, organization, and visibility. Make sure to select Private in the bottom-left if you pushed a private component. Select your component and configure it. A few things to keep in mind:
  1. You can select a specific version of your component, by default the latest version is selected.
  2. Enable Auto update if you want to automatically use the latest version of your component for this project.
  3. If your component only support specific events, disable any unsupported event in the Event Activation section.
Once the project is set up and your component is active, you can start generating page events by visiting your website. The Edgee SDK automatically tracks pageviews by default. If you want to test track events and user events as well, you can use the Edgee SDK: 
edgee.track({
    "name": "event name",
    "properties": {
        "key": "value"
    }
});
Alternatively, enable SDK autocapture for your projects and all events will be collected automatically.
⌘I