Skip to main content

Quickstart

The following is a minimal guide to running writing an Extism plug-in in your language of choice. This document should get you from 0 to "Hello, World!" as quickly as possible.

Generate Plug-in Boilerplate

You may also want to check out the Extism CLI which can generate much of the quickstart boilerplate for you.

Choose A Language

In Extism, your plug-in code is compiled to a binary Wasm module. We offer a variety of libraries, which we call PDKs (Plug-in Development Kits), to help you compile your code to a Wasm module that can be embedded in any Host SDK.

First choose a language for your plug-in:

Install the Dependency

Generate a lib project with Cargo:

cargo new --lib my-plugin

Add the library from crates.io.

cargo add extism-pdk

Change your Cargo.toml to set the crate-type to cdylib (this instructs the compiler to produce a dynamic library, which for our target will be a Wasm binary):

[lib]
crate_type = ["cdylib"]

Create an Export

The primary means of interacting with this plug-in is an export function that can be called by the outside world. Let's create a simple greeting plug-in. The plugin_fn macro wires this function to Extism and exports it using the name greet:

use extism_pdk::*;

#[plugin_fn]
pub fn greet(name: String) -> FnResult<String> {
Ok(format!("Hello, {}!", name))
}

Compile the Plug-in

We can compile to the wasm32-unknown-unknown since we don't need to make any syscalls (not using WASI):

cargo build --target wasm32-unknown-unknown
Wasm32 Targets

If this fails, make sure you have added this target to rust:

rustup target add wasm32-unknown-unknown

Running the Plug-In

This will put your compiled wasm in target/wasm32-unknown-unknown/debug. We can now test it using the Extism CLI's run command:

extism call target/wasm32-unknown-unknown/debug/my_plugin.wasm greet --input "Benjamin"
# => Hello, Benjamin!
Optimize using Release Mode

You will get better performance and smaller .wasm binaries if you build your code using --release.

cargo build --target wasm32-unknown-unknown --release

Documentation

Congrats! You just wrote your first Extism plug-in! To learn more about what this rust library can do, see the rust-pdk README and reference docs.

Need help?

If you've encountered a bug or think something is missing, please open an issue on the Extism GitHub repository.

There is an active community on Discord where the project maintainers and users can help you. Come hang out!