Setup

Requirements

• Node.js 24+ / npm 10+
• A modern browser (for local preview)

Scaffold a project

niyase-plugin new generates a plugin project.

npx @niyase/plugin-sdk new @your-org/tasks
cd tasks
npm install

Generated files:

tasks/
├── package.json        # niyase-plugin scripts + SDK devDeps
├── tsconfig.json
└── src/
    ├── manifest.ts     # defineManifest({...})
    ├── Root.tsx        # the main component that uses useNiyase()
    └── index.tsx       # createNiyase(); register("@your-org/tasks", Root)

CLI commands

Command	Role
niyase-plugin new	Scaffold a plugin
niyase-plugin build	Generate the distributable IIFE bundle (dist/bundle.js)
niyase-plugin lint	tsc + validateManifest() (zod) + forbidden-API scan
niyase-plugin test	Run vitest (verify against the MOCK with createTestHost())
niyase-plugin dev	Local preview (see below)
niyase-plugin publish	Build + validate + submit (see Submission)

Local preview

npm run dev          # = niyase-plugin dev
# ▸ http://localhost:4321

niyase-plugin dev runs your plugin inside a true-to-life generic shell (AppBar / sidebar / tabs), executing it with <iframe sandbox> + postMessage and connecting it to a MOCK backend. Use the DevBar at the top to switch theme, role, industry, language, and fault injection while you check it.

Because preview and production both run on the same useNiyase() contract, what you see here becomes the production look as-is.

Minimal plugin

// src/Root.tsx
import { useEffect, useState } from "react";
import { useNiyase } from "@niyase/plugin-sdk";

export function Root() {
  const niyase = useNiyase();
  const [items, setItems] = useState<{ id: string; title: string }[]>([]);

  useEffect(() => {
    niyase.data
      .list<{ id: string; title: string }>("task")
      .then((r) => setItems(r.items));
  }, []);

  return (
    <ul>
      {items.map((it) => (
        <li key={it.id}>{it.title}</li>
      ))}
    </ul>
  );
}

Next, check the contents of manifest.ts in Manifest.