“Hello World” Example

📘 About this example: Although it is called “Hello World,” this sample is intentionally comprehensive. It brings together validation, streaming, multi‑language client generation, and OpenAPI output in a single, focused project. If you need the absolute minimal starting point, see the Quick Start guide first.

The “Hello World” app at hello-world.vovk.dev is a Next.js / Vovk.ts example showcasing core features by implementing:

Back end:
- UserController with an updateUser method (POST /api/users/{id}).
- StreamController with a JSONLines streamTokens handler (GET /api/streams/tokens).
- OpenApiController with getSpec (GET /api/static/openapi/spec.json), serving the generated OpenAPI spec. Documentation is viewable at the /openapi page.
Front end:
- A form plus a JSONLines streaming demo above it.
Configuration:
- Client‑side validation; segmented & composed TypeScript clients; generation of Rust/Python clients; npm bundle output; and OpenAPI metadata (info + servers).

Explore the source in the GitHub repository . Generated artifacts are committed under dist , tmp_prebundle , dist_rust , and dist_python for inspection (in real projects they should go in .gitignore).

All snippets on this page are pulled directly from GitHub; live example pages are embedded via iframes.

Running the Example Locally

Clone and install:


git clone https://github.com/finom/vovk-hello-world.git
cd vovk-hello-world
npm i

Start the dev server:


npm run dev

Then open http://localhost:3000 .

Topics and Concepts Covered

Zod validation for body, query, and params input, plus output and iteration output schemas with description and examples via Zod meta .
Client-side validation for RPC inputs.
Composed and segmented TypeScript clients.
JSONLines streaming.
Type inference between service and controller layers.
useQuery / useMutation usage with queryKey.
TypeScript client bundle published on npm .
Experimental Rust and Python clients published on crates.io / PyPI .
OpenAPI spec served from a static segment and rendered via Scalar .

Live Demo

The demo provides a simple form (no native validation attributes) and a “Disable client-side input validation” checkbox toggling the disableClientValidation option. “Notification type” is intentionally mis-set to show both client and server validation behavior.

https://hello-world.vovk.dev

`UserController` and `UserService`

/api/users/{id} is implemented by UserController / UserService through updateUser.

The controller method uses @post to map POST and withZod for Zod validation of body, params, query and output. Each schema applies meta for richer OpenAPI (description, examples). For illustration, body nests email and a profile object (name, age).

The service method infers parameter types from the controller method, returning the service method result directly and avoiding implicit any self-reference issues.

UserController.ts

src/modules/user/UserController.ts


import { z } from "zod";
import { prefix, post, operation } from "vovk";
import { withZod } from "vovk-zod";
import UserService from "./UserService";
 
@prefix("users")
export default class UserController {
  @operation({
    summary: "Update user",
    description: "Update user by ID",
  })
  @post("{id}")
  static updateUser = withZod({
    body: z
      .object({
        email: z.email().meta({
          description: "User email",
          examples: ["john@example.com", "jane@example.com"],
        }),
        profile: z
          .object({
            name: z
              .string()
              .min(2)
              .meta({
                description: "User full name",
                examples: ["John Doe", "Jane Smith"],
              }),
            age: z
              .int()
              .min(16)
              .max(120)
              .meta({ description: "User age", examples: [25, 30] }),
          })
          .meta({ description: "User profile object" }),
      })
      .meta({ description: "User data object" }),
    params: z
      .object({
        id: z.uuid().meta({
          description: "User ID",
          examples: ["123e4567-e89b-12d3-a456-426614174000"],
        }),
      })
      .meta({
        description: "Path parameters",
      }),
    query: z
      .object({
        notify: z
          .enum(["email", "push", "none"])
          .meta({ description: "Notification type" }),
      })
      .meta({
        description: "Query parameters",
      }),
    output: z
      .object({
        success: z.boolean().meta({ description: "Success status" }),
        id: z.uuid().meta({ description: "User ID" }),
        notify: z.enum(["email", "push", "none"]).meta({
          description: "Notification type",
        }),
      })
      .meta({ description: "Response object" }),
    async handle(req, { id }) {
      const body = await req.json();
      const notify = req.nextUrl.searchParams.get("notify");
 
      return UserService.updateUser(id, body, notify);
    },
  });
}

The code above is fetched from GitHub repository.

`StreamController` and `StreamService`

/api/streams/tokens streams tokens using a controller generator method that delegates with yield* to the service. Each streamed item is validated via the iteration schema. Delays are simulated with setTimeout.

StreamController.ts

src/modules/stream/StreamController.ts


import { prefix, get, operation } from "vovk";
import { withZod } from "vovk-zod";
import { z } from "zod";
import StreamService from "./StreamService";
 
@prefix("streams")
export default class StreamController {
  @operation({
    summary: "Stream tokens",
    description: "Stream tokens to the client",
  })
  @get("tokens")
  static streamTokens = withZod({
    iteration: z
      .object({
        message: z.string().meta({ description: "Message from the token" }),
      })
      .meta({
        description: "Streamed token object",
      }),
    async *handle() {
      yield* StreamService.streamTokens();
    },
  });
}

The code above is fetched from GitHub repository.

React Components

The demo uses @tanstack/react-query for both standard requests and streaming.

index.tsx

src/components/Demo/index.tsx


"use client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import StreamDemo from "./StreamDemo";
import UserFormDemo from "./UserFormDemo";
 
const queryClient = new QueryClient();
 
const Demo = () => {
  return (
    <QueryClientProvider client={queryClient}>
      <StreamDemo />
      <h2 className="text-lg font-bold mb-1 text-center">
        &quot;Update User&quot; Demo
      </h2>
      <p className="text-xs mb-4 text-center">
        <strong>*</strong> form validation isn&apos;t enabled for demo purposes
      </p>
      <UserFormDemo />
    </QueryClientProvider>
  );
};
 
export default Demo;

The code above is fetched from GitHub repository.

UserFormDemo.tsx

src/components/Demo/UserFormDemo.tsx


"use client";
import React, { useState } from "react";
import type { VovkQuery } from "vovk";
import { useMutation } from "@tanstack/react-query";
import { UserRPC } from "../../client/root"; // segmented client
 
const UserFormDemo = () => {
  const [disableClientValidation, setDisableClientValidation] = useState(false);
  const [name, setName] = useState("John Doe");
  const [age, setAge] = useState(35);
  const [email, setEmail] = useState("john@example.com");
  const [id, setId] = useState("a937629d-e8f6-4b1e-a819-7669358650a0");
  const [notify, setNotify] = useState<
    VovkQuery<typeof UserRPC.updateUser>["notify"]
  >(
    "sms" as "email", // intentionally use an invalid value
  );
 
  const updateUserMutation = useMutation({
    mutationFn: UserRPC.updateUser,
  });
 
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
 
    updateUserMutation.mutate({
      body: {
        email,
        profile: {
          name,
          age,
        },
      },
      query: { notify },
      params: { id },
      disableClientValidation,
    });
  };
  return (
    <form onSubmit={handleSubmit}>
      <h3>Body</h3>
      <div>
        <label>User email</label>
        <input
          name="email"
          placeholder="john@example.com"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
        />
      </div>
      <div>
        <label>User full name</label>
        <input
          name="name"
          type="text"
          placeholder="John Doe"
          value={name}
          onChange={(e) => setName(e.target.value)}
        />
      </div>
      <div>
        <label>User age</label>
        <input
          name="age"
          type="number"
          placeholder="35"
          value={age}
          onChange={(e) => setAge(Number(e.target.value))}
        />
      </div>
 
      <h3>Params</h3>
      <div>
        <label>User ID</label>
        <input
          name="id"
          type="text"
          placeholder="123e4567-e89b-12d3-a456-426614174000"
          value={id}
          onChange={(e) => setId(e.target.value)}
        />
      </div>
      <h3>Query</h3>
      <div>
        <label>Notification type</label>
        <select
          name="notify"
          value={notify}
          onChange={(e) =>
            setNotify(e.target.value as "email" | "push" | "none")
          }
        >
          <option value="none">None</option>
          <option value="email">Email</option>
          <option value="push">Push</option>
          <option value="sms">SMS (error)</option>
        </select>
      </div>
      <br />
      <label>
        <input
          type="checkbox"
          onChange={({ target }) => setDisableClientValidation(target.checked)}
          checked={disableClientValidation}
        />{" "}
        Disable client-side input validation
      </label>
      <button type="submit">Submit</button>
      {(updateUserMutation.data || updateUserMutation.error) && (
        <output>
          <strong>Response:</strong>{" "}
          {updateUserMutation.error ? (
            <div className="text-red-500">
              {updateUserMutation.error.message}
            </div>
          ) : (
            <div className="text-green-500">
              {JSON.stringify(updateUserMutation.data)}
            </div>
          )}
        </output>
      )}
    </form>
  );
};
 
export default UserFormDemo;

The code above is fetched from GitHub repository.

StreamDemo.tsx

src/components/Demo/StreamDemo.tsx


"use client";
import {
  useQuery,
  experimental_streamedQuery as streamedQuery,
} from "@tanstack/react-query";
import { StreamRPC } from "../../client/root"; // segmented client
 
const StreamDemo = () => {
  const { data, refetch } = useQuery({
    queryKey: StreamRPC.streamTokens.queryKey(),
    queryFn: streamedQuery({
      streamFn: () => StreamRPC.streamTokens(),
    }),
  });
 
  return (
    <div className="h-20 cursor-pointer" onClick={() => refetch()}>
      {data?.map((token, index) => (
        <span key={index}>{token.message}</span>
      ))}
    </div>
  );
};
export default StreamDemo;

The code above is fetched from GitHub repository.

Config

The app is configured to:

Client-side validation via Ajv.
Generate Rust and Python code when running vovk dev or vovk generate.
Demonstrate the segmented client, generating RPC modules per segment.
Generate clients and bundle with an explicit origin:
- Python and Rust clients: use https://hello-world.vovk.dev.
- TypeScript Bundle: use https://hello-world.vovk.dev.
- Composed TypeScript client:
  - In development: use http://localhost:PORT (so Node.js via vovk-client can call locally).
  - In production: use an empty origin (requests are relative to the current origin).
- Segmented client: use an empty origin (requests are relative to the current origin).

vovk.config.js


// @ts-check
 
const PROD_ORIGIN = "https://hello-world.vovk.dev";
// Commented lines indicate default values
/** @type {import('vovk').VovkConfig} */
const config = {
  logLevel: "debug",
  outputConfig: {
    imports: {
      validateOnClient: "vovk-ajv",
    },
    openAPIObject: {
      info: {
        title: '"Hello World" app API',
        description:
          'API for "Hello World" app hosted at https://hello-world.vovk.dev/. Source code is available on Github https://github.com/finom/vovk-hello-world.',
        license: {
          name: "MIT",
          url: "https://opensource.org/licenses/MIT",
        },
        version: "1.0.0",
      },
      servers: [
        {
          url: "https://hello-world.vovk.dev",
          description: "Production",
        },
        {
          url: "http://localhost:3000",
          description: "Localhost",
        },
      ],
    },
  },
  composedClient: {
    fromTemplates: ["mjs", "cjs", "py", "rs"],
    // enabled: true,
    // outDir: "./node_modules/.vovk-client",
    outputConfig: {
      origin:
        process.env.NODE_ENV === "production"
          ? null
          : `http://localhost:${process.env.PORT ?? 3000}`,
    },
    // prettifyClient: false,
  },
  segmentedClient: {
    // fromTemplates: ["ts"],
    enabled: true,
    // outDir: "./src/client",
    // outputConfig: { origin: '' },
    // prettifyClient: true,
  },
  bundle: {
    outputConfig: { origin: PROD_ORIGIN },
    keepPrebundleDir: true,
    build: async ({ entry, outDir }) => {
      const { build } = await import("tsdown");
      await build({
        entry,
        dts: true,
        format: ["cjs", "esm"],
        hash: false,
        fixedExtension: true,
        clean: true,
        outDir,
        tsconfig: "./tsconfig.bundle.json",
      });
    },
  },
  clientTemplateDefs: {
    py: {
      extends: "py",
      outputConfig: { origin: PROD_ORIGIN },
      // composedClient: { outDir: "./dist_python" },
    },
    rs: {
      extends: "rs",
      outputConfig: { origin: PROD_ORIGIN },
      // composedClient: { outDir: "./dist_rust" },
    },
  },
};
 
module.exports = config;

The code above is fetched from GitHub repository.

OpenAPI Specification

The OpenAPI specification is served by a GET endpoint returning the generated spec (openapi from vovk-client/openapi).

src/modules/static/openapi/OpenApiController.ts


import { get, operation } from "vovk";
import { openapi } from "vovk-client/openapi";
 
export default class OpenApiController {
  @operation({
    summary: "OpenAPI spec",
    description: 'Get the OpenAPI spec for the "Hello World" app API',
  })
  @get("openapi.json", { cors: true })
  static getSpec = () => openapi;
}

The code above is fetched from GitHub repository.

The spec includes Scalar‑compatible samples you can reuse immediately.

https://hello-world.vovk.dev/openapi

Building and Packaging

This example also demonstrates how to quickly produce distributable packages published on npm , PyPI , and crates.io . The provided templates compile ready-to-use packages with language-specific files such as package.json , Cargo.toml , and pyproject.toml , as well as README files that use code samples served as API/client documentation.

npm run patch:

Verifies a clean working tree.
Bumps the patch version.
Triggers postversion to regenerate clients, bundle TypeScript, publish all packages, and create a commit + tag.


"scripts": {
  // ...
  "publish:node": "npm publish ./dist",
  "publish:rust": "cargo publish --manifest-path dist_rust/Cargo.toml --allow-dirty",
  "publish:python": "python3 -m build ./dist_python --wheel --sdist && python3 -m twine upload ./dist_python/dist/*",
  "git-tag": "git add . && git commit -m \"chore: release v$(node -p \"require('./package.json').version\")\" && git tag v$(node -p \"require('./package.json').version\")",
  "check-uncommitted": "git diff --quiet && git diff --cached --quiet || (echo '❌ Uncommitted changes!' && exit 1)",
  "postversion": "vovk generate && vovk bundle && npm run publish:node && npm run publish:rust && npm run publish:python && npm run git-tag",
  "patch": "npm run check-uncommitted && npm version patch --no-git-tag-version"
}

The README.md files are also updated with the latest examples and descriptions. IFrames below are rendered from the READMEs by Github Pages.

TypeScript

https://finom.github.io/vovk-hello-world/dist/

Node.js, Rust, and Python CLI Demo

The repository includes CLI demos for invoking RPC methods from Node.js, Rust, and Python. Each language has two variants:

local: uses locally generated clients.
- Rust / Python still target https://hello-world.vovk.dev for simplicity.
- Node.js hits http://localhost:PORT (run npm run dev separately).
packaged: uses published registries; all call https://hello-world.vovk.dev.

Each demo invokes updateUser, streamTokens, and getSpec.

Node.js

demo/node/packaged.mts


import { UserRPC, OpenApiRPC, StreamRPC } from "vovk-hello-world";
 
async function main() {
  console.log("\n--- Node.js Demo (Packaged) ---");
  const updateUserResponse = await UserRPC.updateUser({
    params: {
      id: "123e4567-e89b-12d3-a456-426614174000",
    },
    body: {
      email: "john@example.com",
      profile: {
        name: "John Doe",
        age: 25,
      },
    },
    query: {
      notify: "email",
    },
  });
 
  console.log("UserRPC.updateUser response:", updateUserResponse);
 
  const openapiResponse = await OpenApiRPC.getSpec();
  console.log(
    `OpenApiRPC.getSpec response: ${openapiResponse.info.title} ${openapiResponse.info.version}`,
  );
 
  const streamResponse = await StreamRPC.streamTokens();
  console.log(`streamTokens:`);
  for await (const item of streamResponse) {
    process.stdout.write(item.message);
  }
  process.stdout.write("\n");
}
main().catch(console.error);

The code above is fetched from GitHub repository.

Python

demo/python/packaged.py


from vovk_hello_world import UserRPC, OpenApiRPC, StreamRPC
 
def main() -> None:
    print("\n--- Python Demo (Packaged) ---")
 
    body: UserRPC.UpdateUserBody = {
        "email": "john@example.com",
        "profile": {
            "name": "John Doe",
            "age": 25
        }
    }
    query: UserRPC.UpdateUserQuery = {"notify": "email"}
    params: UserRPC.UpdateUserParams = {"id": "123e4567-e89b-12d3-a456-426614174000"}
    update_user_response = UserRPC.update_user(
        params=params,
        body=body,
        query=query
    )
    print('UserRPC.update_user response:', update_user_response)
    
    openapi_response = OpenApiRPC.get_spec()
    print(f"OpenApiRPC.get_spec response: {openapi_response['info']['title']} {openapi_response['info']['version']}")
    
    stream_response = StreamRPC.stream_tokens()
    print("StreamRPC.stream_tokens response:")
    for item in stream_response:
        print(item['message'], end='', flush=True)
    print()  # Add newline after streaming
 
if __name__ == "__main__":
    try:
        main()
    except Exception as e:
        print(f"Error: {e}")

The code above is fetched from GitHub repository.

Rust

demo/rust/packaged/src/main.rs


use std::io::Write;
use vovk_hello_world::{
  user_rpc, 
  open_api_rpc, 
  stream_rpc 
};
pub fn main() {
  println!("\n--- Rust Demo (Packaged) ---");
  use user_rpc::update_user_::{
    body as Body, 
    body_::profile as Profile,
    query as Query,
    query_::notify as Notify,
    params as Params,
  };
 
  let update_user_response = user_rpc::update_user(
    Body {
      email: String::from("john@example.com"),
      profile: Profile {
        name: String::from("John Doe"),
        age: 25
      }
    },
    Query {
      notify: Notify::email
    },
    Params {
      id: String::from("123e4567-e89b-12d3-a456-426614174000")
    },
    None,
    None,
    false,
  );
 
  match update_user_response {
    Ok(response) => println!("user_rpc.update_user response: {:?}", response),
    Err(e) => println!("update_user error: {:?}", e),
  }
 
  let openapi_response = open_api_rpc::get_spec(
    (),
    (),
    (),
    None,
    None,
    false,
  );
 
  match openapi_response {
    Ok(spec) => {
      if let (Some(title), Some(version)) = (
        spec["info"]["title"].as_str(),
        spec["info"]["version"].as_str()
      ) {
        println!("open_api_rpc.get_spec response: {} {}", title, version);
      } else {
        println!("Could not extract title or version from OpenAPI spec");
      }
    },
    Err(e) => println!("Error fetching OpenAPI spec: {:?}", e),
  }
 
  let stream_response = stream_rpc::stream_tokens(
      (),
      (),
      (),
      None,
      None,
      false,
  );
  
  match stream_response {
    Ok(stream) => {
      print!("stream_rpc.stream_tokens response:\n");
      for (_i, item) in stream.enumerate() {
        print!("{}", item.message.as_str());
        std::io::stdout().flush().unwrap();
      }
      println!();
    },
    Err(e) => println!("Error initiating stream: {:?}", e),
  }
}

The code above is fetched from GitHub repository.

Local demos differ only by import paths (Node.js: vovk-client; Python: minor import workarounds; Rust: dependency path in Cargo.toml).

Conclusion

Even with only three endpoints (updateUser, streamTokens, getSpec), Vovk.ts delivers:

Turnkey multi-language client generation (TypeScript bundle + Rust + Python) with publish-ready metadata and READMEs.
Rich, documented OpenAPI output rendered via Scalar.
Text streaming and unified client-side validation flows.

Additional topics not shown here include Function Calling (LLM tool generation), source‑only templates, custom decorators, advanced imports configuration, and more—explore the docs for deeper features.

“Hello World” Example

Running the Example Locally

Topics and Concepts Covered

Live Demo

`UserController` and `UserService`

UserController.ts

UserService.ts

`StreamController` and `StreamService`

StreamController.ts

StreamService.ts

React Components

index.tsx

UserFormDemo.tsx

StreamDemo.tsx

Config

OpenAPI Specification

Building and Packaging

TypeScript

Rust

Python

Node.js, Rust, and Python CLI Demo

Node.js

Python

Rust

Conclusion

“Hello World” Example

Running the Example Locally

Topics and Concepts Covered

Live Demo

UserController and UserService

UserController.ts

UserService.ts

StreamController and StreamService

StreamController.ts

StreamService.ts

React Components

index.tsx

UserFormDemo.tsx

StreamDemo.tsx

Config

OpenAPI Specification

Building and Packaging

TypeScript

Rust

Python

Node.js, Rust, and Python CLI Demo

Node.js

Python

Rust

Conclusion

`UserController` and `UserService`

`StreamController` and `StreamService`