Getting Started

What a niyase plugin is, the four classification axes, and the concept behind the useNiyase() bridge.

A niyase plugin is a feature extension that can be turned on or off per space. Activating one adds a single menu entry to the sidebar (cloud / desktop) or shelf (mobile), and, when needed, dedicated tables in the space database and a dashboard card. A single plugin bundle runs the same way across all three surfaces: niyase cloud (Web) and the niyase app (Desktop / Mobile).

Four axes of classification

niyase plugins are classified along four independent axes. A common mistake is lining up "official / certified / custom" as if they were one choice — but ① (who builds it) and ② (how it's offered) are different axes. Don't conflate them.

#	Axis	Values	Meaning	manifest
①	Developer	Official / Certified	Built by niyase (`OFFICIAL`) / built by an external developer and reviewed by niyase (`CERTIFIED`)	`scope`
②	Provision & cost	Standard / Custom	Free and published to every space (standard) / built for an engineering fee and offered only to specified spaces (custom)	`visibility` + `plugin_allowed_workspace`
③	Deployment	Hybrid / Cloud-only	Installable on both local and cloud spaces (hybrid, the default) / installable on cloud spaces only (cloud-only)	`requiresCloud`
④	Operation pattern	Standalone / PROVIDER-CLIENT	Self-contained within one space (standalone) / a provider and a client plugin work as a pair and share data (PROVIDER-CLIENT)	`defaultRole` + `pairedPluginId`

① and ② are independent. A custom plugin (paid, limited to specific spaces) can be either official (niyase builds it on commission) or certified (an external company builds it on commission).
④ PROVIDER-CLIENT always forces ③ to cloud-only, because a local space can never have a counterpart to collaborate with. A standalone plugin can also be set to cloud-only if it depends on sync or collaboration features.

See Manifest for how each axis is declared.

Core principle — the `useNiyase()` bridge

Plugins never receive any of the app's source code; you develop with the SDK alone. The only API surface a plugin touches is the useNiyase() bridge.

import { useNiyase } from "@niyase/plugin-sdk";

function Root() {
  const niyase = useNiyase();
  niyase.data; // CRUD on your own plugin's plg_* tables
  niyase.core; // Read core data (employees, departments, spaces — minimal fields)
  niyase.connections; // PROVIDER-CLIENT only. Cross-space connections and shared data CRUD
  niyase.context; // { spaceId, workspaceType, role, audience, locale, theme, plugin } reactive
  niyase.i18n; // Resolves your plugin's own ja/en messages against context.locale
  niyase.navigate; // Navigation within your own plugin
  niyase.toast; // Notifications
  niyase.palette; // Unified palette integration
}

One interface, two implementations: in local preview (niyase-plugin dev), useNiyase() is injected with the MOCK implementation; on production niyase it is injected with the REAL implementation. The plugin code stays the same either way, so what you see locally becomes the production look as-is.

The full bridge surface (the detailed API of each namespace) is covered in UI Integration and Core API Integration.

SDK packages

@niyase/plugin-sdk — published on npm (MIT). Includes the useNiyase() bridge contract, register(), and the niyase-plugin CLI
@niyase/plugin-sdk/manifest — the PluginManifest type + defineManifest() + validateManifest() (zod)
@niyase/plugin-sdk/ui — niyase's UI components (externalized at build time; the host's real implementation is used at runtime)
@niyase/plugin-preview — the local preview shell behind niyase-plugin dev. Publishing to npm is coming soon (until then, official plugin development uses it directly inside the monorepo)

Getting Started

Four axes of classification

Core principle — the useNiyase() bridge

SDK packages

What to read next

Core principle — the `useNiyase()` bridge