> ## 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.

# WebAssembly Runtime

> Extend TrailBase with custom server-side logic using WebAssembly components

## Overview

TrailBase includes a powerful WebAssembly (WASM) runtime built on Wasmtime that allows you to extend your backend with custom server-side logic. The runtime supports the [WebAssembly Component Model](https://component-model.bytecodealliance.org/), enabling you to write components in multiple languages including Rust, JavaScript, and TypeScript.

## Key Features

<CardGroup cols={2}>
  <Card title="Custom HTTP Endpoints" icon="route">
    Create custom API endpoints with full request/response control
  </Card>

  <Card title="Scheduled Jobs" icon="clock">
    Run background tasks on a cron schedule
  </Card>

  <Card title="Database Access" icon="database">
    Query and modify your SQLite database directly from WASM
  </Card>

  <Card title="Multi-Language" icon="code">
    Write components in Rust, JavaScript, TypeScript, or any language that compiles to WASM
  </Card>
</CardGroup>

## Architecture

The WASM runtime consists of two main parts:

### Host Runtime

Located in `crates/wasm-runtime-host/`, the host runtime:

* Compiles and loads WASM components using Wasmtime
* Provides sandboxed execution environment with configurable permissions
* Manages component lifecycle and hot-reloading
* Exposes host capabilities through WASI interfaces

```rust theme={null}
let runtime = Runtime::init(
    wasm_component_path,
    store_builder,
    RuntimeOptions {
        fs_root_path: Some(PathBuf::from("/sandbox")),
        use_winch: false,
        tokio_runtime: None,
    },
)?;
```

### Guest Runtime

Located in `crates/wasm-runtime-guest/`, the guest runtime provides:

* Type-safe API bindings for Rust, JavaScript, and TypeScript
* HTTP request/response handling
* Database query interface
* Job scheduling primitives
* Key-value store access
* Outbound HTTP fetch capabilities

## Capabilities

### Database Access

Components can query and modify the SQLite database:

<CodeGroup>
  ```rust Rust theme={null}
  use trailbase_wasm::db::{query, execute, Value};

  let rows = query(
      "SELECT * FROM users WHERE age > $1",
      [Value::Integer(18)]
  ).await?;

  let affected = execute(
      "UPDATE users SET verified = 1 WHERE id = $1",
      [Value::Integer(user_id)]
  ).await?;
  ```

  ```typescript TypeScript theme={null}
  import { query } from 'trailbase-wasm/db';

  const rows = await query(
    'SELECT * FROM users WHERE age > $1',
    [18]
  );
  ```
</CodeGroup>

### HTTP Fetch

Make outbound HTTP requests from your components:

<CodeGroup>
  ```rust Rust theme={null}
  use trailbase_wasm::fetch::{get, Request};

  let data = get("https://api.example.com/data").await?;
  ```

  ```typescript TypeScript theme={null}
  import { fetch } from 'trailbase-wasm/fetch';

  const response = await fetch('https://api.example.com/data');
  ```
</CodeGroup>

### Key-Value Store

Components have access to a shared key-value store:

<CodeGroup>
  ```rust Rust theme={null}
  use trailbase_wasm::kv;

  kv::set("counter", vec![0, 0, 0, 42])?;
  let value = kv::get("counter")?;
  ```

  ```typescript TypeScript theme={null}
  import { kv } from 'trailbase-wasm/kv';

  kv.set('counter', new Uint8Array([42]));
  const value = kv.get('counter');
  ```
</CodeGroup>

## Security & Sandboxing

WASM components run in a secure sandbox with:

* **Memory isolation**: Each component has its own linear memory
* **Filesystem restrictions**: Optional read-only access to a specified directory
* **Network controls**: No raw socket access, only HTTP through WASI interfaces
* **Resource limits**: Configurable memory reservation (default 64MB)

```rust theme={null}
pub struct RuntimeOptions {
    /// Optional file-system sandbox root for r/o file access
    pub fs_root_path: Option<PathBuf>,
    
    /// Whether to use the non-optimizing baseline compiler
    pub use_winch: bool,
    
    /// Which tokio runtime handle to execute on
    pub tokio_runtime: Option<tokio::runtime::Handle>,
}
```

## Component Discovery

TrailBase automatically discovers and loads WASM components from the `components/` directory in your data directory:

```rust theme={null}
pub fn find_wasm_components(components_path: impl AsRef<Path>) -> Vec<PathBuf> {
    // Finds all .wasm files in the components directory
}
```

## Use Cases

<CardGroup cols={2}>
  <Card title="Custom Business Logic" icon="briefcase">
    Implement complex validation, calculations, or workflows
  </Card>

  <Card title="Third-Party Integrations" icon="plug">
    Connect to external APIs and services
  </Card>

  <Card title="Data Processing" icon="chart-line">
    Transform and aggregate data before storage or retrieval
  </Card>

  <Card title="Server-Side Rendering" icon="server">
    Generate dynamic HTML responses
  </Card>
</CardGroup>

## Performance

The runtime is optimized for production use:

* **Ahead-of-time compilation**: Components are compiled once at startup
* **Caching**: Compiled components are cached to disk
* **Parallel compilation**: Utilizes all available CPU cores during compilation
* **Efficient instantiation**: Fast component instantiation for request handling

```rust theme={null}
log::info!("Compiling: {wasm_source_file:?}. May take some time...");

let component = wasmtime::CodeBuilder::new(&engine)
    .wasm_binary_or_text_file(&wasm_source_file)?
    .compile_component()?;

component.initialize_copy_on_write_image()?;
```

## Next Steps

<CardGroup cols={2}>
  <Card title="WASM Components" href="/advanced/wasm-components" icon="cube">
    Learn how to create WASM components
  </Card>

  <Card title="Custom Endpoints" href="/advanced/custom-endpoints" icon="route">
    Build custom HTTP endpoints
  </Card>

  <Card title="Server-Side Rendering" href="/advanced/server-side-rendering" icon="server">
    Render dynamic HTML with WASM
  </Card>

  <Card title="Jobs Scheduler" href="/advanced/jobs-scheduler" icon="clock">
    Schedule background tasks
  </Card>
</CardGroup>