From 1576c47c570b054886708b87c42402353fab4ea4 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 19:46:15 +0000 Subject: [PATCH 1/5] docs: improve README discoverability with badges, comparison table, and roadmap Add badges, a problem/solution intro, a Vision vs Encore.ts/OpenTelemetry/Sentry comparison table, an OTel export feature entry, and a checkbox-style Roadmap section to make the project's value proposition clearer at a glance. --- README.md | 107 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 80 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index f29f932..854b139 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,75 @@ # Vision 🔮 + + +[![npm version](https://img.shields.io/npm/v/@getvision/server.svg)](https://www.npmjs.com/package/@getvision/server) +[![npm downloads](https://img.shields.io/npm/dm/@getvision/server.svg)](https://www.npmjs.com/package/@getvision/server) +[![CI](https://github.com/ephor/vision/actions/workflows/ci.yml/badge.svg)](https://github.com/ephor/vision/actions/workflows/ci.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) +[![GitHub stars](https://img.shields.io/github/stars/ephor/vision.svg?style=social)](https://github.com/ephor/vision/stargazers) + **Universal observability dashboard for API development** Vision is a development dashboard that provides unified observability across protocols and validation libraries. Add it to your existing Express, Fastify, or Hono application. -> Protocol-agnostic monitoring with support for REST (GraphQL, tRPC, and MCP are in development) +> Protocol-agnostic monitoring with support for REST today — see the [Roadmap](#roadmap) for GraphQL, tRPC, and MCP +
Vision Dashboard - API observability and testing interface
--- +## Why Vision + +Observability for APIs usually means a tradeoff. **Encore.ts** gives you a dashboard, but only if you rebuild your app on its framework and runtime. **OpenTelemetry** gives you a vendor-neutral standard, but you're wiring up an SDK, a collector, and a backend yourself. **Sentry** is quick to install, but it's built for error tracking, not a request/response playground for everyday API development. + +Vision drops into the Express, Fastify, or Hono app you already have — two lines of code, no rewrite — and gives you live traces, logs, and a request playground in your browser. Prefer to start clean? `@getvision/server` is an Elysia-based meta-framework with Vision built in. Either way, it's self-hosted, runs alongside your app, and you keep your code. + +### Vision vs. the alternatives + +| | **Vision** | **Encore.ts** | **OpenTelemetry** | **Sentry** | +| -------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | +| Setup time | ~2 lines in an existing app | Framework rewrite (Encore runtime/SDK) | Manual instrumentation + collector/backend config | SDK install, minutes | +| Vendor / code lock-in | None — middleware on your existing app | High — app is built on Encore's framework | None — open standard | Low-medium — SDK calls, hosted backend by default | +| Self-hosted | Yes (in-process dashboard) | Yes, self-hostable; cloud platform optional | Yes (Collector + backend of your choice) | Self-hosted available, but under a non-OSS license (FSL) | +| Multi-protocol (REST/GraphQL/tRPC/MCP) | REST today; GraphQL, tRPC, MCP on the [Roadmap](#roadmap) | REST/RPC via Encore's own framework | Protocol-agnostic, but you instrument each one yourself | Mainly HTTP/REST tracing | +| Validation library integration | Zod, Valibot, Standard Schema v1 (auto request templates) | Encore's own validation (TypeScript types → API) | None — not in scope for OTel | None — not in scope | +| License / cost | MIT, free | Apache 2.0 (open source) + paid Encore Cloud platform | Apache 2.0, free (you pay for the backend you export to) | BSL/FSL source-available; paid SaaS for hosted plans | + +_(Comparison based on each project's public docs as of writing; correct an inaccuracy by opening an issue or PR.)_ + +--- + ## Features ### Multi-Protocol Support + - REST APIs, GraphQL, tRPC, and Model Context Protocol (MCP) - Unified tracing across all protocols - Service catalog with auto-discovery ### Validation Library Integration + - **Zod** - Full feature support -- **Valibot** - Modern validation support +- **Valibot** - Modern validation support - **Standard Schema v1** - Universal compatibility - Automatic request template generation - Real-time validation error display ### Development Tools + - API playground with multi-tab testing - Live logs with trace context - Performance monitoring - TypeScript-first implementation +### Export & Integration + +- OpenTelemetry export (new) - OTLP/HTTP exporter (`@getvision/server` `vision.exporters`) for sending traces to Honeycomb, Grafana Tempo, BetterStack, an OTel Collector, or any OTLP-compatible backend + --- ## Logging Philosophy @@ -49,31 +87,35 @@ Vision implements the **Wide Events** logging approach - add context once, see i ### Add to Existing App (Express Example) ```typescript -import express from 'express' -import { visionAdapter } from '@getvision/adapter-express' -import { z } from 'zod' // or v from 'valibot'! +import express from "express"; +import { visionAdapter } from "@getvision/adapter-express"; +import { z } from "zod"; // or v from 'valibot'! -const app = express() +const app = express(); // Add Vision in development -if (process.env.NODE_ENV !== 'production') { - app.use('*', visionAdapter({ port: 9500 })) +if (process.env.NODE_ENV !== "production") { + app.use("*", visionAdapter({ port: 9500 })); } // Your existing endpoints - now with Vision! -app.post('/users', +app.post( + "/users", // Automatic template generation! - validator('body', z.object({ - name: z.string(), - email: z.string().email(), - })), + validator( + "body", + z.object({ + name: z.string(), + email: z.string().email(), + }), + ), (req, res) => { // req.body is fully typed and validated - res.json(req.body) - } -) + res.json(req.body); + }, +); -app.listen(3000) +app.listen(3000); // Dashboard at http://localhost:9500 ``` @@ -84,19 +126,18 @@ bun add @getvision/server elysia zod ``` ```typescript -import { createVision, createModule } from '@getvision/server' -import { z } from 'zod' +import { createVision, createModule } from "@getvision/server"; +import { z } from "zod"; -const usersModule = createModule({ prefix: '/users' }) - .post( - '/', - async ({ body }) => ({ id: crypto.randomUUID(), ...body }), - { body: z.object({ name: z.string(), email: z.string().email() }) } - ) +const usersModule = createModule({ prefix: "/users" }).post( + "/", + async ({ body }) => ({ id: crypto.randomUUID(), ...body }), + { body: z.object({ name: z.string(), email: z.string().email() }) }, +); -createVision({ service: { name: 'My API' } }) +createVision({ service: { name: "My API" } }) .use(usersModule) - .listen(3000) + .listen(3000); // Dashboard at http://localhost:9500 ``` @@ -112,6 +153,18 @@ createVision({ service: { name: 'My API' } }) --- +## Roadmap + +- [x] REST +- [x] OpenTelemetry export (new) +- [ ] GraphQL +- [ ] tRPC +- [ ] MCP + +See the full [roadmap](https://getvision.dev/docs/roadmap) for details on what's planned. + +--- + ## Documentation Full documentation at **[getvision.dev/docs](https://getvision.dev/docs)** From a883034d9352d12e6a6ded3891c1a195252050aa Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 19:52:35 +0000 Subject: [PATCH 2/5] docs: refocus comparison table on Encore.ts and OpenTelemetry Drop Sentry from the comparison: it's a production error-tracking SaaS, a different lifecycle stage from Vision's dev-time dashboard, so a parity table overstated the rivalry. Reframe OpenTelemetry as a standard Vision exports to (complement, not competitor) and add a built-in dashboard/UI row. --- README.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 854b139..b0d67b1 100644 --- a/README.md +++ b/README.md @@ -24,22 +24,23 @@ Vision is a development dashboard that provides unified observability across pro ## Why Vision -Observability for APIs usually means a tradeoff. **Encore.ts** gives you a dashboard, but only if you rebuild your app on its framework and runtime. **OpenTelemetry** gives you a vendor-neutral standard, but you're wiring up an SDK, a collector, and a backend yourself. **Sentry** is quick to install, but it's built for error tracking, not a request/response playground for everyday API development. +Observability for APIs usually means a tradeoff. **Encore.ts** gives you a built-in dashboard, but only if you rebuild your app on its framework and runtime. **OpenTelemetry** gives you a vendor-neutral standard, but it's plumbing — you wire up an SDK, a collector, and a backend before you see anything. -Vision drops into the Express, Fastify, or Hono app you already have — two lines of code, no rewrite — and gives you live traces, logs, and a request playground in your browser. Prefer to start clean? `@getvision/server` is an Elysia-based meta-framework with Vision built in. Either way, it's self-hosted, runs alongside your app, and you keep your code. +Vision drops into the Express, Fastify, or Hono app you already have — two lines of code, no rewrite — and gives you live traces, logs, and a request playground in your browser while you build. Prefer to start clean? `@getvision/server` is an Elysia-based meta-framework with Vision built in. It's self-hosted, runs alongside your app, and you keep your code — and when you're ready to ship telemetry to production, Vision speaks OTLP, so the same traces export straight into your OpenTelemetry backend. ### Vision vs. the alternatives -| | **Vision** | **Encore.ts** | **OpenTelemetry** | **Sentry** | -| -------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------- | -| Setup time | ~2 lines in an existing app | Framework rewrite (Encore runtime/SDK) | Manual instrumentation + collector/backend config | SDK install, minutes | -| Vendor / code lock-in | None — middleware on your existing app | High — app is built on Encore's framework | None — open standard | Low-medium — SDK calls, hosted backend by default | -| Self-hosted | Yes (in-process dashboard) | Yes, self-hostable; cloud platform optional | Yes (Collector + backend of your choice) | Self-hosted available, but under a non-OSS license (FSL) | -| Multi-protocol (REST/GraphQL/tRPC/MCP) | REST today; GraphQL, tRPC, MCP on the [Roadmap](#roadmap) | REST/RPC via Encore's own framework | Protocol-agnostic, but you instrument each one yourself | Mainly HTTP/REST tracing | -| Validation library integration | Zod, Valibot, Standard Schema v1 (auto request templates) | Encore's own validation (TypeScript types → API) | None — not in scope for OTel | None — not in scope | -| License / cost | MIT, free | Apache 2.0 (open source) + paid Encore Cloud platform | Apache 2.0, free (you pay for the backend you export to) | BSL/FSL source-available; paid SaaS for hosted plans | - -_(Comparison based on each project's public docs as of writing; correct an inaccuracy by opening an issue or PR.)_ +| | **Vision** | **Encore.ts** | **OpenTelemetry** | +| -------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------- | +| Setup time | ~2 lines in an existing app | Framework rewrite (Encore runtime/SDK) | Manual instrumentation + collector/backend config | +| Vendor / code lock-in | None — middleware on your existing app | High — app is built on Encore's framework | None — open standard | +| Self-hosted | Yes (in-process dashboard) | Yes, self-hostable; cloud platform optional | Yes (Collector + backend of your choice) | +| Built-in dashboard / UI | Yes — traces, logs, request playground | Yes — local dev dashboard + cloud | No — bring your own (Jaeger, Grafana, …) | +| Multi-protocol (REST/GraphQL/tRPC/MCP) | REST today; GraphQL, tRPC, MCP on the [Roadmap](#roadmap) | REST/RPC via Encore's own framework | Protocol-agnostic, but you instrument each one yourself | +| Validation library integration | Zod, Valibot, Standard Schema v1 (auto request templates) | Encore's own validation (TypeScript types → API) | None — not in scope for OTel | +| License / cost | MIT, free | Apache 2.0 (open source) + paid Encore Cloud platform | Apache 2.0, free (you pay for the backend you export to) | + +_OpenTelemetry isn't really a competitor — it's a standard Vision exports to. Vision is the dev-time UX; OTel is the wire format for shipping those traces onward. Comparison based on each project's public docs as of writing; correct an inaccuracy by opening an issue or PR._ --- From 5c8f94aceff5b29ea47ef2cc613512804ae2dd4a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 19:57:05 +0000 Subject: [PATCH 3/5] docs: make comparison a Vision-vs-Encore.ts table with OTLP as a feature row MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop OpenTelemetry as a competitor column — it's a standard Vision exports to, not a rival. Narrow the table to the one true peer (Encore.ts) and surface OTLP export as a feature row, where Vision ships today and Encore's native export is still announced/coming soon. --- README.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index b0d67b1..c080744 100644 --- a/README.md +++ b/README.md @@ -28,19 +28,23 @@ Observability for APIs usually means a tradeoff. **Encore.ts** gives you a built Vision drops into the Express, Fastify, or Hono app you already have — two lines of code, no rewrite — and gives you live traces, logs, and a request playground in your browser while you build. Prefer to start clean? `@getvision/server` is an Elysia-based meta-framework with Vision built in. It's self-hosted, runs alongside your app, and you keep your code — and when you're ready to ship telemetry to production, Vision speaks OTLP, so the same traces export straight into your OpenTelemetry backend. -### Vision vs. the alternatives - -| | **Vision** | **Encore.ts** | **OpenTelemetry** | -| -------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------- | -------------------------------------------------------- | -| Setup time | ~2 lines in an existing app | Framework rewrite (Encore runtime/SDK) | Manual instrumentation + collector/backend config | -| Vendor / code lock-in | None — middleware on your existing app | High — app is built on Encore's framework | None — open standard | -| Self-hosted | Yes (in-process dashboard) | Yes, self-hostable; cloud platform optional | Yes (Collector + backend of your choice) | -| Built-in dashboard / UI | Yes — traces, logs, request playground | Yes — local dev dashboard + cloud | No — bring your own (Jaeger, Grafana, …) | -| Multi-protocol (REST/GraphQL/tRPC/MCP) | REST today; GraphQL, tRPC, MCP on the [Roadmap](#roadmap) | REST/RPC via Encore's own framework | Protocol-agnostic, but you instrument each one yourself | -| Validation library integration | Zod, Valibot, Standard Schema v1 (auto request templates) | Encore's own validation (TypeScript types → API) | None — not in scope for OTel | -| License / cost | MIT, free | Apache 2.0 (open source) + paid Encore Cloud platform | Apache 2.0, free (you pay for the backend you export to) | - -_OpenTelemetry isn't really a competitor — it's a standard Vision exports to. Vision is the dev-time UX; OTel is the wire format for shipping those traces onward. Comparison based on each project's public docs as of writing; correct an inaccuracy by opening an issue or PR._ +### Vision vs. Encore.ts + +The closest comparison is **Encore.ts** — it also pairs API code with an auto-generated dashboard. The difference is what you give up to get one: + +| | **Vision** | **Encore.ts** | +| ---------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------- | +| Setup | ~2 lines in an app you already have | Rewrite onto Encore's runtime/SDK | +| Works with existing Express/Fastify/Hono | Yes — drop-in middleware | No — you adopt Encore's framework | +| Vendor / code lock-in | None | High — app is built on Encore's framework | +| Built-in dashboard / UI | Yes — traces, logs, request playground | Yes — local dev dashboard + cloud | +| Multi-protocol (REST/GraphQL/tRPC/MCP) | REST today; GraphQL, tRPC, MCP on the [Roadmap](#roadmap) | REST/RPC via Encore's own framework | +| Validation library integration | Zod, Valibot, Standard Schema v1 (auto request templates) | Encore's own validation (TypeScript types → API) | +| OpenTelemetry / OTLP export | Yes — OTLP/HTTP, shipped | Announced, coming soon | +| Self-hosted | Yes (in-process dashboard) | Yes, self-hostable; cloud platform optional | +| License / cost | MIT, free | Apache 2.0 (open source) + paid Encore Cloud platform | + +_OpenTelemetry isn't on this list on purpose — it's a standard Vision exports to, not a competitor. Vision is the dev-time UX; OTel is the wire format for shipping those traces to whatever backend you run. Comparison based on each project's public docs as of writing; correct an inaccuracy by opening an issue or PR._ --- From 9e3585afb4349edb1433cdf4926b5c7cab9ceb1a Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 19:59:52 +0000 Subject: [PATCH 4/5] docs: add develop-locally-ship-to-prod tagline, drop comparison footnote MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Surface the "develop with Vision locally → ship the same traces to whatever prod backend you already run" line in the intro, and remove the footnote under the comparison table. --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c080744..d416ee6 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,9 @@ Vision is a development dashboard that provides unified observability across pro Observability for APIs usually means a tradeoff. **Encore.ts** gives you a built-in dashboard, but only if you rebuild your app on its framework and runtime. **OpenTelemetry** gives you a vendor-neutral standard, but it's plumbing — you wire up an SDK, a collector, and a backend before you see anything. -Vision drops into the Express, Fastify, or Hono app you already have — two lines of code, no rewrite — and gives you live traces, logs, and a request playground in your browser while you build. Prefer to start clean? `@getvision/server` is an Elysia-based meta-framework with Vision built in. It's self-hosted, runs alongside your app, and you keep your code — and when you're ready to ship telemetry to production, Vision speaks OTLP, so the same traces export straight into your OpenTelemetry backend. +Vision drops into the Express, Fastify, or Hono app you already have — two lines of code, no rewrite — and gives you live traces, logs, and a request playground in your browser while you build. Prefer to start clean? `@getvision/server` is an Elysia-based meta-framework with Vision built in. It's self-hosted, runs alongside your app, and you keep your code. + +**Develop with Vision locally → ship the same traces to whatever prod backend you already run (Grafana, Honeycomb, Datadog, OTel Collector).** ### Vision vs. Encore.ts @@ -44,8 +46,6 @@ The closest comparison is **Encore.ts** — it also pairs API code with an auto- | Self-hosted | Yes (in-process dashboard) | Yes, self-hostable; cloud platform optional | | License / cost | MIT, free | Apache 2.0 (open source) + paid Encore Cloud platform | -_OpenTelemetry isn't on this list on purpose — it's a standard Vision exports to, not a competitor. Vision is the dev-time UX; OTel is the wire format for shipping those traces to whatever backend you run. Comparison based on each project's public docs as of writing; correct an inaccuracy by opening an issue or PR._ - --- ## Features From e6bc21a50f3bb6744c7ec07bca23f44de5dd964c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 30 Jun 2026 20:02:31 +0000 Subject: [PATCH 5/5] docs: remove manual gh-topics TODO from README Drop the ops instruction comment from the public README; it doesn't belong in user-facing docs. --- README.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/README.md b/README.md index d416ee6..34447a3 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,5 @@ # Vision 🔮 - - [![npm version](https://img.shields.io/npm/v/@getvision/server.svg)](https://www.npmjs.com/package/@getvision/server) [![npm downloads](https://img.shields.io/npm/dm/@getvision/server.svg)](https://www.npmjs.com/package/@getvision/server) [![CI](https://github.com/ephor/vision/actions/workflows/ci.yml/badge.svg)](https://github.com/ephor/vision/actions/workflows/ci.yml)