How to guide for writing your first plugin


  • This is an improvement of psychobunny's example which adds module support. The "callbacked" field in plugin.json may be unnecessary, all the code that I've seen checks that the last argument is a function before it treats it as a callback.

    plugin.json:

    {
       "id": "nodebb-plugin-youtube"
     , "name": "NodeBB YouTube Plugin"
     , "description": "NodeBB Plugin that enables users to embed YouTube videos inline in their posts."
     , "url": "https://github.com/psychobunny/nodebb-plugin-youtube"
     , "library": "./library.js"
     , "hooks": [
        {
         "hook": "filter:post.parse"
          , "method": "parse"
          , "callbacked": true
        }
     ]
    }
    

    library.js:

    /*
       nodebb modules (eg db) have paths that are relative to the object javascript source file.
       nodejs modules (eg async) have no path.
    */
    
    (function(Youtube) {
     'use strict'
    
     var  async = module.parent.require('async')
          db = module.parent.require('./database')
    
     Youtube.parse = function(postContent, callback) {
       postContent = postContent.replace(
         /<a href="(?:https?:\/\/)?(?:www\.)?(?:youtube\.com|youtu\.be)\/(?:watch\?v=)?(.+)<\/a>/g,
         '<iframe class="youtube-plugin" width="640" height="360" src="http://www.youtube.com/embed/$1" frameborder="0" allowfullscreen></iframe>'
       )
       callback(null, postContent)
     }
    
    }(module.exports))
    

  • Hey

    I've been trying to write a plugin and have been following the guide by @psychobunny creating a plugin.js and library file. Then I was stuck since I don't know where to put these files.
    According to this https://docs.nodebb.org/et/latest/plugins/create.html I should be able to create a directory under /plugins/nodebb-plugin-my-test-plugin/ and then loaded my NodeBB instance with ./nodebb dev. And can't find any indication that my library is loaded, either in the log or in the admin -> plugin interface.

    Anyone who can hint what I'm missing.

    Best regards?


  • @h_kirk Hey buddy, plugins go in a nodebb-plugin-plugin-name folder inside your node_modules folder, and need to be enabled from your admin ACP by going to extend > plugins. 👍


  • Thanks for the quick replay.

    I have actually tried this. Both in normal and dev mode. And both with my ID begin nodebb-plugin-plugin-name and just plugin-name. There is no indication in log or in the admin interface that my plugin is recognised.

    My directory looks like this:

    /nodebb/node_modules/nodebb-plugin-force-tag$ ls
    library.js  LICENSE  plugin.json  README.md
    

    And my plugin.json file like this:

    {
        "id": "nodebb-plugin-force-tag",
        "name": "NodeBB ForceTag Plugin",
        "description": "NodeBB Plugin that forces users to tag a post.",
        "url": "https://github.com/hkirk/nodebb-plugin-force-tag",
        "library": "./library.js",
        "hooks": [
            { "hook": "action:post.save", "method": "forceTag" }
        ],
    }
    

    Anything else i have misunderstood.

    Best regards


  • I had the same Issue. Other than mentioned, you have to place a package.json in you plugin-root.

    // package.json
    {
            "name": "nodebb-plugin-yourname",
            "version": "0.0.1",
            "description": "NodeBB plugin",
            "main": "library.js"
    }
    

    Otherwise the used npm technique would not be able to "find" it.

    PS: How to enter CodeBlock ? XD


  • Cool @termnml the package.json file did the trick.

    Maybe that should be mentioned along with the plugin.json file.

    Anyway thanks a bunch.


  • @psychobunny could 😉


  • @termnml said:

    PS: How to enter CodeBlock ? XD

    4 spaces like this:

    {
         "name": "nodebb-plugin-yourname",
         "version": "0.0.1",
         "description": "NodeBB plugin",
         "main": "library.js"
    }
    

    Or wrap it with ``` top and bottom, like this

    {
             "name": "nodebb-plugin-yourname",
             "version": "0.0.1",
             "description": "NodeBB plugin",
             "main": "library.js"
    }
    

    Quote my post to see the formatting. 👍


  • @a_5mith said:

    @termnml said:

    PS: How to enter CodeBlock ? XD

    4 spaces like this:

    {
         "name": "nodebb-plugin-yourname",
         "version": "0.0.1",
         "description": "NodeBB plugin",
         "main": "library.js"
    }
    

    Or wrap it with ``` top and bottom, like this

    {
             "name": "nodebb-plugin-yourname",
             "version": "0.0.1",
             "description": "NodeBB plugin",
             "main": "library.js"
    }
    

    Quote my post to see the formatting. 👍

    Ha. Thx. 👍


  • I tried following this, and I can't even get the basic "hello, world" logging.

    nobebb/node_modules/nodebb-plugin-json-auth/package.json

    {
    	"id": "nodebb-plugin-json-auth",
    	"version": "0.0.1",
    	"name": "NodeBB JSON remote Authentication",
    	"description": "Replaces NodeBB login with a remote location.",
    	"library": "./library.js"
    }
    

    nobebb/node_modules/nodebb-plugin-json-auth/library.js

    console.log('hello, world!');
    

    When I look in Advanced > Logs I can see the "reloading..." and such logged, but there is no "hello, world!". It doesn't appear in Extend > Plugins, either.


  • @Sadtaco Use this as a guide, but you need library, plugin & package as a minimum usually.


  • @a_5mith said:

    @Sadtaco Use this as a guide, but you need library, plugin & package as a minimum usually.

    That was it. nodebb does not recognize it without a package.json as well. The docs make no mention of that and only go over plugin.json and the js file.


  • The doc is over two years old. so does contain out of date info.

    Refer to the documentation, it'll likely be more up to date. Link to Documentation


  • @a_5mith said:

    The doc is over two years old. so does contain out of date info.

    Refer to the documentation, it'll likely be more up to date. Link to Documentation

    That's where I found that to begin with. It didn't mention needing a package.json https://docs.nodebb.org/en/latest/plugins/create.html so that needs to be added.


  • This post is deleted!
  • Plugin & Theme Dev

    I created a very simple skeleton plugin for reference that works as of NodeBB 0.7.2 https://github.com/jongarrison/nodebb-plugin-skeleton

  • Plugin & Theme Dev

    I should also mention that this includes instructions on how to use 'npm link' to use a plugin that is under development.

  • Plugin & Theme Dev

    Here is another thing that would be good for new plugin devs to find early on...

    https://github.com/NodeBB/nodebb-plugin-quickstart/

    Maybe this thread is getting kind of old and shouldn't be pinned any more. When I was starting out trying to develop some plugins it lead me down some odd roads. It is good to see where all of the active community members get their start though 😄

  • Admin

    Good point. Unpinned, this is pretty damn old haha.

  • GNU/Linux Admin

    I think it's time to publish some new guides on our blog 😄

Suggested Topics

| |