> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/trailbaseio/trailbase/llms.txt
> Use this file to discover all available pages before exploring further.

# WASM Components

> Managing WebAssembly components via CLI

## Overview

TrailBase supports WebAssembly (WASM) components for extending server functionality. The CLI provides commands to add, remove, list, and update WASM components.

## Component Management

### Component References

WASM components can be referenced in three ways:

<ParamField path="Name" type="string">
  First-party component name from the official registry.

  **Format:** `namespace/component-name` (e.g., `trailbase/auth_ui`)

  Must contain only alphanumeric characters, `_`, `-`, or `/`
</ParamField>

<ParamField path="URL" type="string">
  HTTPS URL pointing to a `.wasm` or `.zip` file.

  **Format:** `https://example.com/component.wasm`

  Only HTTPS is supported for security reasons
</ParamField>

<ParamField path="Path" type="string">
  Local filesystem path to a `.wasm` or `.zip` file.

  **Format:** `./path/to/component.wasm` or `/absolute/path/component.zip`
</ParamField>

## Adding Components

### components add

Install a WASM component from a name, URL, or local path.

```bash theme={null}
trail components add <REFERENCE>
```

<ParamField path="reference" type="string" required>
  Component reference (name, URL, or path).
</ParamField>

<CodeGroup>
  ```bash First-party Component theme={null}
  trail components add trailbase/auth_ui

  # Output:
  # Downloading https://github.com/trailbaseio/trailbase/releases/download/v0.1.0/trailbase_v0.1.0_wasm_auth_ui.zip
  # Added: ["./traildepot/wasm/auth_ui_component.wasm"]
  ```

  ```bash From HTTPS URL (.wasm) theme={null}
  trail components add https://example.com/custom_component.wasm

  # Output:
  # Downloading https://example.com/custom_component.wasm
  # Added: ["./traildepot/wasm/custom_component.wasm"]
  ```

  ```bash From HTTPS URL (.zip) theme={null}
  trail components add https://example.com/components.zip

  # Output:
  # Downloading https://example.com/components.zip
  # Added: ["./traildepot/wasm/component1.wasm", "./traildepot/wasm/component2.wasm"]
  ```

  ```bash From Local File theme={null}
  trail components add ./my_component.wasm

  # Output:
  # Added: ["./traildepot/wasm/my_component.wasm"]
  ```

  ```bash From Local ZIP theme={null}
  trail components add /path/to/components.zip

  # Output:
  # Added: ["./traildepot/wasm/component1.wasm", "./traildepot/wasm/component2.wasm"]
  ```
</CodeGroup>

<Info>
  Components are installed to `<data-dir>/wasm/` directory and are automatically loaded on server startup.
</Info>

**Installation process:**

1. **Download/read** component file(s)
2. **Extract** (if ZIP archive)
3. **Validate** WASM component format
4. **Copy** to `<data-dir>/wasm/`
5. **Return** list of installed files

<Note>
  First-party components are version-matched to your TrailBase installation. The URL template automatically uses your TrailBase version.
</Note>

## Removing Components

### components remove

Remove an installed WASM component.

```bash theme={null}
trail components remove <REFERENCE>
```

<ParamField path="reference" type="string" required>
  Component reference. Can be a name or local path. URLs are not supported for removal.
</ParamField>

<CodeGroup>
  ```bash By Name (First-party) theme={null}
  trail components remove trailbase/auth_ui

  # Output:
  # Removed: ["./traildepot/wasm/auth_ui_component.wasm"]
  ```

  ```bash By Path theme={null}
  trail components remove ./traildepot/wasm/my_component.wasm

  # Output:
  # Removed: ["./traildepot/wasm/my_component.wasm"]
  ```
</CodeGroup>

<Warning>
  This permanently deletes the component file(s) from disk. The operation cannot be undone.
</Warning>

<Note>
  URLs cannot be used for removal. Use the component name (for first-party components) or the local path instead.
</Note>

## Listing Components

### components list

List all available first-party components from the official registry.

```bash theme={null}
trail components list
```

**Example output:**

```
Components:

trailbase/auth_ui
```

<Info>
  This shows components available for installation, not currently installed components. Use `components installed` to see installed components.
</Info>

### components installed

List all currently installed components with their interfaces.

```bash theme={null}
trail components installed
```

**Example output:**

```json theme={null}
./traildepot/wasm/auth_ui_component.wasm - interfaces: [
  {
    "name": "auth-ui",
    "namespace": "trailbase",
    "version": "0.1.0",
    "worlds": [
      "auth-ui"
    ],
    "interfaces": [
      "login",
      "register",
      "reset-password"
    ]
  }
]

./traildepot/wasm/custom_component.wasm - interfaces: [
  {
    "name": "custom-api",
    "namespace": "example",
    "version": null,
    "worlds": [
      "api-handler"
    ],
    "interfaces": [
      "handle-request"
    ]
  }
]
```

**Output structure:**

<ParamField path="name" type="string">
  Component package name.
</ParamField>

<ParamField path="namespace" type="string">
  Component namespace. First-party components use `trailbase`, custom components use custom namespaces.
</ParamField>

<ParamField path="version" type="string | null">
  Semantic version of the component, if specified.
</ParamField>

<ParamField path="worlds" type="string[]">
  List of WASI worlds the component implements.
</ParamField>

<ParamField path="interfaces" type="string[]">
  List of interfaces exposed by the component.
</ParamField>

<Note>
  The output filters out `wasi` and `root` namespaces, showing only application-relevant interfaces.
</Note>

## Updating Components

### components update

Update all installed first-party components to the latest version matching your TrailBase installation.

```bash theme={null}
trail components update
```

**Example output:**

```
Updated : ["./traildepot/wasm/auth_ui_component.wasm"]
Skipping "./traildepot/wasm/custom_component.wasm", not a first-party component
```

**Update process:**

1. **Scan** `<data-dir>/wasm/` for installed components
2. **Identify** first-party components by filename
3. **Download** latest version for each
4. **Replace** existing files
5. **Skip** custom/third-party components

<Info>
  Only first-party components from the official registry are updated. Custom components must be updated manually.
</Info>

<Warning>
  Components are replaced in-place. If the download fails partway through, you may need to reinstall manually.
</Warning>

## Component Structure

### WASM Component Format

TrailBase uses WebAssembly Component Model (WASI Preview 2):

```
component.wasm
├── Package metadata
│   ├── Name
│   ├── Namespace
│   └── Version
├── Worlds
│   └── World definitions
└── Interfaces
    ├── Imports (what the component needs)
    └── Exports (what the component provides)
```

### Component Lifecycle

1. **Installation** - Component copied to `<data-dir>/wasm/`
2. **Discovery** - TrailBase scans `wasm/` directory on startup
3. **Loading** - Components are loaded into WASM runtime
4. **Execution** - Components respond to requests based on their interfaces
5. **Unloading** - Components are unloaded on server shutdown

### Runtime Configuration

Configure WASM runtime via CLI options:

```bash theme={null}
trail run \
  --runtime-threads 4 \
  --runtime-root-fs /var/lib/trailbase/fs
```

<ParamField path="--runtime-threads" type="integer">
  Number of WASM isolates/workers. Defaults to CPU count.
</ParamField>

<ParamField path="--runtime-root-fs" type="string">
  Sandboxed filesystem root for WASM components.
</ParamField>

## First-Party Components

### trailbase/auth\_ui

Pre-built authentication UI component.

**Installation:**

```bash theme={null}
trail components add trailbase/auth_ui
```

**Features:**

* Login page
* Registration page
* Password reset flow
* Email verification
* OAuth provider buttons

**Interfaces:**

* `login` - Render login page
* `register` - Render registration page
* `reset-password` - Render password reset page

<Info>
  More first-party components will be added in future releases. Check the registry with `trail components list`.
</Info>

## Custom Components

### Creating Custom Components

Custom WASM components must implement WASI interfaces:

1. **Define interfaces** using WIT (WebAssembly Interface Types)
2. **Implement in your language** (Rust, Go, C, etc.)
3. **Compile to WASM Component** using `wasm-tools`
4. **Install via CLI**

**Example WIT definition:**

```wit theme={null}
package example:custom-api@0.1.0;

world api-handler {
  export handle-request: func(path: string) -> result<string, string>;
}
```

### Component Requirements

<ParamField path="Component Model" type="requirement">
  Must use WASI Component Model (not core WASM modules).
</ParamField>

<ParamField path="File Format" type="requirement">
  Must be `.wasm` file or `.zip` containing `.wasm` files.
</ParamField>

<ParamField path="Interfaces" type="requirement">
  Must export at least one interface that TrailBase can invoke.
</ParamField>

<ParamField path="Security" type="requirement">
  Runs in sandboxed environment with limited filesystem access.
</ParamField>

## Troubleshooting

### Component Won't Load

**Error:** Component file exists but isn't loaded

**Solutions:**

```bash theme={null}
# Check component is valid WASM
trail components installed

# Verify file format
file traildepot/wasm/component.wasm
# Should show: WebAssembly (wasm) binary module

# Check server logs for WASM errors
trail run --stderr-logging
```

### Download Fails

**Error:** `Failed to download component`

**Causes:**

* Network connectivity issues
* Invalid URL
* Component not available for your TrailBase version

**Solutions:**

```bash theme={null}
# Check TrailBase version
trail --version

# Try manual download
curl -L https://github.com/trailbaseio/trailbase/releases/download/v0.1.0/component.zip -o component.zip

# Install from local file
trail components add ./component.zip
```

### Version Mismatch

**Error:** Component loads but doesn't work correctly

**Cause:** Component version doesn't match TrailBase version

**Solution:**

```bash theme={null}
# Update all first-party components
trail components update

# Or reinstall specific component
trail components remove trailbase/auth_ui
trail components add trailbase/auth_ui
```

### Permission Denied

**Error:** `Permission denied` when adding component

**Solutions:**

```bash theme={null}
# Check wasm directory permissions
ls -la traildepot/wasm/

# Fix permissions
chmod 755 traildepot/wasm/

# Retry installation
trail components add component.wasm
```

### Component Conflicts

**Error:** Two components with same filename

**Solution:**

```bash theme={null}
# List installed components
trail components installed

# Remove conflicting component
trail components remove ./traildepot/wasm/duplicate.wasm

# Reinstall desired component
trail components add correct-component.wasm
```

## Advanced Usage

### Component Development Workflow

<Accordion title="Step-by-step: Develop and test custom component">
  ```bash theme={null}
  # 1. Create WIT interface definition
  cat > component.wit <<EOF
  package example:api@0.1.0;

  world handler {
    export process: func(input: string) -> string;
  }
  EOF

  # 2. Implement in Rust (or your preferred language)
  cargo component new my_component

  # 3. Build WASM component
  cargo component build --release

  # 4. Install for testing
  trail components add ./target/wasm32-wasi/release/my_component.wasm

  # 5. Test with TrailBase
  trail run --dev

  # 6. Iterate: make changes and reinstall
  cargo component build --release
  trail components remove ./traildepot/wasm/my_component.wasm
  trail components add ./target/wasm32-wasi/release/my_component.wasm
  ```
</Accordion>

### Packaging Components for Distribution

<Accordion title="Step-by-step: Create distributable component package">
  ```bash theme={null}
  # 1. Build component
  cargo component build --release

  # 2. Create ZIP package
  cd target/wasm32-wasi/release/
  zip my_component.zip my_component.wasm

  # 3. Include documentation
  zip -u my_component.zip README.md LICENSE

  # 4. Upload to hosting
  # Users can then install with:
  trail components add https://example.com/my_component.zip
  ```
</Accordion>

### Managing Multiple Component Versions

<Accordion title="Managing component versions across environments">
  ```bash theme={null}
  # Development: use local development version
  trail components add ./dev/component-dev.wasm

  # Staging: use released version
  trail components add https://cdn.example.com/component-v1.2.0.wasm

  # Production: use first-party or stable URL
  trail components add trailbase/auth_ui

  # Pin to specific version via URL
  trail components add https://github.com/example/releases/download/v1.0.0/component.wasm
  ```
</Accordion>

### Batch Component Operations

<Accordion title="Install multiple components at once">
  ```bash theme={null}
  # Create list of components
  cat > components.txt <<EOF
  trailbase/auth_ui
  https://example.com/component1.wasm
  ./local/component2.wasm
  EOF

  # Install all
  while read -r component; do
    echo "Installing $component..."
    trail components add "$component"
  done < components.txt

  # Verify all installed
  trail components installed
  ```
</Accordion>

## Component Security

### Sandboxing

WASM components run in a sandboxed environment:

* **No network access** by default
* **Limited filesystem access** (only `--runtime-root-fs`)
* **No system calls** outside WASI
* **Memory isolation** between components
* **CPU/memory limits** enforced by runtime

### Trusted Components

First-party components from `trailbase/*` namespace:

* Built and signed by TrailBase team
* Reviewed for security
* Version-matched to TrailBase release
* Automatically updated via `components update`

### Third-Party Components

<Warning>
  Third-party components run with the same privileges as first-party components. Only install components from trusted sources.
</Warning>

**Before installing third-party components:**

1. **Review source code** if available
2. **Check developer reputation**
3. **Test in development** environment first
4. **Monitor resource usage**
5. **Review WASM interfaces** with `components installed`

## Component API Reference

### WASI Interfaces

TrailBase provides these WASI interfaces to components:

<ParamField path="wasi:filesystem" type="interface">
  Sandboxed filesystem access within `--runtime-root-fs`.
</ParamField>

<ParamField path="wasi:random" type="interface">
  Cryptographically secure random number generation.
</ParamField>

<ParamField path="wasi:clocks" type="interface">
  Access to system clocks for timestamps.
</ParamField>

<ParamField path="wasi:io" type="interface">
  Standard I/O streams.
</ParamField>

### TrailBase Interfaces

TrailBase-specific interfaces for components:

<ParamField path="trailbase:http" type="interface">
  HTTP request handling (in development).
</ParamField>

<ParamField path="trailbase:database" type="interface">
  Database access (in development).
</ParamField>

<Note>
  Component API is under active development. Check documentation for the latest available interfaces.
</Note>