This guide explains how to build a Cogita plugin that can be enabled by a site or a theme without coupling the plugin to one visual layout. Plugins provide capabilities; themes decide how those capabilities are presented.
Read the Plugin API specification first. It defines factory return values, registration order, layout requirements, capability identifiers, virtual modules, diagnostics, and lifecycle boundaries.
A minimal plugin has its own package, a factory, and a small configuration namespace:
The factory receives the enhanced CogitaPluginConfig and returns a plugin instance:
Keep the plugin configuration under its own namespace. Return null when the capability is disabled or cannot run in the current site. This keeps the zero-configuration path quiet and lets Core assemble only the capabilities a site actually uses.
Build-time state is available through CogitaBuildContext:
The context contains the site root, current working directory, shared contentIndex, theme layout paths, strict mode, the unified logger, and framework metadata. Legacy top-level fields remain for compatibility, but new build services belong in this context.
If a plugin generates a page, declare the layout it requires:
The layout name must match a key in the selected theme's pageLayouts. Use stable domain.capability identifiers for data contracts. Built-in identifiers should be imported from COGITA_CAPABILITIES in @cogita/shared.
Themes can mark capabilities as required or optional:
Core validates these declarations before the build. Missing required capabilities and missing layouts fail early in strict mode. Optional capabilities should have a visible, safe fallback in the theme.
Use the shared content index when multiple plugins need the same source data. Use a virtual module when a theme layout needs serialized build output:
Every module identifier must be unique in one build. Use createCogitaVirtualModule and public identifiers from @cogita/shared when the module is part of a shared contract. Do not expose absolute paths, tokens, private configuration, or full article bodies unless that is explicitly part of the public data model.
Use one hook for one job:
Rspress may run build hooks concurrently. Do not coordinate plugins by relying on the order of the plugin array. A plugin should be safe to run more than once during development rebuilds and should avoid mutating another plugin's state.
A site can add a plugin without modifying its theme:
Core registers core capabilities, theme bridge plugins, theme plugins, and then site plugins. Plugin names must be unique. Strict mode is recommended for development and CI because duplicate names, conflicting routes, and conflicting runtime modules become actionable build errors.
Tests should cover the plugin as a package and as part of a minimal site:
At minimum, test:
When a published package changes, add a Changeset. Keep the package README, design document, and consumer example synchronized.
Avoid importing internal files from Core, themes, or another plugin. Depend on public types and helpers from @cogita/shared, and declare workspace dependencies with workspace:* during monorepo development.
Do not put site-specific content or business rules inside a reusable plugin. If a feature changes the composition of a reading experience, extend the theme; if it supplies reusable data or behavior, keep it in the plugin.