Skip to main content

Developer Guide

Introduction

★ Start here (Development) — Monorepo, architecture, APIs, MCP/Cursor, extension paths.
Editorial Documentation: Navbar Editorial, not this sidebar.

Welcome to the cockpitOS Developer Guide. Here: Plugins, Themes, APIs, MCP and platform extensions — technically, for code and integrations.

What You Can Develop​

WordPress Themes​

  • Theme Upload System: ZIP upload with dashboard integration
  • Center-specific Customizations: Colors, fonts, logo per center
  • CSS Variables System: Dynamic theme customizations
  • Elementor Integration: Custom widgets and dynamic tags
  • Auto-synchronization: WordPress plugin automatically loads theme data

Elementor Widgets​

  • cockpitOS Widgets: Shop grids, event lists, news feeds
  • Dynamic Tags: Content areas, shop data, event information
  • Theme Integration: Widgets use dashboard colors and fonts
  • API Integration: Live data from the cockpitOS dashboard

Blocks​

  • React Components: Modern React-based blocks
  • Schema-based: Automatic UI generation from JSON schema
  • Responsive: Mobile-first design
  • Reusable: Deployed across different themes

Development Kit​

In the monorepo, packages/sdk (@cockpitos/sdk) — CLI for scaffolding block and theme plugins. The global npm install -g method is optional for external plugin authors.

SDK (Monorepo)​

# After pnpm install in the monorepo:
pnpm --filter @cockpitos/sdk exec cockpitos create-block my-block
pnpm --filter @cockpitos/sdk exec cockpitos create-theme my-theme

The command cockpitos dev currently only starts a placeholder log — plugin development primarily takes place via npm run dev in the generated plugin folder. Storybook/Playground as described in older docs are not included in the package.

Quick Start (external)​

npm install -g @cockpitos/sdk
cockpitos create-block my-awesome-block
cd my-awesome-block && npm install && npm run dev

Documentation​

Community​

Prerequisites​

  • Node.js: >= 22.13 (as per Root package.json / Render)
  • TypeScript: >= 5.0.0
  • React: >= 19.0.0
  • Next.js: >= 15.0.0

Dashboard App in Monorepo (Build & Typecheck)​

  • Active Next Configuration: apps/dashboard/next.config.js (not next.config.ts; the .ts file is only for reference/IDE).
  • outputFileTracingRoot: points to the Workspace Root, so Next uses the correct pnpm-lock.yaml during build (fewer warnings with multiple lockfiles).
  • Large Uploads: experimental.serverActions.bodySizeLimit and experimental.middlewareClientMaxBodySize (no outdated proxyClientMaxBodySize in Next 15.5).
  • pnpm --filter dashboard type-check: The tsconfig.json of the dashboard does not include .next/types in include and excludes .next — otherwise, generated route validator types produce many false positives; no impact on runtime data. Typed routes for Link might be restricted; source code under src/ remains authoritative. (Next may write suggestions to the file on the first run — consciously do not commit/adopt .next/types if you want a clean tsc.)
  • Build: PageNotFoundError / ENOENT during "Collecting page data": occurs during incremental builds occasionally when the .next cache is inconsistent. No data loss: the dashboard automatically runs prebuild before pnpm build (rm -rf .next) to keep the production build stable. (Only build artifacts, no DB.) The API routes under src/app/api/.../route.ts are not altered in the process.

Next Steps​

  1. Understand Plugin System - Fundamentals of the plugin architecture
  2. Create Your First Plugin - Step-by-step tutorial
  3. Develop Theme - Build your own theme (Coming Soon)
  4. Publish Plugin - Publish your plugin in the marketplace (Coming Soon)

Ready to get started? Begin with our Getting Started Guide.

Nutzungsstatistik: Seitenaufrufe werden anonymisiert erfasst. Im Umami-Dashboard nach diesem Pfad filtern: /en/developer-guide/intro