Skip to content

docs: reorder landing and clarify service evaluation paths #253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
intech merged 1 commit into from
Nov 4, 2026
Merged

docs: reorder landing and clarify service evaluation paths #253

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions .vitepress/data/modules.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ export const publicModules = [
guide: '/en/guide/auth',
api: '/en/api/@connectum/auth/',
source: 'https://github.com/Connectum-Framework/connectum/tree/main/packages/auth',
example: 'https://github.com/Connectum-Framework/examples/tree/main/auth',
example: 'https://github.com/Connectum-Framework/examples/tree/main/car-sharing',
entryPoints: ['createJwtAuthInterceptor', 'createAuthzInterceptor', 'requireAuthContext'],
},
{
Expand All @@ -62,18 +62,18 @@ export const publicModules = [
name: '@connectum/events-nats',
category: 'Communication',
summary: 'NATS JetStream adapter for the Connectum EventBus.',
guide: '/en/guide/events/adapters',
guide: '/en/guide/events/adapters#nats-jetstream-adapter',
api: '/en/api/@connectum/events-nats/',
source: 'https://github.com/Connectum-Framework/connectum/tree/main/packages/events-nats',
example: 'https://github.com/Connectum-Framework/examples/tree/main/with-events-nats',
example: 'https://github.com/Connectum-Framework/examples/tree/main/with-events-dlq',
entryPoints: ['NatsAdapter', 'NatsAdapterOptions'],
},
{
slug: 'events-kafka',
name: '@connectum/events-kafka',
category: 'Communication',
summary: 'Kafka and Redpanda adapter for the Connectum EventBus.',
guide: '/en/guide/events/adapters',
guide: '/en/guide/events/adapters#kafka-adapter',
api: '/en/api/@connectum/events-kafka/',
source: 'https://github.com/Connectum-Framework/connectum/tree/main/packages/events-kafka',
example: 'https://github.com/Connectum-Framework/examples/tree/main/with-events-kafka',
Expand All @@ -84,7 +84,7 @@ export const publicModules = [
name: '@connectum/events-redis',
category: 'Communication',
summary: 'Redis Streams and Valkey adapter for the Connectum EventBus.',
guide: '/en/guide/events/adapters',
guide: '/en/guide/events/adapters#redis-streams-adapter',
api: '/en/api/@connectum/events-redis/',
source: 'https://github.com/Connectum-Framework/connectum/tree/main/packages/events-redis',
example: 'https://github.com/Connectum-Framework/examples/tree/main/with-events-valkey',
Expand All @@ -95,7 +95,7 @@ export const publicModules = [
name: '@connectum/events-amqp',
category: 'Communication',
summary: 'AMQP and RabbitMQ adapter with topology and reliable-publishing controls.',
guide: '/en/guide/events/adapters',
guide: '/en/guide/events/adapters#amqp--rabbitmq-adapter',
api: '/en/api/@connectum/events-amqp/',
source: 'https://github.com/Connectum-Framework/connectum/tree/main/packages/events-amqp',
example: 'https://github.com/Connectum-Framework/examples/tree/main/with-events-amqp',
Expand Down Expand Up @@ -126,7 +126,7 @@ export const publicModules = [
slug: 'reflection',
name: '@connectum/reflection',
category: 'Operations',
summary: 'gRPC Server Reflection for discovery, inspection, and tooling.',
summary: 'gRPC Server Reflection for schema inspection and client tooling.',
guide: '/en/guide/protocols/reflection',
api: '/en/api/@connectum/reflection/',
source: 'https://github.com/Connectum-Framework/connectum/tree/main/packages/reflection',
Expand All @@ -150,7 +150,7 @@ export const publicModules = [
guide: '/en/guide/service-communication/service-catalog',
api: '/en/api/@connectum/protoc-gen-catalog/',
source: 'https://github.com/Connectum-Framework/connectum/tree/main/packages/protoc-gen-catalog',
entryPoints: ['protoc-gen-catalog'],
entryPoints: ['protoc-gen-connectum-catalog'],
},
{
slug: 'testing',
Expand All @@ -160,7 +160,6 @@ export const publicModules = [
guide: '/en/guide/testing/integration',
api: '/en/api/@connectum/testing/',
source: 'https://github.com/Connectum-Framework/connectum/tree/main/packages/testing',
example: 'https://github.com/Connectum-Framework/examples/tree/main/runn',
entryPoints: ['createTestServer', 'withTestServer', 'createLocalClient'],
},
{
Expand Down
5 changes: 3 additions & 2 deletions .vitepress/homepage/deployment-markup.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,11 @@ export function deploymentMarkup(svg = '') {
<p class="home-eyebrow">Service calls</p>
<h2 id="service-calls-title">Same code.<br>Different deployments.</h2>
<p>Keep your Protobuf contracts and service handlers. Run services together as a monolith, separately as microservices, or in a hybrid deployment.</p>
<p>Call other services with <code>ctx.call()</code>. The same typed call runs in-process or over RPC, depending on your server configuration.</p>
<p>A generated catalog supplies the types for <code>ctx.call()</code>. Local registration and configured remote resolvers choose where each call runs.</p>
<p>These diagrams illustrate routing; endpoints, credentials and process deployment remain your configuration.</p>
<div class="home-inline-links">
<a href="/en/guide/service-communication/service-catalog">Explore service calls →</a>
<a href="/en/guide/service-communication/resolvers">Configure remote routes →</a>
<a href="/en/guide/service-communication/resolver-configuration">Configure remote routes →</a>
</div>
</div>`;
}
119 changes: 65 additions & 54 deletions .vitepress/theme/components/HomePage.vue
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,40 +39,40 @@ onBeforeUnmount(() => revealObserver?.disconnect());
// biome-ignore lint/correctness/noUnusedVariables: the Vue template iterates these goal links.
const goals = [
{
label: 'New to Connectum',
title: 'Build a first service',
description: 'Go from an empty directory to a verified gRPC call with a focused, linear tutorial.',
label: 'Your first service',
title: 'Build a protected RPC',
description: 'Scaffold a project, add a Protobuf method and check calls with and without a JWT.',
link: '/en/guide/quickstart',
action: 'Start the tutorial',
action: 'Follow the quickstart',
},
{
label: 'Building a capability',
title: 'Solve a service task',
description: 'Add validation, service calls, events, authentication, or testing with a guide for the task at hand.',
link: '/en/guide/about#choose-your-path',
action: 'Browse guides',
label: 'Connecting services',
title: 'Choose how services communicate',
description: 'Compare typed RPC calls and events, then choose local or remote routing.',
link: '/en/guide/communication',
action: 'Communication guides',
},
{
label: 'Operating services',
title: 'Deploy and operate services',
description: 'Configure health checks, observability, shutdown, containers, Kubernetes, or a gateway.',
link: '/en/guide/production/kubernetes',
action: 'Explore operations',
label: 'Deploying a service',
title: 'Choose a deployment setup',
description: 'Package the service for containers and find guidance for Kubernetes, gateways and service meshes.',
link: '/en/guide/deploy',
action: 'Deployment guides',
},
{
label: 'Know what you need',
label: 'Exact API',
title: 'Find an exact option',
description: 'Jump by module or symbol into the generated API, compatibility matrix, or migration guidance.',
description: 'Look up exported functions, TypeScript interfaces and configuration fields in the generated API.',
link: '/en/api/',
action: 'Open reference',
action: 'Open the API',
},
] as const;

// biome-ignore lint/correctness/noUnusedVariables: the Vue template iterates these lifecycle entries.
const lifecycle = [
['Define', 'Proto contracts and generated types'],
['Run', 'Server lifecycle and transport'],
['Protect', 'Validation, auth, and resilience'],
['Protect', 'Configured validation, auth and resilience'],
['Observe', 'Traces, metrics, and logs'],
['Operate', 'Health, shutdown, and deployment'],
] as const;
Expand All @@ -97,18 +97,55 @@ const lifecycle = [
<div>
<dt>Compatibility</dt>
<dd>
<a href="/en/guide/runtime-compatibility">Runtime matrix <span aria-hidden="true">→</span></a>
<a href="/en/guide/runtime-compatibility-details#compatibility-matrix">Runtime matrix <span aria-hidden="true">→</span></a>
</dd>
</div>
</dl>
</div>
<div class="home-hero__art" aria-hidden="true"></div>
</section>

<section class="home-section home-ecosystem" aria-labelledby="ecosystem-title">
<div class="home-section__heading home-section__heading--split">
<div>
<p class="home-eyebrow">Fits your stack</p>
<h2 id="ecosystem-title">Build on ConnectRPC and Protobuf.</h2>
</div>
<p>
ConnectRPC supplies the RPC layer. Connectum adds a shared server lifecycle and optional modules for security, telemetry and events.
</p>
</div>
<EcosystemRail />
<p class="home-section__more">
<a href="/en/guide/about#what-connectum-owns">See what Connectum owns →</a>
· <a href="/en/guide/runtime-compatibility-details">Runtime requirements and limits →</a>
</p>
</section>

<section class="home-section home-example" aria-labelledby="example-title">
<div class="home-example__copy">
<p class="home-eyebrow">From contract to handler</p>
<h2 id="example-title">Implement your contract in TypeScript.</h2>
<p>
Define the API in Protobuf, generate its types and implement the handlers as ordinary functions. Register services, middleware and protocols with
<code>createServer()</code>.
</p>
<div class="home-inline-links">
<a href="/en/guide/quickstart-manual">Build a service step by step →</a>
<a href="/en/api/@connectum/core/types/interfaces/CreateServerOptions">CreateServerOptions →</a>
</div>
</div>
<HomeCodeWalkthrough>
<slot name="server-example" />
</HomeCodeWalkthrough>
</section>

<HomeDeployments />

<section class="home-section home-intents" aria-labelledby="start-by-goal">
<div class="home-section__heading">
<p class="home-eyebrow">Start by goal</p>
<h2 id="start-by-goal">Choose a path for the task at hand.</h2>
<h2 id="start-by-goal">Choose your next step.</h2>
</div>
<div class="home-goal-grid">
<!-- biome-ignore lint/a11y/useValidAnchor: Vue binds the real destination through :href. -->
Expand All @@ -128,7 +165,8 @@ const lifecycle = [
<h2 id="lifecycle-title">Add capabilities through explicit modules.</h2>
</div>
<p>
The framework keeps lifecycle and registration predictable while modules remain explicit. Begin with the server; add production behavior as the service grows.
Use the same startup and shutdown model across services, with only the modules each service needs. Your application keeps its database, business logic and
dependency wiring.
</p>
</div>
<ol class="lifecycle-track">
Expand All @@ -138,49 +176,22 @@ const lifecycle = [
<span>{{ detail }}</span>
</li>
</ol>
<p>
For a small RPC endpoint, or when your existing setup already covers these needs, ConnectRPC alone may be enough.
<a href="/en/guide/about">Decide whether Connectum fits your service.</a>
</p>
</section>

<section class="home-section home-ecosystem" aria-labelledby="ecosystem-title">
<div class="home-section__heading home-section__heading--split">
<div>
<p class="home-eyebrow">Fits your stack</p>
<h2 id="ecosystem-title">Choose a runtime for each service.</h2>
</div>
<p>Use ConnectRPC or gRPC, connect to supported brokers, and choose Node.js or Bun for each service.</p>
</div>
<EcosystemRail />
</section>

<section class="home-section home-example" aria-labelledby="example-title">
<div class="home-example__copy">
<p class="home-eyebrow">The central primitive</p>
<h2 id="example-title">Compose a service with an explicit lifecycle.</h2>
<p>
Define a Protobuf contract, generate TypeScript types, implement a handler, and start a server with <code>createServer()</code>. Then call the same service with
Connect and gRPC.
</p>
<div class="home-inline-links">
<a href="/en/guide/quickstart">Follow the full tutorial →</a>
<a href="/en/api/@connectum/core/types/interfaces/CreateServerOptions">CreateServerOptions →</a>
</div>
</div>
<HomeCodeWalkthrough>
<slot name="server-example" />
</HomeCodeWalkthrough>
</section>

<HomeDeployments />

<section class="home-section home-modules" aria-labelledby="modules-title">
<div class="home-section__heading home-section__heading--split">
<div>
<p class="home-eyebrow">Explore modules</p>
<h2 id="modules-title">Find modules by capability.</h2>
</div>
<p>Each module links to its guide, configuration help, and generated API reference.</p>
<p>Choose a capability, then open its Guide or generated API.</p>
</div>
<ModuleGrid />
<p class="home-section__more"><a href="/en/guide/about#modules">Find a module's guide and API →</a></p>
<p class="home-section__more"><a href="/en/guide/production/architecture#extension-seams">Understand module boundaries →</a></p>
</section>

<section class="home-section home-resources" aria-labelledby="resources-title">
Expand Down
Loading
Loading