Jay Plugin Development — Agent Kit

Plugin Developer Agent Kit — documentation written for AI agents, readable by humans.

This folder contains guides for creating jay-stack plugins: contracts, headless components, server actions, services, and plugin-provided routes.

What is a Jay Plugin?

A plugin provides headless components (data + interactions, no UI) that project designers use via contracts. Plugins can also provide complete pages (backoffice tools, admin dashboards) via routes. Prefer shipping your components as design-system elements — a component that also ships one or more .jay-html templates designers flatten into their pages and upgrade via jay-stack sync (see design-system-guide.md). Shipping a template gives consumers consistent, upgradable UI out of the box instead of hand-authoring every region; ship a bare contract (no template) only when the component truly has no default markup. Plugins can be standalone npm packages or inline within a project (see examples/jay-stack/fake-shop).

Workflow

1. Define contracts first — the contract is the source of truth
2. Implement components matching the contracts
3. Define actions with .jay-action metadata
4. Optionally add routes — pages for admin tools and dashboards
5. Optionally add validators — custom jay-html validation rules
6. Optionally add setup/agentkit handlers — config templating, add-menu generation, AIditor Project settings tabs
7. Set up plugin.yaml — list contracts, actions, services, contexts, routes, validators, setup, agentkit
8. Configure build — dual entry points (server + client), vite.config.ts, package.json exports
9. Validate with jay-stack validate-plugin

Plugin Lifecycle — CLI Commands

The plugin participates in four CLI commands, each running different hooks:

Command	When	What runs from your plugin
jay-stack validate-plugin	Plugin development	Checks plugin.yaml structure, contracts, exports, handler references
jay-stack setup <plugin>	Project setup	setup — creates config files, validates credentials
jay-stack agent-kit	Before development	agentkit — generates add-menu items, settings tabs, reference data, skills
jay-stack validate	During development	validators[].handler — runs your validation rules against project jay-html files

validate-plugin validates YOUR plugin's structure. Run it during plugin development.
validate runs your plugin's validators against a PROJECT that uses your plugin. Run it from the project.

Guides

File	Topic
Contract Authoring Guide	Writing contracts: syntax, page/component/linked contracts, examples
contracts-guide.md	Plugin-specific contract concerns
plugin-structure.md	plugin.yaml, package layout, exports
component-structure.md	makeJayStackComponent, builder API, three-phase rendering
design-system-guide.md	Shipping a template designers flatten; upgrades via jay-stack sync
component-state.md	createSignal, createMemo, createEffect, createDerivedArray, createEvent
component-refs.md	Refs, collection refs, element types
component-data.md	Immutable data, JSON Patch, createPatchableSignal
component-context.md	Context hooks: provide, reactive, global
render-results.md	phaseOutput, RenderPipeline, errors, redirects
actions-guide.md	makeJayAction, makeJayQuery, .jay-action files
webhooks-guide.md	makeWebhook, data change invalidation, renderer server
services-guide.md	createJayService, makeJayInit
plugin-routes.md	Plugin-provided pages: routes, jay-html templates, page components
seo-guide.md	SEO head tags: title, meta, OG, canonical via phaseOutput
commands-guide.md	makeCliCommand, .jay-command files, CONSOLE_CONTEXT, jay-stack run
validation.md	jay-stack validate-plugin, writing custom jay-html validators
setup-guide.md	Setup handlers, agent-kit handlers, references generation
add-menu-guide.md	AIditor add-menu items: schema, interaction, browse, presentation
aiditor-settings-guide.md	AIditor Project settings tabs: template, materialization, devOnly route
dev-server-service.md	Dev server service API: routes, params, freeze management
../references/<plugin>/	Plugin reference data

Key Principles

• Contract is the source of truth — define it before implementing the component
• Ship a design system — give each component one or more .jay-html templates so consumers flatten and upgrade via jay-stack sync, rather than hand-authoring UI
• Data is immutable — never mutate ViewState directly, use JSON Patch
• Phase-aware — choose the right rendering phase for each piece of data
• Props for configuration, params for URLs — props are passed by parent components, params come from route segments

---

About this document

This page is part of the Jay Stack Agent Kit — documentation generated from the framework source and written primarily for AI agents. The language and structure are optimized for machine consumption — expect precise, specification-style prose rather than narrative documentation. Learn more about the Agent Kit →