# Available Plugins

> Official VDL plugins and what each one generates.

Canonical HTML: https://vdl.varavel.com/docs/guides/plugins/
Markdown: https://vdl.varavel.com/docs/guides/plugins/index.md

## Overview

VDL generates output through plugins. Each plugin receives the resolved VDL IR plus the plugin options from `vdl.config.vdl`, then returns files for VDL to write into the configured `outDir`.

This page summarizes the current official plugin ecosystem.

## Data Model Plugins

### `varavelio/vdl-plugin-go`

Generates Go data-model code from VDL types, enums, and constants.

Use it when you want Go structs, enum-like types, constants, strict JSON validation, optional-field pointer handling, and `datetime` mapped to `time.Time`.

Typical outputs include `types.go`, `enums.go`, `constants.go`, and `pointers.go`.

Common options:

| Option            | Purpose                                                |
| ----------------- | ------------------------------------------------------ |
| `package`         | Go package name.                                       |
| `genConsts`       | Enable or disable constant generation.                 |
| `strict`          | Enable stricter JSON validation.                       |
| `genPointerUtils` | Generate `Ptr`, `Val`, and `Or` helpers.               |
| `jsonPackage`     | Use a compatible JSON package such as `goccy/go-json`. |

Example:

```vdl
{
  src "varavelio/vdl-plugin-go@v0.1.3"
  schema "./schema.vdl"
  outDir "./gen/go"
  options {
    package "contracts"
  }
}
```

Repository: [varavelio/vdl-plugin-go](https://github.com/varavelio/vdl-plugin-go)

### `varavelio/vdl-plugin-ts`

Generates TypeScript data-model code from VDL types, enums, and constants.

Use it when you want typed interfaces, enum helpers, constants, `Date` hydration for `datetime`, and optional runtime validation helpers.

Typical outputs include `types.ts`, `enums.ts`, `index.ts`, and optionally `constants.ts`.

Common options:

| Option            | Purpose                                     |
| ----------------- | ------------------------------------------- |
| `genConsts`       | Enable or disable constant generation.      |
| `strict`          | Generate runtime `validate(...)` helpers.   |
| `importExtension` | Use `.js`, `.ts`, or extensionless imports. |

Example:

```vdl
{
  src "varavelio/vdl-plugin-ts@v0.1.4"
  schema "./schema.vdl"
  outDir "./gen/ts"
  options {
    importExtension "js"
  }
}
```

Repository: [varavelio/vdl-plugin-ts](https://github.com/varavelio/vdl-plugin-ts)

### `varavelio/vdl-plugin-json-schema`

Generates JSON Schema Draft 2020-12 from VDL types and enums.

Use it when you need a standard machine-readable schema for validators, form builders, documentation systems, API gateways, or external integrations.

The plugin emits all top-level VDL types and enums under `$defs`, supports references between definitions, maps non-optional fields to JSON Schema `required`, and carries documentation and `@deprecated` metadata into the generated schema.

Common options:

| Option    | Purpose                                                |
| --------- | ------------------------------------------------------ |
| `outFile` | Output JSON filename.                                  |
| `id`      | Top-level JSON Schema `$id`.                           |
| `root`    | Top-level `$ref` pointing to one generated definition. |

Example:

```vdl
{
  src "varavelio/vdl-plugin-json-schema@v0.1.0"
  schema "./schema.vdl"
  outDir "./gen/json-schema"
  options {
    outFile "schema.json"
    root "Account"
  }
}
```

Repository: [varavelio/vdl-plugin-json-schema](https://github.com/varavelio/vdl-plugin-json-schema)

## RPC Plugins

RPC support is annotation-based. These plugins look for `@rpc` service types and `@proc` or `@stream` operation fields.

### `varavelio/vdl-plugin-rpc-go`

Generates Go RPC clients or servers from annotation-based VDL RPC services.

This plugin is RPC-only. It does not generate data models; pair it with `varavelio/vdl-plugin-go` and point `typesImport` to the generated Go type package when the RPC output is in a separate package.

For `target "client"`, it emits typed client builders, procedure and stream execution APIs, headers, interceptors, retry and timeout policies, reconnect policies, and stream hooks.

For `target "server"`, it emits typed handler registration APIs, middleware hooks, stream configuration, error handling, and `net/http` adapter helpers.

Common options:

| Option        | Purpose                                                      |
| ------------- | ------------------------------------------------------------ |
| `target`      | Required. `client` or `server`.                              |
| `typesImport` | Go import path for the package generated by `vdl-plugin-go`. |
| `package`     | Generated Go package name.                                   |
| `jsonPackage` | Compatible JSON package imported as `json`.                  |

Example:

```vdl
{
  src "varavelio/vdl-plugin-rpc-go@v0.1.2"
  schema "./schema.vdl"
  outDir "./internal/client"
  options {
    target "client"
    package "client"
    typesImport "example.com/project/internal/types"
  }
}
```

Repository: [varavelio/vdl-plugin-rpc-go](https://github.com/varavelio/vdl-plugin-rpc-go)

### `varavelio/vdl-plugin-rpc-ts`

Generates TypeScript RPC clients or servers from annotation-based VDL RPC services.

This plugin is RPC-only. It expects data models from `varavelio/vdl-plugin-ts` and references them through `typesImport`.

For `target "client"`, it emits a typed client with procedure and stream builders, headers, interceptors, retries, timeouts, reconnect policies, and stream controls.

For `target "server"`, it emits a typed server with procedure and stream registration APIs, middleware, error handlers, ping configuration, and Node.js plus Fetch-compatible HTTP adapters.

Common options:

| Option            | Purpose                                                  |
| ----------------- | -------------------------------------------------------- |
| `target`          | Required. `client` or `server`.                          |
| `typesImport`     | Required import path to the generated TypeScript models. |
| `importExtension` | Internal generated import extension behavior.            |

Example:

```vdl
{
  src "varavelio/vdl-plugin-rpc-ts@v0.1.0"
  schema "./schema.vdl"
  outDir "./generated/client"
  options {
    target "client"
    typesImport "../types/index.js"
    importExtension "js"
  }
}
```

Repository: [varavelio/vdl-plugin-rpc-ts](https://github.com/varavelio/vdl-plugin-rpc-ts)

### `varavelio/vdl-plugin-rpc-openapi`

Generates OpenAPI 3.0 documents for VDL RPC procedures and streams.

Use it when you want to publish an OpenAPI contract for your VDL RPC layer, import requests into tools such as Postman, or feed OpenAPI-compatible docs, gateway, validation, or generation workflows.

It emits one `POST` path per operation, groups operations by service, emits request and response envelopes, and includes non-RPC VDL types and enums under `components.schemas`.

Common options:

| Option           | Purpose                                                   |
| ---------------- | --------------------------------------------------------- |
| `outFile`        | OpenAPI output file, usually `.yaml`, `.yml`, or `.json`. |
| `playgroundFile` | Optional standalone HTML docs file.                       |
| `playgroundUi`   | `swagger-ui`, `scalar`, or `stoplight-elements`.          |
| `title`          | OpenAPI `info.title`.                                     |
| `version`        | OpenAPI `info.version`.                                   |
| `description`    | OpenAPI `info.description`.                               |
| `baseUrl`        | One or more comma-separated server URLs.                  |

Example:

```vdl
{
  src "varavelio/vdl-plugin-rpc-openapi@v0.1.3"
  schema "./schema.vdl"
  outDir "./gen/openapi"
  options {
    outFile "openapi.yaml"
    title "Messaging API"
    version "1.0.0"
  }
}
```

Repository: [varavelio/vdl-plugin-rpc-openapi](https://github.com/varavelio/vdl-plugin-rpc-openapi)

## Event Plugins

### `varavelio/vdl-plugin-events-go`

Generates Go subject builders and a centralized event catalog from VDL types annotated with `@event`.

This plugin is event-focused and only processes `@event` object types. It does not generate event payload structs; pair it with `varavelio/vdl-plugin-go` for payload models.

It validates event subject templates, checks `{fieldName}` placeholders against top-level primitive fields, supports repeated placeholders, formats non-string placeholders, and emits a typed `VDLEventCatalog` with `BuildSubject` functions.

Common options:

| Option    | Purpose                    |
| --------- | -------------------------- |
| `package` | Generated Go package name. |
| `outFile` | Generated Go filename.     |

Example:

```vdl
{
  src "varavelio/vdl-plugin-events-go@v0.1.3"
  schema "./schema.vdl"
  outDir "./gen/events"
  options {
    package "events"
  }
}
```

Repository: [varavelio/vdl-plugin-events-go](https://github.com/varavelio/vdl-plugin-events-go)

## Documentation And Metadata Plugins

### `varavelio/vdl-plugin-explorer`

Generates a standalone HTML explorer for VDL docs, RPCs, types, enums, and constants.

Use it when you want to share schema documentation with teammates, clients, or partners without running a server. The generated HTML embeds the schema data directly, includes search and navigation, supports light and dark themes, and works as a static file.

Common options:

| Option       | Purpose                                               |
| ------------ | ----------------------------------------------------- |
| `outFile`    | Output HTML filename.                                 |
| `rpcBaseUrl` | Base URL shown for generated RPC operation endpoints. |

Example:

```vdl
{
  src "varavelio/vdl-plugin-explorer@v0.1.1"
  schema "./schema.vdl"
  outDir "./docs"
  options {
    outFile "schema-explorer.html"
  }
}
```

Repository: [varavelio/vdl-plugin-explorer](https://github.com/varavelio/vdl-plugin-explorer)

### `varavelio/vdl-plugin-meta`

Exports the VDL Intermediate Representation as JSON.

Use it when you need reflection-like schema metadata at runtime, for internal tools, dynamic forms, custom validators, explorers, or downstream generators.

Common options:

| Option             | Purpose                                         |
| ------------------ | ----------------------------------------------- |
| `outFile`          | Output JSON filename.                           |
| `includePositions` | Include source file, line, and column metadata. |

Example:

```vdl
{
  src "varavelio/vdl-plugin-meta@v1.0.1"
  schema "./schema.vdl"
  outDir "./gen/meta"
  options {
    outFile "vdl-meta.json"
    includePositions "false"
  }
}
```

Repository: [varavelio/vdl-plugin-meta](https://github.com/varavelio/vdl-plugin-meta)

## Combining Plugins

You can run several plugins against the same schema in one `vdl generate` call.

```vdl
const config = {
  version 1
  plugins [
    {
      src "varavelio/vdl-plugin-go@v0.1.3"
      schema "./schema.vdl"
      outDir "./gen/go"
      options { package "contracts" }
    }
    {
      src "varavelio/vdl-plugin-json-schema@v0.1.0"
      schema "./schema.vdl"
      outDir "./gen/json-schema"
    }
    {
      src "varavelio/vdl-plugin-explorer@v0.1.1"
      schema "./schema.vdl"
      outDir "./docs/schema"
    }
  ]
}
```

Use separate `outDir` values unless you intentionally want related generated files in the same package. VDL prevents two plugin outputs from writing the same file path in one generation run.

## Version Note

The examples above use the versions documented in each plugin README at the time this page was written. Check each plugin repository for the latest release tag before pinning a new project.