Quickstart
The following is a minimal guide to running an Extism plug-in in your language
and platform of choice. This document should get you from 0
to "Hello, World!"
as quickly as possible.
Choose A Language
In Extism parlance, your normal (non-wasm) application is known as the "host". We offer a variety of libraries, which we call "Host SDKs", to help you embed Extism plug-ins into your application.
First choose the language of your application:
- JavaScript
- Go
- Rust
- Ruby
- Python
- C#
- F#
- Java
- Elixir
- C
- PHP
- OCaml
- Zig
- Haskell
- C++
- D
Install the Dependency
The module is hosted on npm.
Put the @extism/extism
dependency in your package.json
:
npm install @extism/extism --save
This library is also compatible with Browsers, Deno, and Bun but this guide will assume we're running in node.js.
Import the library and load a plug-in
We suggest you copy paste the following code here into a node.js shell:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
const createPlugin = require("@extism/extism")
const plugin = await createPlugin(
'https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm',
{ useWasi: true }
);
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
let out = await plugin.call("count_vowels", "Hello, World!");
console.log(out.text())
// => '{"count":3,"total":3,"vowels":"aeiouAEIOU"}'
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this javascript library can do, see the js-sdk README and reference docs.
If you're interested in learning how to write a plug-in, see the plugin quickstart.
Install the Dependency
Install via go get:
go get github.com/extism/go-sdk
Import the library and load a plug-in
Let's now load a plug-in in Go.
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
Copy paste this into a main function in main.go
:
package main
import (
"context"
"fmt"
"github.com/extism/go-sdk"
"os"
)
func main() {
manifest := extism.Manifest{
Wasm: []extism.Wasm{
extism.WasmUrl{
Url: "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm",
},
},
}
ctx := context.Background()
config := extism.PluginConfig{}
plugin, err := extism.NewPlugin(ctx, manifest, config, []extism.HostFunction{})
if err != nil {
fmt.Printf("Failed to initialize plugin: %v\n", err)
os.Exit(1)
}
}
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
Copy-paste this code to the end of your main func:
func main() {
// ...
data := []byte("Hello, World!")
exit, out, err := plugin.Call("count_vowels", data)
if err != nil {
fmt.Println(err)
os.Exit(int(exit))
}
response := string(out)
fmt.Println(response)
}
Run the program:
$ go run main.go
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this go library can do, see the go-sdk README and reference docs.
If you're interested in learning how to write a plug-in, see the plugin quickstart.
Install the Dependency
To use the extism crate, you can add it to your Cargo file:
[dependencies]
extism = "1.0.0"
Import the library and load a plug-in
Let's now load a plug-in in Rust.
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
Copy paste this into a main function in main.rs
. This will load an Extism plug-in from the web:
use extism::*;
fn main() {
let url = Wasm::url(
"https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
);
let manifest = Manifest::new([url]);
let mut plugin = Plugin::new(&manifest, [], true).unwrap();
}
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
Copy-paste this code to the end of your main function:
fn main() {
// ...
let res = plugin.call::<&str, &str>("count_vowels", "Hello, world!").unwrap();
println!("{}", res);
}
Run the program:
$ cargo run
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this rust library can do, see the rust-sdk README and reference docs.
If you're interested in learning how to write a plug-in, see the plugin quickstart.
Install the Dependency
For this library, you first need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:
sudo extism lib install
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib
#=> Copying extism.h to /usr/local/include/extism.h
The ruby gem is hosted on RubyGems.
Put the extism
gem in your Gemfile
:
gem 'extism', '~> 1.0'
Or install with gem install
if you are not using bundler:
gem install extism
Import the library and load a plug-in
Let's now load a plug-in from ruby. We suggest you copy paste the following code here into an irb or pry shell:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
require 'extism'
url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
manifest = Extism::Manifest.from_url(url)
plugin = Extism::Plugin.new(manifest)
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
plugin.call("count_vowels", "Hello, World!")
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this ruby library can do, see the ruby-sdk README and reference docs.
If you're interested in learning how to write a plug-in, see the plugin quickstart.
Install the Dependency
Install this package from PyPI:
# using pip
$ pip install extism
# using poetry
$ poetry add extism=^1.0.0
Import the library and load a plug-in
Let's now load a plug-in from python. We suggest you copy paste the following code here into a python interpreter:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
import extism
url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
manifest = {"wasm": [{"url": url}]}
plugin = extism.Plugin(manifest)
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
wasm_vowel_count = plugin.call(
"count_vowels",
"hello world"
)
print(wasm_vowel_count)
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this python library can do, see the python-sdk README and reference docs.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependency
This library depends on the native Extism runtime, we provide native runtime packages for all supported operating systems. You can install with:
dotnet add package Extism.runtime.all
Then, add the Extism.Sdk NuGet package to your project:
dotnet add package Extism.Sdk
Import the library and load a plug-in
Let's now load a plug-in from C#. We suggest you copy paste the following code here
into a main Progam.cs
file:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
using System;
using Extism.Sdk;
var manifest = new Manifest(new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"));
using var plugin = new Plugin(manifest, new HostFunction[] { }, withWasi: true);
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
Add these next lines to your Program.cs
file:
var output = plugin.Call("count_vowels", "Hello, World!");
Console.WriteLine(output);
Run using dotnet
:
dotnet run
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this dotnet library can do, see the dotnet-sdk README and reference docs.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependency
This library depends on the native Extism runtime, we provide native runtime packages for all supported operating systems. You can install with:
dotnet add package Extism.runtime.all
Then, add the Extism.Sdk NuGet package to your project:
dotnet add package Extism.Sdk
Import the library and load a plug-in
Let's now load a plug-in from F#. We suggest you copy paste the following code here
into a main Progam.fs
file:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
open System
open Extism.Sdk
open Extism.Sdk.Native
let uri = Uri("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm")
let manifest = Manifest(new UrlWasmSource(uri))
let plugin = new Plugin(manifest, Array.Empty<HostFunction>(), withWasi = true)
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
Add these next lines to your Program.fs
file:
let output = plugin.Call("count_vowels", "Hello, World!")
System.Console.WriteLine(output)
Run using dotnet
:
dotnet run
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this dotnet library can do, see the dotnet-sdk README and reference docs.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependency
For this library, you first need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:
sudo extism lib install
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib
#=> Copying extism.h to /usr/local/include/extism.h
Once this is done, you can install the jar.
Maven
To use the Extism java-sdk with maven you need to add the following dependency to your pom.xml
file:
<dependency>
<groupId>org.extism.sdk</groupId>
<artifactId>extism</artifactId>
<version>1.0.0</version>
</dependency>
Gradle
To use the Extism java-sdk with maven you need to add the following dependency to your build.gradle
file:
implementation 'org.extism.sdk:extism:1.0.0'
Import the library and load a plug-in
Let's now load a plug-in from Java. We suggest you copy paste the following code here
into a main function in a Main.java
file:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
import org.extism.sdk.manifest.Manifest;
import org.extism.sdk.wasm.UrlWasmSource;
import org.extism.sdk.Plugin;
public static void main(String[] args) {
var url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm";
var manifest = new Manifest(List.of(UrlWasmSource.fromUrl(url)));
var plugin = new Plugin(manifest, false, null);
}
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
Add these next lines to your main function:
public static void main(String[] args) {
// ...
var output = plugin.call("count_vowels", "Hello, World!");
System.out.println(output);
}
Running this should yield the vowel report:
mvn compile exec:java -Dexec.mainClass="com.dylibso.myapp.Main"
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this java library can do, see the java-sdk README and reference docs.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependency
You can find this package on hex.pm
def deps do
[
{:extism, "1.0.0"}
]
end
Note: You do not need to install the Extism Runtime shared object, but you will need a rust toolchain installed to build this package. See Install Rust to install for your platform.
Import the library and load a plug-in
Let's now load a plug-in from Elixir. We suggest you copy paste the following code here
into a main function in an Elixir repl using iex -S mix
:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
manifest = %{wasm: [%{url: url}]}
{:ok, plugin} = Extism.Plugin.new(manifest, false)
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
Paste in these lines next and it should print out the vowel report:
{:ok, output} = Extism.Plugin.call(plugin, "count_vowels", "Hello, World!")
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this Elixir library can do, see the elixir-sdk README and reference docs.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependency
For this library, you need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:
sudo extism lib install
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib
#=> Copying extism.h to /usr/local/include/extism.h
Import the library and load a plug-in
Let's now load a plug-in from C. We suggest you copy paste the following code here
into a main function in a main.c
file:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
#include <extism.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
int main(void) {
const char *manifest = "{\"wasm\": [{\"url\": "
"\"https://github.com/extism/plugins/releases/latest/"
"download/count_vowels.wasm\"}]}";
char *errmsg = NULL;
ExtismPlugin *plugin = extism_plugin_new(
(const uint8_t *)manifest, strlen(manifest), NULL, 0, true, &errmsg);
if (plugin == NULL) {
fprintf(stderr, "ERROR: %s\n", errmsg);
extism_plugin_new_error_free(errmsg);
exit(1);
}
// ...
}
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
Here we add a print_plugin_output
function and the remainder of the main implementation:
void print_plugin_output(ExtismPlugin *plugin, int32_t rc) {
if (rc != EXTISM_SUCCESS) {
fprintf(stderr, "ERROR: %s\n", extism_plugin_error(plugin));
return;
}
size_t outlen = extism_plugin_output_length(plugin);
const uint8_t *out = extism_plugin_output_data(plugin);
write(STDOUT_FILENO, out, outlen);
}
int main(void) {
// ...
const char *input = "Hello, world!";
print_plugin_output(plugin, extism_plugin_call(plugin, "count_vowels",
(const uint8_t *)input,
strlen(input)));
extism_plugin_free(plugin);
return 0;
}
gcc -g -o example main.c -lextism
./example
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this C library can do, see the libextism README and reference docs.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependency
For this library, you need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:
sudo extism lib install
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib
#=> Copying extism.h to /usr/local/include/extism.h
Install via Packagist:
composer require extism/extism
For the time being you may need to add a minimum-stability of "dev" to your composer.json
{
"minimum-stability": "dev",
}
Import the library and load a plug-in
Let's now load a plug-in from php. We suggest you copy paste the following code here
into in index.php
file:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
<?php
use Extism\Plugin;
use Extism\Manifest;
use Extism\UrlWasmSource;
require_once __DIR__ . '/vendor/autoload.php';
$wasm = new UrlWasmSource("https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm");
$manifest = new Manifest($wasm);
$plugin = new Plugin($manifest, true);
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
<?php
// ...
$output = $plugin->call("count_vowels", "Hello, World!");
// => {"count": 3, "total": 6, "vowels": "aeiouAEIOU"}
The run it:
php index.php
# => '{"count":3,"total":3,"vowels":"aeiouAEIOU"}'
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this php library can do, see the php-sdk README and reference docs.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependency
For this library, you need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:
sudo extism lib install
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib
#=> Copying extism.h to /usr/local/include/extism.h
Import the library and load a plug-in
Let's now load a plug-in from OCaml!
Add the extism
package to your dune
and dune-project
files:
(libraries extism)
(package
(depends (extism)))
In your OCaml project:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
open Extism
let wasm = Manifest.Wasm.url "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
let manifest = Manifest.create [wasm]
let plugin = Plugin.of_manifest_exn manifest
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
let () =
let output = Plugin.call_string_exn plugin ~name:"count_vowels" "Hello, world!" in
print_endline output
dune exec ./bin/main.exe
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this OCaml library can do, see the ocaml-sdk README.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependency
For this library, you need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:
sudo extism lib install
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib
#=> Copying extism.h to /usr/local/include/extism.h
Import the library and load a plug-in
Let's now load a plug-in from Zig!
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
// First require the library
const extism = @import("extism");
const std = @import("std");
const wasm_url = extism.manifest.WasmUrl{ .url = "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm" };
const manifest = .{ .wasm = &[_]extism.manifest.Wasm{.{ .wasm_url= wasm_url }} };
var gpa = std.heap.GeneralPurposeAllocator(.{}){};
defer std.debug.assert(gpa.deinit() == .ok);
const allocator = gpa.allocator();
var plugin = try extism.Plugin.initFromManifest(
allocator,
manifest,
&[_]extism.Function{},
false,
);
defer plugin.deinit();
Call an export function
This plug-in was written in Rust and it does one thing, it counts vowels in a string. As such, it exposes one "export" function: count_vowels
. We can call exports using Extism::Plugin#call:
try plugin.call("count_vowels", "Hello, World!");
# => {"count": 3, "total": 3, "vowels": "aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this java library can do, see the zig-sdk README.
Install the Dependency
For this library, you need to install the Extism Runtime. You can download the shared object directly from a release or use the Extism CLI to install it:
sudo extism lib install
#=> Fetching https://github.com/extism/extism/releases/download/v1.0.0/libextism-aarch64-apple-darwin-v1.0.0.tar.gz
#=> Copying libextism.dylib to /usr/local/lib/libextism.dylib
#=> Copying extism.h to /usr/local/include/extism.h
Import the library and load a plug-in
Let's now load a plug-in from Haskell!
Add extism
to your cabal file:
executable example
main-is: bin/Main.hs
build-depends: extism
In your Haskell project:
count_vowels.wasm
is an example plugin that counts vowels. It was written in Rust, but can
be written in any of the supported PDK languages.
module Main where
import Extism
main = do
let wasm = wasmURL "GET" "https://github.com/extism/plugins/releases/latest/download/count_vowels.wasm"
plugin <- unwrap <$> newPlugin (manifest [wasm]) [] True
Call an export function
Let's call the "count_vowels" export function on the plugin. This counts the number of vowels in the string we pass in and returns a JSON encoded result.
res <- unwrap <$> call plugin "count_vowels" "Hello, world!"
putStrLn res
cabal exec example
# => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this Haskell library can do, see the haskell-sdk README.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
Install the Dependencies
Install the Extism runtime by following the instructions here
Install cmake and jsoncpp
# on Debian
sudo apt install cmake jsoncpp
# on macOS
brew install cmake jsoncpp
If you'd prefer to link jsoncpp statically, or do an in-tree build, See Alternative Dependency Strategies.
Build and Install cpp-sdk
cmake -B build
cmake --build build -j
sudo cmake --install build
To add the cpp-sdk to a CMake project:
find_package(extism-cpp)
target_link_libraries(getting-started extism-cpp)
Import the library and load a plug-in
Let's now load a plug-in from C++
#include <extism.hpp>
int main(void) {
const auto manifest =
extism::Manifest::wasmURL("https://github.com/extism/plugins/releases/"
"latest/download/count_vowels.wasm");
extism::Plugin plugin(manifest, true);
}
Call an export function
This plug-in was written in Rust and it does one thing, it counts vowels in a string. It exposes one "export" function: count_vowels. We can call exports using Plugin::call. Let's add code to call count_vowels to our main func:
#include <extism.hpp>
#include <iostream>
#include <string>
int main(void) {
// ...
const std::string hello("Hello, World!");
auto out = plugin.call("count_vowels", hello);
std::string response(out.string());
std::cout << response << std::endl;
// => {"count":3,"total":3,"vowels":"aeiouAEIOU"}
}
Build it:
cmake -B build && cmake --build build
Running this should print out the JSON vowel count report:
./build/getting-started
{"count":3,"total":3,"vowels":"aeiouAEIOU"}
Documentation
Congrats! You just ran your first Extism plug-in. To learn more about what this C++ library can do, see the cpp-sdk README.
If you're interested in writing how to write a plug-in, see the plugin quickstart.
See the README
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!