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

# Extensions Overview

> Understanding k6's extension system and available extension types

k6 extensions allow you to enhance k6's functionality by adding custom JavaScript modules, output formats, secret sources, and subcommands. Extensions are built in Go and loaded into k6 using xk6.

## What Are Extensions?

Extensions are Go packages that integrate with k6 to provide additional capabilities beyond the core functionality. They enable you to:

* Add custom JavaScript APIs
* Integrate with proprietary systems
* Create specialized output formats
* Implement custom authentication sources
* Add new CLI subcommands

<Note>
  Extensions are compiled into k6 at build time, creating a custom k6 binary with your additional functionality.
</Note>

## Extension Types

k6 supports four types of extensions (`ext/ext.go:26`):

### JavaScript Extensions

Add custom JavaScript modules that can be imported in your test scripts.

```javascript theme={null}
import custom from 'k6/x/custom';

export default function () {
  custom.doSomething();
}
```

**Use cases:**

* Protocol implementations (MQTT, Kafka, gRPC)
* Custom encodings or cryptography
* Proprietary API clients
* Specialized data generation

### Output Extensions

Create custom outputs to send test results to any backend or format.

```bash theme={null}
k6 run --out myoutput=config script.js
```

**Use cases:**

* Proprietary monitoring systems
* Custom database storage
* Specialized file formats
* Real-time streaming platforms

See [Creating Custom Outputs](/results/custom-outputs) for details.

### Secret Source Extensions

Implement custom secret sources for retrieving sensitive configuration values.

**Use cases:**

* Corporate secret management systems
* Hardware security modules (HSM)
* Cloud provider secret managers
* Custom encryption schemes

### Subcommand Extensions

Add new CLI subcommands to k6.

```bash theme={null}
k6 mycommand [args]
```

**Use cases:**

* Custom test orchestration
* Specialized reporting tools
* Configuration generators
* Integration utilities

## Extension Registry

Extensions are registered globally using the extension registry (`ext/ext.go:18`). The registry:

* Maintains a map of extensions by type
* Prevents duplicate registrations
* Tracks module path and version information
* Provides lookup by extension type

### Registration

Extensions self-register using the `Register()` function:

```go theme={null}
import "go.k6.io/k6/ext"

func init() {
    ext.Register("myextension", ext.JSExtension, &MyExtension{})
}
```

<Warning>
  Attempting to register an extension with a duplicate name will cause a panic. Ensure your extension names are unique.
</Warning>

## Extension Metadata

Each extension contains metadata (`ext/ext.go:49`):

```go theme={null}
type Extension struct {
    Name    string        // Extension name
    Path    string        // Go module path
    Version string        // Module version
    Type    ExtensionType // Extension type
    Module  any           // Extension implementation
}
```

This metadata is used for:

* Version tracking and compatibility
* Debugging and diagnostics
* Extension discovery
* Conflict detection

### Viewing Extensions

List all loaded extensions:

```bash theme={null}
k6 version
```

The output shows k6 version and all compiled-in extensions with their versions.

## How Extensions Work

<Steps>
  ### Build Time

  Extensions are compiled into k6 using xk6:

  ```bash theme={null}
  xk6 build --with github.com/user/xk6-extension@latest
  ```

  ### Initialization

  When k6 starts, extension `init()` functions run and register extensions.

  ### Runtime

  k6 looks up registered extensions when:

  * Importing JavaScript modules
  * Processing `--out` flags
  * Loading secret sources
  * Executing CLI commands

  ### Execution

  Extensions integrate with k6's core systems:

  * JS extensions expose APIs to test scripts
  * Output extensions receive metric samples
  * Secret sources are queried for values
  * Subcommands execute custom logic
</Steps>

## Extension Naming

Follow these conventions:

### Repository Names

Prefix with `xk6-` for discoverability:

* `xk6-output-kafka`
* `xk6-redis`
* `xk6-crypto`

### Extension Names

Use lowercase, descriptive names:

```go theme={null}
ext.Register("redis", ext.JSExtension, module)
```

### JavaScript Import Paths

JS extensions use the `k6/x/` namespace:

```javascript theme={null}
import redis from 'k6/x/redis';
```

<Tip>
  Consistent naming helps users discover and use your extensions easily.
</Tip>

## Popular Extensions

### Official Extensions

* **xk6-browser**: Browser automation and testing
* **xk6-dashboard**: Web-based results dashboard
* **xk6-kubernetes**: Kubernetes testing utilities
* **xk6-sql**: SQL database testing

### Community Extensions

* **xk6-kafka**: Apache Kafka protocol support
* **xk6-redis**: Redis client functionality
* **xk6-mqtt**: MQTT protocol implementation
* **xk6-output-influxdb**: InfluxDB v2 output
* **xk6-prometheus-remote**: Prometheus remote write

Explore more at [k6 Extension Registry](https://k6.io/docs/extensions/).

## Building Blocks

Extensions leverage k6's internal packages:

### For JavaScript Extensions

* `js/modules`: Module registration and lifecycle
* `metrics`: Creating and emitting custom metrics

### For Output Extensions

* `output`: Output interface and utilities
* `metrics`: Receiving and processing samples

### Common Packages

* `lib`: Core k6 types and utilities
* `stats`: Statistical calculations
* `lib/types`: Common type definitions

## Version Compatibility

Extensions should specify compatible k6 versions:

```go theme={null}
// go.mod
module github.com/user/xk6-myext

go 1.22

require go.k6.io/k6 v0.50.0
```

<Warning>
  k6's internal APIs may change between versions. Pin your extension to compatible k6 versions and test thoroughly when upgrading.
</Warning>

## Performance Considerations

* **JavaScript extensions**: Minimize CGO calls and data conversions
* **Output extensions**: Use buffering and async processing
* **All extensions**: Avoid blocking operations in hot paths

<Note>
  Badly performing extensions can significantly impact test accuracy by consuming VU execution time.
</Note>

## Security Considerations

* Validate all inputs from JavaScript
* Sanitize data sent to external systems
* Handle secrets securely
* Avoid logging sensitive information
* Review dependencies for vulnerabilities

## Extension Development

Ready to build your own extension?

* [Using Extensions](/extensions/using-extensions) - Install and use existing extensions
* [Creating Extensions](/extensions/creating-extensions) - Build custom extensions
* [Creating Custom Outputs](/results/custom-outputs) - Specialized output guide

## Community Resources

* [k6 Community Forum](https://community.grafana.com/c/grafana-k6/)
* [Extension Registry](https://k6.io/docs/extensions/)
* [xk6 Repository](https://github.com/grafana/xk6)
* [Example Extensions](https://github.com/topics/xk6)