Skip to content

Available VDL Plugins

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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./gen/go"
  options {
    package "contracts"
  }
}

Repository: 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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./gen/ts"
  options {
    importExtension "js"
  }
}

Repository: 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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./gen/json-schema"
  options {
    outFile "schema.json"
    root "Account"
  }
}

Repository: 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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./internal/client"
  options {
    target "client"
    package "client"
    typesImport "example.com/project/internal/types"
  }
}

Repository: 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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./generated/client"
  options {
    target "client"
    typesImport "../types/index.js"
    importExtension "js"
  }
}

Repository: 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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./gen/openapi"
  options {
    outFile "openapi.yaml"
    title "Messaging API"
    version "1.0.0"
  }
}

Repository: 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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./gen/events"
  options {
    package "events"
  }
}

Repository: 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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./docs"
  options {
    outFile "schema-explorer.html"
  }
}

Repository: 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:

{
  src "varavelio/[email protected]"
  schema "./schema.vdl"
  outDir "./gen/meta"
  options {
    outFile "vdl-meta.json"
    includePositions "false"
  }
}

Repository: varavelio/vdl-plugin-meta

Combining Plugins

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

const config = {
  version 1
  plugins [
    {
      src "varavelio/[email protected]"
      schema "./schema.vdl"
      outDir "./gen/go"
      options { package "contracts" }
    }
    {
      src "varavelio/[email protected]"
      schema "./schema.vdl"
      outDir "./gen/json-schema"
    }
    {
      src "varavelio/[email protected]"
      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.