Publishing Plugins

Learn how to package, document, and publish your Genkit plugins to npm so others can use them.

Prerequisites

Node.js and npm installed
npm account (sign up here)
TypeScript knowledge
Completed plugin implementation

Package Structure

Recommended Directory Structure

my-genkit-plugin/
├── src/
│   ├── index.ts         # Main plugin export
│   ├── models.ts        # Model implementations
│   └── types.ts         # Type definitions
├── tests/
│   └── index.test.ts    # Tests
├── package.json
├── tsconfig.json
├── README.md
├── LICENSE
└── .npmignore

Package Configuration

package.json

{
  "name": "genkitx-myplugin",
  "version": "1.0.0",
  "description": "Genkit plugin for MyProvider AI models",
  "keywords": [
    "genkit",
    "genkit-plugin",
    "genkit-model",
    "ai",
    "myprovider"
  ],
  "author": "Your Name <your.email@example.com>",
  "license": "Apache-2.0",
  "repository": {
    "type": "git",
    "url": "https://github.com/yourusername/genkitx-myplugin.git"
  },
  "main": "./lib/index.js",
  "types": "./lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts",
      "require": "./lib/index.js",
      "import": "./lib/index.mjs",
      "default": "./lib/index.js"
    }
  },
  "files": [
    "lib",
    "README.md",
    "LICENSE"
  ],
  "scripts": {
    "build": "tsc && tsup-node",
    "test": "vitest",
    "prepublishOnly": "npm run build"
  },
  "peerDependencies": {
    "genkit": "^1.0.0"
  },
  "devDependencies": {
    "genkit": "^1.0.0",
    "typescript": "^5.0.0",
    "tsup": "^8.0.0",
    "vitest": "^1.0.0"
  }
}

Important fields:

name - Use genkitx-* prefix for community plugins
keywords - Include genkit-plugin for discoverability
peerDependencies - Require genkit as peer dependency
files - Only include necessary files (lib, README, LICENSE)
exports - Support both CommonJS and ESM

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "declaration": true,
    "outDir": "./lib",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "lib", "tests"]
}

.npmignore

src/
tests/
tsconfig.json
tsup.config.ts
*.test.ts
.git/
.github/
node_modules/

Naming Conventions

Package Names

Official plugins (by Firebase/Google):

@genkit-ai/plugin-name - e.g., @genkit-ai/anthropic

Community plugins:

genkitx-plugin-name - e.g., genkitx-ollama, genkitx-pinecone

Avoid:

Names starting with genkit- (reserved for official packages)
Generic names like genkit-ai-plugin

Keywords

Include relevant keywords for npm search:

"keywords": [
  "genkit",
  "genkit-plugin",
  "genkit-model",        // For model providers
  "genkit-embedder",     // For embedders
  "genkit-retriever",    // For vector stores
  "ai",
  "llm",
  "your-provider-name"
]

Documentation

README.md Template

# genkitx-myplugin

Genkit plugin for [MyProvider](https://myprovider.com) AI models.

## Installation

\`\`\`bash
npm install genkitx-myplugin
\`\`\`

## Usage

\`\`\`typescript
import { genkit } from 'genkit';
import { myProvider } from 'genkitx-myplugin';

const ai = genkit({
  plugins: [
    myProvider({ apiKey: process.env.MY_API_KEY }),
  ],
});

const response = await ai.generate({
  model: myProvider.model('my-model'),
  prompt: 'Hello!',
});
\`\`\`

## Configuration

### Plugin Options

- `apiKey` (string, required) - Your MyProvider API key
- `baseUrl` (string, optional) - Custom API endpoint

### Model Config

- `temperature` (number, 0-2) - Sampling temperature
- `maxOutputTokens` (number) - Maximum response length

## Available Models

- `my-model-1` - General purpose model
- `my-model-2` - Specialized model

## Examples

[Include common use cases]

## License

Apache-2.0

## Links

- [MyProvider Documentation](https://myprovider.com/docs)
- [GitHub Repository](https://github.com/yourusername/genkitx-myplugin)
- [npm Package](https://www.npmjs.com/package/genkitx-myplugin)

API Documentation

Document all exported functions and types:

/**
 * MyProvider plugin for Genkit.
 * 
 * Provides access to MyProvider AI models.
 * 
 * @param options - Plugin configuration
 * @param options.apiKey - API key (or set MY_API_KEY env var)
 * @param options.baseUrl - Optional custom API endpoint
 * 
 * @example
 * ```typescript
 * import { myProvider } from 'genkitx-myplugin';
 * 
 * const ai = genkit({
 *   plugins: [
 *     myProvider({ apiKey: 'your-key' }),
 *   ],
 * });
 * ```
 */
export function myProvider(options?: MyProviderOptions): GenkitPluginV2 {
  // ...
}

Testing

Unit Tests

import { describe, it, expect } from 'vitest';
import { genkit } from 'genkit';
import { myProvider } from '../src';

describe('myProvider plugin', () => {
  it('should register models', async () => {
    const ai = genkit({
      plugins: [myProvider({ apiKey: 'test' })],
    });

    // Test basic generation
    const response = await ai.generate({
      model: myProvider.model('test-model'),
      prompt: 'Hello',
    });

    expect(response.text()).toBeTruthy();
  });

  it('should require API key', () => {
    expect(() => {
      myProvider({ apiKey: undefined });
    }).toThrow('API key required');
  });

  it('should handle errors', async () => {
    const ai = genkit({
      plugins: [myProvider({ apiKey: 'invalid' })],
    });

    await expect(
      ai.generate({
        model: myProvider.model('test'),
        prompt: 'test',
      })
    ).rejects.toThrow();
  });
});

Publishing to npm

First-time Setup

Create npm account:

npm adduser

Verify login:

npm whoami

Publishing Steps

Build the package:

npm run build

Test locally:

npm pack
# Creates genkitx-myplugin-1.0.0.tgz

# Test in another project
cd /path/to/test-project
npm install /path/to/genkitx-myplugin-1.0.0.tgz

Run tests:

npm test

Update version:

# Patch release (1.0.0 -> 1.0.1)
npm version patch

# Minor release (1.0.0 -> 1.1.0)
npm version minor

# Major release (1.0.0 -> 2.0.0)
npm version major

Publish:

npm publish --access public

Scoped Packages

For organization packages:

npm publish --access public

Best Practices

1. Semantic Versioning

Follow semver:

Major (1.0.0 -> 2.0.0) - Breaking changes
Minor (1.0.0 -> 1.1.0) - New features, backward compatible
Patch (1.0.0 -> 1.0.1) - Bug fixes

2. Changelog

Maintain a CHANGELOG.md:

# Changelog

## [1.1.0] - 2024-03-15

### Added
- Support for streaming responses
- New model: my-model-3

### Fixed
- Token counting issue

## [1.0.0] - 2024-03-01

### Added
- Initial release
- Support for my-model-1 and my-model-2

3. License

Use Apache-2.0 to match Genkit:

Copyright 2024 Your Name

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

4. Types

Always include TypeScript declarations:

{
  "types": "./lib/index.d.ts",
  "exports": {
    ".": {
      "types": "./lib/index.d.ts"
    }
  }
}

5. Peer Dependencies

Use peerDependencies for Genkit:

{
  "peerDependencies": {
    "genkit": "^1.0.0"
  },
  "devDependencies": {
    "genkit": "^1.0.0"
  }
}

6. Security

Don’t include API keys in code or tests
Add .env to .gitignore
Use environment variables for secrets
Document security best practices

7. Examples

Provide working examples:

examples/
├── basic-usage.ts
├── streaming.ts
└── rag-example.ts

Maintenance

Responding to Issues

Triage issues promptly
Label issues appropriately
Provide clear reproduction steps
Fix critical bugs quickly

Keeping Up-to-date

Monitor Genkit releases
Update peer dependency versions
Test against new Genkit versions
Update documentation

Deprecation

If deprecating features:

/**
 * @deprecated Use newFunction() instead. Will be removed in v2.0.0.
 */
export function oldFunction() {
  console.warn('oldFunction is deprecated. Use newFunction instead.');
  return newFunction();
}

Promotion

Genkit Discord - Announce in #plugins channel
GitHub - Add genkit-plugin topic to repository
Twitter/X - Share with #Genkit hashtag
Blog post - Write about your plugin
Documentation - Submit PR to genkit-ai/docsite

Badge for README

[![npm version](https://badge.fury.io/js/genkitx-myplugin.svg)](https://www.npmjs.com/package/genkitx-myplugin)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

Resources

Checklist

Before publishing:

Official Plugins

Plugin Development

Publishing Plugins

Publishing Plugins

Prerequisites

Package Structure

Recommended Directory Structure

Package Configuration

package.json

tsconfig.json

.npmignore

Naming Conventions

Package Names

Keywords

Documentation

README.md Template

API Documentation

Testing

Unit Tests

Publishing to npm

First-time Setup

Publishing Steps

Scoped Packages

Best Practices

1. Semantic Versioning

2. Changelog

3. License

4. Types

5. Peer Dependencies

6. Security

7. Examples

Maintenance

Responding to Issues

Keeping Up-to-date

Deprecation

Promotion

Badge for README

Resources

Checklist

​Publishing Plugins

​Prerequisites

​Package Structure

​Recommended Directory Structure

​Package Configuration

​package.json

​tsconfig.json

​.npmignore

​Naming Conventions

​Package Names

​Keywords

​Documentation

​README.md Template

​API Documentation

​Testing

​Unit Tests

​Publishing to npm

​First-time Setup

​Publishing Steps

​Scoped Packages

​Best Practices

​1. Semantic Versioning

​2. Changelog

​3. License

​4. Types

​5. Peer Dependencies

​6. Security

​7. Examples

​Maintenance

​Responding to Issues

​Keeping Up-to-date

​Deprecation

​Promotion

​Share Your Plugin

​Badge for README

​Resources

​Checklist

Publishing Plugins

Prerequisites

Package Structure

Recommended Directory Structure

Package Configuration

package.json

tsconfig.json

.npmignore

Naming Conventions

Package Names

Keywords

Documentation

README.md Template

API Documentation

Testing

Unit Tests

Publishing to npm

First-time Setup

Publishing Steps

Scoped Packages

Best Practices

1. Semantic Versioning

2. Changelog

3. License

4. Types

5. Peer Dependencies

6. Security

7. Examples

Maintenance

Responding to Issues

Keeping Up-to-date

Deprecation

Promotion

Share Your Plugin

Badge for README

Resources

Checklist