Skip to content

PUBLISHING.md

Latest commit

 

History

History
424 lines (306 loc) · 8.55 KB

PUBLISHING.md

File metadata and controls

424 lines (306 loc) · 8.55 KB

Publishing Guide for n8n-nodes-openguardrails

This guide explains how to publish the OpenGuardrails node to npm and the n8n community.

Prerequisites

  1. npm Account

  2. npm CLI Authentication

    npm login
# Enter your npm username, password, and email

  3. GitHub Repository

    • Create repository: openguardrails/n8n-nodes-openguardrails
    • Push all code to GitHub

Pre-Publishing Checklist

1. Code Quality

# Run linting
npm run lint

# Auto-fix linting issues
npm run lintfix

# Format code
npm run format

2. Build and Test

# Install dependencies
npm install

# Build the package
npm run build

# Verify dist/ folder is created
ls -la dist/

3. Test Locally

# Link the package locally
npm link

# In your n8n installation directory
cd ~/.n8n
npm link n8n-nodes-openguardrails

# Restart n8n and test the node
n8n start

Test all operations:

  • ✅ Check Content
  • ✅ Input Moderation
  • ✅ Output Moderation
  • ✅ Conversation Check
  • ✅ Credentials authentication
  • ✅ Error handling

4. Update Version

Update package.json version following Semantic Versioning:

  • Patch (1.0.0 → 1.0.1): Bug fixes
  • Minor (1.0.0 → 1.1.0): New features (backward compatible)
  • Major (1.0.0 → 2.0.0): Breaking changes
# For example, release version 1.0.0
npm version 1.0.0

5. Update Documentation

Ensure these files are up to date:

  • ✅ README.md - Installation, usage, examples
  • ✅ CHANGELOG.md - Version history
  • ✅ LICENSE - Apache 2.0
  • ✅ package.json - Correct metadata

Publishing Steps

Step 1: Final Build

# Clean previous builds
rm -rf dist/

# Build fresh
npm run build

Step 2: Test Package Contents

# Check what will be published
npm pack --dry-run

# Review the list of files
# Make sure only necessary files are included

Step 3: Publish to npm

# Publish as public package
npm publish --access public

You should see output like:

+ n8n-nodes-openguardrails@1.0.0

Step 4: Verify Publication

  1. Visit https://www.npmjs.com/package/n8n-nodes-openguardrails
  2. Check that all information is correct
  3. Verify README is displayed properly

Step 5: Tag GitHub Release

# Create and push git tag
git tag v1.0.0
git push origin v1.0.0

On GitHub:

  1. Go to repository Releases
  2. Click Create a new release
  3. Select tag v1.0.0
  4. Title: v1.0.0 - Initial Release
  5. Add release notes from CHANGELOG.md
  6. Click Publish release

n8n Community Registration

Step 1: Wait for npm Package

The package must be live on npm before registering with n8n.

Step 2: Test Installation

Test that users can install your node:

# In n8n Community Nodes UI
Settings → Community Nodes → Install
Enter: n8n-nodes-openguardrails

Or via CLI:

npm install n8n-nodes-openguardrails

Step 3: Register with n8n

  1. Automatic Discovery: n8n automatically discovers npm packages with n8n-community-node-package keyword
  2. Package should appear in n8n's community node search within 24-48 hours

Step 4: Promote Your Node

Once published, share on:

Package.json Requirements

Ensure your package.json has these required fields:

{
  "name": "n8n-nodes-openguardrails",
  "version": "1.0.0",
  "description": "n8n node for OpenGuardrails AI safety and content moderation",
  "keywords": [
    "n8n-community-node-package",  // REQUIRED
    "n8n",
    "openguardrails",
    "content moderation",
    "ai safety"
  ],
  "license": "Apache-2.0",
  "homepage": "https://www.openguardrails.com",
  "repository": {
    "type": "git",
    "url": "https://github.com/openguardrails/n8n-nodes-openguardrails.git"
  },
  "n8n": {
    "n8nNodesApiVersion": 1,
    "credentials": [
      "dist/credentials/OpenGuardrailsApi.credentials.js"
    ],
    "nodes": [
      "dist/nodes/OpenGuardrails/OpenGuardrails.node.js"
    ]
  }
}

Files to Include in Package

Ensure .npmignore or package.json files field includes:

Include:

  • dist/ (compiled files)
  • README.md
  • LICENSE
  • package.json

Exclude:

  • node_modules/
  • src/ or uncompiled TypeScript
  • .git/
  • Test files
  • .env files
  • Development configs

Post-Publishing Tasks

1. Update Main Repository

If this node is part of OpenGuardrails main repo, update:

## n8n Integration

Install our official n8n node:

\`\`\`bash
npm install n8n-nodes-openguardrails
\`\`\`

Or install via n8n Community Nodes UI.

[Documentation](https://github.com/openguardrails/n8n-nodes-openguardrails)

2. Create Integration Documentation

Add n8n integration page to main docs site:

  • Installation instructions
  • Configuration guide
  • Example workflows
  • Video tutorial (optional)

3. Monitor Issues

  • Watch GitHub repository for issues
  • Respond to npm package issues
  • Monitor n8n community forum for questions

Updating the Package

When releasing updates:

1. Make Changes

# Create feature branch
git checkout -b feature/new-operation

# Make changes
# Commit changes
git commit -m "Add new operation"

# Push and create PR
git push origin feature/new-operation

2. Update Version

# Merge to main
git checkout main
git pull

# Bump version
npm version patch  # or minor/major

# This creates a git commit and tag

3. Update CHANGELOG.md

Add entry for new version:

## [1.0.1] - 2025-01-XX

### Fixed
- Fixed error handling for timeout errors

### Added
- Added support for custom timeout configuration

4. Publish Update

# Build
npm run build

# Publish
npm publish --access public

# Push tags
git push --tags
git push origin main

5. Announce Update

Post in:

  • GitHub Releases
  • n8n Community Forum
  • Twitter/X
  • OpenGuardrails Discord/Slack

Troubleshooting

Issue: "You do not have permission to publish"

Solution:

  • Verify you're logged in: npm whoami
  • Check package name isn't taken
  • Use --access public flag

Issue: "Package name too similar to existing package"

Solution:

  • npm may block similar names to prevent typosquatting
  • Choose a more unique name
  • Contact npm support if legitimate

Issue: "Version already exists"

Solution:

  • You cannot republish the same version
  • Increment version: npm version patch
  • Publish again

Issue: "Missing required field in package.json"

Solution:

  • Check all required fields are present
  • Validate with: npm pack --dry-run
  • Fix package.json and try again

Issue: "Build files missing in published package"

Solution:

  • Ensure dist/ is included in package
  • Check .npmignore or files field in package.json
  • Run npm pack --dry-run to preview

Best Practices

  1. Version Control: Always tag releases in git
  2. Changelog: Keep detailed changelog
  3. Testing: Test locally before publishing
  4. Documentation: Keep README updated
  5. Responsiveness: Respond to issues quickly
  6. Backwards Compatibility: Avoid breaking changes when possible
  7. Security: Never include secrets in published code
  8. Dependencies: Keep dependencies minimal and updated

Support Resources

Community Guidelines

When publishing to n8n community:

  1. Quality: Ensure node is well-tested and documented
  2. Maintenance: Commit to maintaining the node
  3. Support: Respond to user issues and questions
  4. Updates: Keep node compatible with latest n8n versions
  5. Security: Follow security best practices
  6. Licensing: Use permissive license (Apache-2.0, MIT)

Success Metrics

Track your node's success:

Maintenance Schedule

Recommended maintenance tasks:

  • Weekly: Check for new issues
  • Monthly: Update dependencies
  • Quarterly: Review and update documentation
  • Yearly: Major version review

Ready to publish? Follow the checklist above and ship it! 🚀

Questions? Contact: thomas@openguardrails.com