Ecosystem & Packaging Conventions

Guidelines for building, naming, versioning, and distributing Notty plugins, themes, and starters.

For the platform distribution model (package architecture, publish contract, version sync), see Distribution Model.

Starter Templates

Notty ships with built-in starter templates to jumpstart common project types:

npx @notty/create my-project --template blog
npx @notty/create my-project --template ecommerce
npx @notty/create my-project --template portfolio
npx @notty/create my-project --template minimal

Template	Schemas	Components
default	article	—
blog	article, category, tag, author	shared/seo-meta
ecommerce	product, product-category, order	shared/seo-meta
portfolio	project, skill, testimonial, about page	shared/seo-meta
minimal	— (empty)	—

Each template generates the full project structure plus pre-configured schemas for the chosen vertical.

create-notty resolves published package versions automatically when it can. If you need to target a specific runtime release line, pass --notty-version <version> to pin @notty/server, @notty/core, and engines.notty.

Plugin Conventions

Naming

• npm package name: notty-plugin-<name> (e.g., notty-plugin-seo, notty-plugin-analytics)
• Scoped packages: @myorg/notty-plugin-<name> (e.g., @acme/notty-plugin-crm)
• The name field in the plugin manifest should match the package name

Package Structure

notty-plugin-my-plugin/
  src/
    index.ts          # Main entry — exports definePlugin(...)
  package.json        # Must include "notty" manifest field
  tsconfig.json
  README.md

package.json Requirements

{
  "name": "notty-plugin-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"],
  "dependencies": {
    "@notty/plugin-api": "^<plugin-api-version>"
  },
  "notty": {
    "name": "notty-plugin-my-plugin",
    "displayName": "My Plugin",
    "version": "1.0.0",
    "kind": "plugin",
    "description": "What this plugin does",
    "engines": { "notty": ">=<runtime-version>" }
  }
}

Versioning

• Follow semver
• Specify engines.notty to declare minimum compatible Notty version
• Bump the engines.notty constraint only when you use features from a newer Notty release
• @notty/plugin-api and @notty/theme-api can move on a different version line than the runtime packages; pin SDK deps to the matching published SDK release and keep engines.notty aligned with the runtime line you support

Testing

Use @notty/plugin-api/testing for plugin unit tests:

import { createTestPluginContext } from '@notty/plugin-api/testing';
import myPlugin from './index';

const ctx = createTestPluginContext();
myPlugin.register(ctx);

// Assert routes, hooks, widgets were registered

Registration

Users register plugins in notty.config.ts:

import myPlugin from 'notty-plugin-my-plugin';

export default defineConfig({
  plugins: [
    { source: myPlugin },
    // or with config:
    { source: myPlugin, config: { apiKey: '...' } },
  ],
});

Theme Conventions

Naming

• npm package name: notty-theme-<name> (e.g., notty-theme-dark, notty-theme-corporate)
• Scoped packages: @myorg/notty-theme-<name>

Package Structure

notty-theme-my-theme/
  src/
    index.ts          # Main entry — exports defineTheme(...)
  package.json        # Include "notty" metadata + discovery keywords
  tsconfig.json
  README.md

package.json Requirements

{
  "name": "notty-theme-my-theme",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./package.json": "./package.json"
  },
  "files": ["dist"],
  "keywords": ["notty-theme"],
  "dependencies": {
    "@notty/theme-api": "^<theme-api-version>"
  },
  "notty": {
    "name": "notty-theme-my-theme",
    "displayName": "My Theme",
    "version": "1.0.0",
    "kind": "theme",
    "description": "What this theme changes",
    "engines": { "notty": ">=<runtime-version>" }
  }
}

Design Tokens

Themes define tokens in the manifest:

tokens: {
  colors: {
    brand: {
      primary: { value: '#6366f1', description: 'Primary brand color' },
      secondary: { value: '#818cf8' },
    },
    semantic: {
      success: { value: '#22c55e' },
      warning: { value: '#f59e0b' },
      error: { value: '#ef4444' },
      info: { value: '#3b82f6' },
    },
    surface: {
      background: { value: '#ffffff' },
      foreground: { value: '#1e293b' },
    },
  },
  typography: {
    heading: { fontFamily: '"Inter", sans-serif', fontWeight: 700 },
    body: { fontFamily: '"Inter", sans-serif', fontSize: '14px', lineHeight: 1.6 },
  },
  radii: {
    sm: { value: '4px' },
    md: { value: '8px' },
    lg: { value: '12px' },
  },
}

Branding

Themes can customize admin branding:

branding: {
  title: 'My Company CMS',
  logo: '/path/to/logo.svg',
  favicon: '/path/to/favicon.ico',
  footerText: '© 2024 My Company',
  hidePoweredBy: true,
},
layout: {
  sidebarPosition: 'left',
  sidebarCollapsed: false,
  headerVisible: true,
}

Publishing Checklist

Before publishing a plugin or theme to npm:

1. Build — pnpm build (output in dist/)
2. Type-check — pnpm type-check
3. Test — run your test suite
4. Validate — pnpm dlx @notty/cli validate-plugin . (for plugins)
5. README — document installation, configuration, and usage
6. License — include a LICENSE file
7. Changelog — keep a CHANGELOG.md

npm publish

npm publish --access public

Scaffolding New Plugins & Themes

The CLI scaffolds production-ready starters:

# Create a plugin
npx @notty/create my-plugin --plugin

# Create a theme
npx @notty/create my-theme --theme

Both commands generate the full package structure with package.json, tsconfig.json, entry file, README.md, and .gitignore.

Directory Conventions

Schema Files

• Collection types: schemas/<singular-name>.json
• Single types: schemas/<singular-name>.json (with kind: "singleType")
• Components: components/<category>/<name>.json

Extension Points

Notty plugins can register:

Extension	API	Scope
REST routes	ctx.routes.get/post/...	/api/x/<plugin>/
Content hooks	ctx.hooks.on('content:*')	All content types
Dashboard widgets	ctx.admin.addDashboardWidget	Admin dashboard
Navigation items	ctx.admin.addNavigationItem	Admin sidebar
Settings sections	ctx.admin.addSettingsSection	Admin settings page
Authorization policies	ctx.policies.register	Route authorization
Middleware	ctx.middleware.add	Request pipeline
Services	ctx.services.register	Shared business logic

Future: Marketplace

Notty is building toward an ecosystem marketplace where developers can discover and share plugins and themes. Key principles:

• Open distribution — publish to npm, discoverable via the Notty registry
• Quality signals — compatibility badges, download counts, community ratings
• One-click install — notty install <plugin> adds the dependency and registers it in config
• Verified publishers — optional verification for trusted publishers

To prepare for marketplace readiness:

1. Follow the naming conventions above
2. Include comprehensive README with screenshots
3. Specify engines.notty accurately
4. Include the notty metadata field in package.json
5. Add keywords: ["notty-plugin"] or keywords: ["notty-theme"] for discoverability