Installation

Install and configure Moqtail in your project

Package Installation

Moqtail is available as an npm package. Install it using your preferred package manager:

npm

npm install moqtail

Package Information

Package Name: moqtail
Current Version: 0.9.0
License: Apache-2.0
Homepage: https://moqtail.dev
Repository: github.com/moqtail/moqtail

Prerequisites

Before installing Moqtail, ensure your development environment meets these requirements:

1. Node.js

   Node.js version 18 or higher is recommended for optimal compatibility.

   node --version
   # Should output v18.0.0 or higher
   
2. WebTransport Support

   Your target browsers must support WebTransport. Check compatibility at caniuse.com/webtransport.

   Supported browsers:

   • Chrome 97+
   • Edge 97+
   • Opera 83+
3. HTTPS/TLS Certificate

   For local development with a relay server, you’ll need to trust a local CA certificate. See the relay server documentation for details.

Import Paths

Moqtail provides multiple entry points for different parts of the library:

Main Entry Point

Import everything from the main entry point:

import { MOQtailClient, FullTrackName, MoqtObject } from 'moqtail'

Subpath Imports

For more granular imports, use subpath exports:

Client

// Import client types and classes
import { MOQtailClient } from 'moqtail/client'

TypeScript Configuration

Moqtail is built with TypeScript and includes full type definitions. The package exports both ESM and CommonJS formats:

package.json

{
  "type": "module",
  "main": "dist/index.cjs",
  "module": "dist/index.js",
  "types": "dist/index.d.ts"
}

Recommended tsconfig.json

For optimal TypeScript support:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "resolveJsonModule": true
  }
}

Build Tools Configuration

Vite

Moqtail works seamlessly with Vite:

vite.config.ts

import { defineConfig } from 'vite'

export default defineConfig({
  // No special configuration needed
  server: {
    // For local development with relay
    https: true
  }
})

Webpack

For Webpack users:

webpack.config.js

module.exports = {
  resolve: {
    extensions: ['.ts', '.js']
  },
  module: {
    rules: [
      {
        test: /\.ts$/,
        use: 'ts-loader',
        exclude: /node_modules/
      }
    ]
  }
}

Verify Installation

Create a simple test file to verify your installation:

test.ts

import { MOQtailClient } from 'moqtail'

console.log('Moqtail imported successfully!')
console.log('MOQtailClient:', MOQtailClient)

Run it with:

Node.js

node --loader ts-node/esm test.ts

You should see output confirming the import was successful.

Setting Up a Local Relay (Optional)

For development, you may want to run a local MOQT relay server. The Moqtail repository includes a Rust-based relay:

1. Clone the Repository

   git clone https://github.com/moqtail/moqtail.git
   cd moqtail
   
2. Install Rust

   Install Rust from rustup.rs if not already installed.

3. Generate TLS Certificates

   cd apps/relay/cert
   # Follow instructions in README.md
   
4. Run the Relay

   cargo run --bin relay -- \
     --port 4433 \
     --cert-file cert/cert.pem \
     --key-file cert/key.pem
   
5. Trust the Certificate

   Import and trust the generated CA certificate in your browser/system.

The relay server is required for testing publisher and subscriber interactions. Without it, you can still import and work with Moqtail’s types and utilities.

Troubleshooting

Common Issues

Module not found error

Ensure you’ve run the install command and that node_modules contains the moqtail directory.

ls node_modules/moqtail

WebTransport is not defined

This error occurs when running in environments without WebTransport support (Node.js, older browsers).

Solution: WebTransport is a browser-only API. Moqtail must run in a WebTransport-compatible browser or use a polyfill for testing.

TypeScript type errors

Make sure your tsconfig.json includes "lib": ["DOM", "ES2020"] to enable WebTransport types.

Certificate trust issues

For local development, you must trust the relay’s CA certificate. Follow the instructions in apps/relay/cert/README.md.

Next Steps

Quick Start

Build your first MOQT application

API Reference

Explore the complete API documentation