@roastery/blend

Capsule manifest contract for the Roastery CMS ecosystem — a declarative identity card each capsule implements with its metadata, environment requirements, dependencies, and Barista plugin registration.

Overview

blend defines the contract between a capsule and the host that orchestrates it:

• Blend — Abstract class every capsule implements to declare who it is (name, version, owner, license), what it needs (environmentNeeds, dependencies), and how it plugs into the host app (plugin).
• Owner — Authorship and contact metadata, mirroring a package.json author object.
• Version — Template-literal semver type that keeps every declared version exact at compile time.
• Plugin — Barista plugin function type: receives the host app, returns the extended app.
• Tag — OpenAPI-style tag metadata (name, description, optional externalDocs) used to group a capsule's routes in the host's generated API documentation.

Technologies

| Tool | Purpose | |------|---------| | @roastery/barista | HTTP application framework the Plugin type plugs into | | @roastery/terroir | TypeBox re-exports used by environmentNeeds schemas | | TypeBox | Runtime schema validation and TypeScript type inference | | tsup | Bundling to ESM + CJS with .d.ts generation | | Bun | Runtime, test runner, and package manager | | Knip | Unused exports and dependency detection | | Husky + commitlint | Git hooks and conventional commit enforcement |

Installation

Install the package and its companions:

bun add @roastery/blend @roastery/barista @roastery/terroir typescript

Or install them separately:

# Install the library
bun add @roastery/blend

# Install the ecosystem packages and peer dependencies
bun add @roastery/barista @roastery/terroir typescript

Local development (link)

If you're developing blend alongside another project, you can link it locally:

# Inside the blend directory
bun run setup  # builds and registers the link

# Inside your consuming project
bun link @roastery/blend

Blend

Abstract manifest every capsule implements. It carries no behaviour — subclasses only declare readonly fields, and the orchestration layer reads them to validate the environment, resolve dependencies between capsules, and register plugins on the host application.

import { Blend } from "@roastery/blend";
import type { Owner, Plugin, Tag, Version } from "@roastery/blend/types";
import { t } from "@roastery/terroir";

export class PostCapsule extends Blend {
	public readonly name = "post";
	public readonly version: Version = "0.1.0";
	public readonly owner: Owner = {
		name: "Alan Reis",
		email: "[email protected]",
		repository: "https://github.com/roastery-cms/blend",
	};
	public readonly license = "MIT";
	public readonly environmentNeeds = t.Object({
		DATABASE_URL: t.String(),
		CACHE_PROVIDER: t.Union([t.Literal("REDIS"), t.Literal("MEMORY")]),
	});
	public readonly plugin: Plugin = (app) => app.get("/posts", () => []);
	public readonly dependencies: Record<string, Version> = {
		"post-tag": "0.1.0",
	};
	public readonly tag: Tag = {
		name: "Posts",
		description: "Endpoints for creating and reading blog posts.",
	};
}

Members

| Member | Type | Required | Description | |--------|------|----------|-------------| | name | string | yes | Unique capsule identifier; other manifests use it as a key in their dependencies | | version | Version | yes | The capsule's own version, strict major.minor.patch | | owner | Owner | yes | Who maintains the capsule and how to reach them | | license | string | yes | License identifier, preferably SPDX (e.g. "MIT") | | environmentNeeds | t.TSchema | no | TypeBox schema of the environment variables the capsule requires at runtime | | plugin | Plugin | no | Hook that wires routes, decorators, and state into the host app | | dependencies | Record<string, Version> | no | Other capsules required, keyed by their name | | tag | Tag | no | OpenAPI tag metadata grouping the capsule's routes in generated API docs |

Types

Owner

Authorship and contact metadata, mirroring the shape of a package.json author object.

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | yes | Maintainer display name — a person or an organization | | email | string | yes | Contact e-mail for support and security reports | | repository | string | no | URL of the capsule's source repository | | website | string | no | Maintainer homepage or profile page |

Version

Template-literal semver: only strict major.minor.patch strings compile. Pre-release suffixes and range operators are intentionally not representable.

import type { Version } from "@roastery/blend/types";

const ok: Version = "1.4.2";
// const missing: Version = "1.4";  // rejected: no patch segment
// const range: Version = "^1.4.2"; // rejected: ranges are not versions

Plugin

Barista plugin function: receives the fully typed host app (ContentType and BasePath are inferred from it), adds the capsule's routes and state, and returns the extended app. The return type is deliberately wide (object) because Elysia's structural types are invariant — route/type accumulation happens through Elysia's own .use() inference at the orchestrator, not through this alias — while still rejecting implementations that forget to return the app.

import type { Plugin } from "@roastery/blend/types";

const plugin: Plugin = (app) => app.get("/posts", () => []);

Tag

OpenAPI-style tag metadata a capsule attaches to itself so its routes are grouped under a named, described section in the host's generated API documentation — mirrors the OpenAPI Tag Object shape so it can be forwarded as-is.

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | yes | Name of the tag grouping the capsule's routes in the generated API docs | | description | string | yes | Short description of what the tagged routes are for | | externalDocs | { description?: string; url: string } | no | Link to further documentation beyond this description |

import type { Tag } from "@roastery/blend/types";

const tag: Tag = {
	name: "Posts",
	description: "Endpoints for creating and reading blog posts.",
	externalDocs: {
		description: "Full posts API guide",
		url: "https://docs.roastery.dev/posts",
	},
};

Exports reference

// Root entry point
import { Blend } from "@roastery/blend";
import type { Owner, Plugin, Tag, Version } from "@roastery/blend";

// Types-only subpath
import type { Owner, Plugin, Tag, Version } from "@roastery/blend/types";

Development

# Build for distribution
bun run build

# Check for unused exports and dependencies
bun run knip

# Full setup (build + bun link)
bun run setup

License

MIT