Your First Plugin - NaaP Docs

What We'll Build#

In this guide, we'll build a Task Tracker plugin with:

A React frontend showing a task list
An Express backend with CRUD API
A PostgreSQL database for persistence
Full integration with shell services (auth, notifications, events)

Step 1: Scaffold the Plugin#

Terminal

$naap-plugin create task-tracker --template full-stack --category developer-tools

This creates a complete plugin skeleton. Navigate into the directory:

Terminal

$cd task-tracker

$npm install

Step 2: Define the Plugin Manifest#

Edit plugin.json:

JSON

1	{
2	"name": "task-tracker",
3	"displayName": "Task Tracker",
4	"version": "1.0.0",
5	"description": "Track and manage development tasks",
6	"category": "developer-tools",
7
8	"frontend": {
9	"entry": "./frontend/dist/production/task-tracker.js",
10	"devPort": 3020,
11	"routes": ["/task-tracker", "/task-tracker/*"],
12	"navigation": {
13	"label": "Tasks",
14	"icon": "CheckSquare",
15	"section": "main",
16	"order": 45
17	}
18	},
19
20	"backend": {
21	"entry": "./backend/dist/server.js",
22	"port": 4020,
23	"apiPrefix": "/api/v1/task-tracker",
24	"healthCheck": "/healthz"
25	},
26
27	"database": {
28	"type": "postgresql",
29	"schema": "plugin_task_tracker"
30	}
31	}

Step 3: Set Up the Database#

NaaP uses a single database with multi-schema isolation. Models are defined centrally in packages/database/prisma/schema.prisma — never in the plugin directory. See Database Architecture.

Add your models to packages/database/prisma/schema.prisma:

Prisma

1	// Append to packages/database/prisma/schema.prisma
2	model TrackerTask {
3	id String @id @default(uuid())
4	title String
5	description String?
6	status String @default("todo")
7	priority String @default("medium")
8	assigneeId String?
9	createdBy String
10	createdAt DateTime @default(now())
11	updatedAt DateTime @updatedAt
12
13	@@schema("plugin_task_tracker")
14	}

Also register the schema:

Add "plugin_task_tracker" to the schemas array in packages/database/prisma/schema.prisma
Add CREATE SCHEMA IF NOT EXISTS plugin_task_tracker; to docker/init-schemas.sql

Generate and push:

Terminal

$cd packages/database

$npx prisma generate

$npx prisma db push

Create the database client file:

TypeScript

// backend/src/db/client.ts
import { prisma } from '@naap/database';
export const db = prisma;

Step 4: Build the Backend API#

Edit backend/src/server.ts:

TypeScript

1	import express from 'express';
2	import { db } from './db/client.js';
3
4	const app = express();
5	const PORT = process.env.PORT \|\| 4020;
6
7	app.use(express.json());
8
9	// Health check
10	app.get('/healthz', (_req, res) => {
11	res.json({ status: 'healthy', service: 'task-tracker' });
12	});
13
14	// List tasks — note the prefixed model name: db.trackerTask
15	app.get('/api/v1/task-tracker/tasks', async (req, res) => {
16	const tasks = await db.trackerTask.findMany({
17	orderBy: { createdAt: 'desc' },
18	});
19	// API envelope: { success: true, data: { tasks } }
20	res.json({ success: true, data: { tasks } });
21	});
22
23	// Create task
24	app.post('/api/v1/task-tracker/tasks', async (req, res) => {
25	const { title, description, priority } = req.body;
26	const userId = req.headers['x-user-id'] as string;
27
28	const task = await db.trackerTask.create({
29	data: { title, description, priority, createdBy: userId },
30	});
31	res.status(201).json({ success: true, data: { task } });
32	});
33
34	// Update task
35	app.patch('/api/v1/task-tracker/tasks/:id', async (req, res) => {
36	const { id } = req.params;
37	const task = await db.trackerTask.update({
38	where: { id },
39	data: req.body,
40	});
41	res.json({ success: true, data: { task } });
42	});
43
44	// Delete task
45	app.delete('/api/v1/task-tracker/tasks/:id', async (req, res) => {
46	await db.trackerTask.delete({ where: { id: req.params.id } });
47	res.json({ success: true, data: null });
48	});
49
50	app.listen(PORT, () => {
51	console.log(`Task Tracker backend running on port ${PORT}`);
52	});

Step 5: Build the Frontend#

Edit frontend/src/App.tsx:

TypeScript

1	import { useState, useEffect } from 'react';
2	import { useAuth, useNotify, usePluginApi } from '@naap/plugin-sdk';
3
4	interface Task {
5	id: string;
6	title: string;
7	status: string;
8	priority: string;
9	createdAt: string;
10	}
11
12	export default function App() {
13	const auth = useAuth();
14	const notify = useNotify();
15	const api = usePluginApi();
16	const [tasks, setTasks] = useState<Task[]>([]);
17	const [title, setTitle] = useState('');
18
19	useEffect(() => {
20	loadTasks();
21	}, []);
22
23	async function loadTasks() {
24	const res = await api.get('/tasks');
25	// usePluginApi auto-unwraps the { success, data } envelope
26	setTasks(res.tasks ?? []);
27	}
28
29	async function addTask() {
30	if (!title.trim()) return;
31	await api.post('/tasks', { title });
32	setTitle('');
33	notify.success('Task created!');
34	loadTasks();
35	}
36
37	async function toggleTask(task: Task) {
38	const newStatus = task.status === 'done' ? 'todo' : 'done';
39	await api.patch(`/tasks/${task.id}`, { status: newStatus });
40	loadTasks();
41	}
42
43	return (
44	<div className="p-6 max-w-2xl mx-auto">
45	<h1 className="text-2xl font-bold mb-6">Task Tracker</h1>
46
47	{/* Add task form */}
48	<div className="flex gap-2 mb-6">
49	<input
50	value={title}
51	onChange={(e) => setTitle(e.target.value)}
52	onKeyDown={(e) => e.key === 'Enter' && addTask()}
53	placeholder="Add a new task..."
54	className="flex-1 px-3 py-2 rounded-lg border"
55	/>
56	<button
57	onClick={addTask}
58	className="px-4 py-2 bg-primary text-white rounded-lg"
59	>
60	Add
61	</button>
62	</div>
63
64	{/* Task list */}
65	<div className="space-y-2">
66	{tasks.map((task) => (
67	<div
68	key={task.id}
69	className="flex items-center gap-3 p-3 rounded-lg border"
70	>
71	<button onClick={() => toggleTask(task)}>
72	{task.status === 'done' ? '✅' : '⬜'}
73	</button>
74	<span className={task.status === 'done' ? 'line-through opacity-50' : ''}>
75	{task.title}
76	</span>
77	</div>
78	))}
79	</div>
80	</div>
81	);
82	}

Step 6: Set Up the Mount Function#

Edit frontend/src/mount.tsx:

TypeScript

1	import React from 'react';
2	import { createRoot } from 'react-dom/client';
3	import { ShellProvider } from '@naap/plugin-sdk';
4	import type { ShellContext } from '@naap/plugin-sdk';
5	import App from './App';
6
7	let root: ReturnType<typeof createRoot> \| null = null;
8
9	export function mount(container: HTMLElement, context: ShellContext) {
10	root = createRoot(container);
11	root.render(
12	<ShellProvider value={context}>
13	<App />
14	</ShellProvider>
15	);
16
17	return () => {
18	if (root) {
19	root.unmount();
20	root = null;
21	}
22	};
23	}

Step 7: Configure the Build#

Edit frontend/vite.config.ts:

TypeScript

1	import { createPluginConfig } from '@naap/plugin-build/vite';
2
3	export default createPluginConfig({
4	name: 'task-tracker',
5	displayName: 'Task Tracker',
6	globalName: 'NaapPluginTaskTracker',
7	defaultCategory: 'developer-tools',
8	});

Step 8: Run and Test#

Terminal

# Start the dev server

$naap-plugin dev

# Open the shell

$open http://localhost:3000

Your Task Tracker plugin should appear in the sidebar. You can add tasks, mark them as done, and see notifications.

Next Steps#

Add testing to your plugin
Publish to the marketplace
Explore the full SDK API

What We'll Build#

In this guide, we'll build a Task Tracker plugin with:

A React frontend showing a task list
An Express backend with CRUD API
A PostgreSQL database for persistence
Full integration with shell services (auth, notifications, events)

Step 1: Scaffold the Plugin#

Terminal

$naap-plugin create task-tracker --template full-stack --category developer-tools

This creates a complete plugin skeleton. Navigate into the directory:

Terminal

$cd task-tracker

$npm install

Step 2: Define the Plugin Manifest#

Edit plugin.json:

JSON

1	{
2	"name": "task-tracker",
3	"displayName": "Task Tracker",
4	"version": "1.0.0",
5	"description": "Track and manage development tasks",
6	"category": "developer-tools",
7
8	"frontend": {
9	"entry": "./frontend/dist/production/task-tracker.js",
10	"devPort": 3020,
11	"routes": ["/task-tracker", "/task-tracker/*"],
12	"navigation": {
13	"label": "Tasks",
14	"icon": "CheckSquare",
15	"section": "main",
16	"order": 45
17	}
18	},
19
20	"backend": {
21	"entry": "./backend/dist/server.js",
22	"port": 4020,
23	"apiPrefix": "/api/v1/task-tracker",
24	"healthCheck": "/healthz"
25	},
26
27	"database": {
28	"type": "postgresql",
29	"schema": "plugin_task_tracker"
30	}
31	}

Step 3: Set Up the Database#

NaaP uses a single database with multi-schema isolation. Models are defined centrally in packages/database/prisma/schema.prisma — never in the plugin directory. See Database Architecture.

Add your models to packages/database/prisma/schema.prisma:

Prisma

1	// Append to packages/database/prisma/schema.prisma
2	model TrackerTask {
3	id String @id @default(uuid())
4	title String
5	description String?
6	status String @default("todo")
7	priority String @default("medium")
8	assigneeId String?
9	createdBy String
10	createdAt DateTime @default(now())
11	updatedAt DateTime @updatedAt
12
13	@@schema("plugin_task_tracker")
14	}

Also register the schema:

Add "plugin_task_tracker" to the schemas array in packages/database/prisma/schema.prisma
Add CREATE SCHEMA IF NOT EXISTS plugin_task_tracker; to docker/init-schemas.sql

Generate and push:

Terminal

$cd packages/database

$npx prisma generate

$npx prisma db push

Create the database client file:

TypeScript

// backend/src/db/client.ts
import { prisma } from '@naap/database';
export const db = prisma;

Step 4: Build the Backend API#

Edit backend/src/server.ts:

TypeScript

1	import express from 'express';
2	import { db } from './db/client.js';
3
4	const app = express();
5	const PORT = process.env.PORT \|\| 4020;
6
7	app.use(express.json());
8
9	// Health check
10	app.get('/healthz', (_req, res) => {
11	res.json({ status: 'healthy', service: 'task-tracker' });
12	});
13
14	// List tasks — note the prefixed model name: db.trackerTask
15	app.get('/api/v1/task-tracker/tasks', async (req, res) => {
16	const tasks = await db.trackerTask.findMany({
17	orderBy: { createdAt: 'desc' },
18	});
19	// API envelope: { success: true, data: { tasks } }
20	res.json({ success: true, data: { tasks } });
21	});
22
23	// Create task
24	app.post('/api/v1/task-tracker/tasks', async (req, res) => {
25	const { title, description, priority } = req.body;
26	const userId = req.headers['x-user-id'] as string;
27
28	const task = await db.trackerTask.create({
29	data: { title, description, priority, createdBy: userId },
30	});
31	res.status(201).json({ success: true, data: { task } });
32	});
33
34	// Update task
35	app.patch('/api/v1/task-tracker/tasks/:id', async (req, res) => {
36	const { id } = req.params;
37	const task = await db.trackerTask.update({
38	where: { id },
39	data: req.body,
40	});
41	res.json({ success: true, data: { task } });
42	});
43
44	// Delete task
45	app.delete('/api/v1/task-tracker/tasks/:id', async (req, res) => {
46	await db.trackerTask.delete({ where: { id: req.params.id } });
47	res.json({ success: true, data: null });
48	});
49
50	app.listen(PORT, () => {
51	console.log(`Task Tracker backend running on port ${PORT}`);
52	});

Step 5: Build the Frontend#

Edit frontend/src/App.tsx:

TypeScript

1	import { useState, useEffect } from 'react';
2	import { useAuth, useNotify, usePluginApi } from '@naap/plugin-sdk';
3
4	interface Task {
5	id: string;
6	title: string;
7	status: string;
8	priority: string;
9	createdAt: string;
10	}
11
12	export default function App() {
13	const auth = useAuth();
14	const notify = useNotify();
15	const api = usePluginApi();
16	const [tasks, setTasks] = useState<Task[]>([]);
17	const [title, setTitle] = useState('');
18
19	useEffect(() => {
20	loadTasks();
21	}, []);
22
23	async function loadTasks() {
24	const res = await api.get('/tasks');
25	// usePluginApi auto-unwraps the { success, data } envelope
26	setTasks(res.tasks ?? []);
27	}
28
29	async function addTask() {
30	if (!title.trim()) return;
31	await api.post('/tasks', { title });
32	setTitle('');
33	notify.success('Task created!');
34	loadTasks();
35	}
36
37	async function toggleTask(task: Task) {
38	const newStatus = task.status === 'done' ? 'todo' : 'done';
39	await api.patch(`/tasks/${task.id}`, { status: newStatus });
40	loadTasks();
41	}
42
43	return (
44	<div className="p-6 max-w-2xl mx-auto">
45	<h1 className="text-2xl font-bold mb-6">Task Tracker</h1>
46
47	{/* Add task form */}
48	<div className="flex gap-2 mb-6">
49	<input
50	value={title}
51	onChange={(e) => setTitle(e.target.value)}
52	onKeyDown={(e) => e.key === 'Enter' && addTask()}
53	placeholder="Add a new task..."
54	className="flex-1 px-3 py-2 rounded-lg border"
55	/>
56	<button
57	onClick={addTask}
58	className="px-4 py-2 bg-primary text-white rounded-lg"
59	>
60	Add
61	</button>
62	</div>
63
64	{/* Task list */}
65	<div className="space-y-2">
66	{tasks.map((task) => (
67	<div
68	key={task.id}
69	className="flex items-center gap-3 p-3 rounded-lg border"
70	>
71	<button onClick={() => toggleTask(task)}>
72	{task.status === 'done' ? '✅' : '⬜'}
73	</button>
74	<span className={task.status === 'done' ? 'line-through opacity-50' : ''}>
75	{task.title}
76	</span>
77	</div>
78	))}
79	</div>
80	</div>
81	);
82	}

Step 6: Set Up the Mount Function#

Edit frontend/src/mount.tsx:

TypeScript

1	import React from 'react';
2	import { createRoot } from 'react-dom/client';
3	import { ShellProvider } from '@naap/plugin-sdk';
4	import type { ShellContext } from '@naap/plugin-sdk';
5	import App from './App';
6
7	let root: ReturnType<typeof createRoot> \| null = null;
8
9	export function mount(container: HTMLElement, context: ShellContext) {
10	root = createRoot(container);
11	root.render(
12	<ShellProvider value={context}>
13	<App />
14	</ShellProvider>
15	);
16
17	return () => {
18	if (root) {
19	root.unmount();
20	root = null;
21	}
22	};
23	}

Step 7: Configure the Build#

Edit frontend/vite.config.ts:

TypeScript

1	import { createPluginConfig } from '@naap/plugin-build/vite';
2
3	export default createPluginConfig({
4	name: 'task-tracker',
5	displayName: 'Task Tracker',
6	globalName: 'NaapPluginTaskTracker',
7	defaultCategory: 'developer-tools',
8	});

Step 8: Run and Test#

Terminal

# Start the dev server

$naap-plugin dev

# Open the shell

$open http://localhost:3000

Your Task Tracker plugin should appear in the sidebar. You can add tasks, mark them as done, and see notifications.

Next Steps#

Add testing to your plugin
Publish to the marketplace
Explore the full SDK API