How to guide for writing your first plugin

  • Admin

    Here's a simple walkthrough on creating a hello world plugin followed by creating a simplified YouTube plugin.

    Hope it's useful! šŸ™‚

  • Community Rep

    Hey @psychobunny is there a way to load up JavaScript libraries for use in the admin settings part of the plugin?

  • Admin

    @bentael just includes a template and sticks a <script> tag in there. ajaxify will parse and run inline scripts. you could use require.js as well if you want to be neater

    let me know if you need a hand, also check out

  • Plugin & Theme Dev

    @BDHarrington7 also keep in mind that you have jQuery aka $ so you can use that and app (as the NodeBB app) in the global context as well, to do stuff like

      title: 'Error',
      message: 'Something went wrong while saving',
      type: 'danger',
      timeout: 2000
  • NodeBB Admin

    @bentael I added two helpers sometime ago to help with error and success alerts. app.alertError('oops') and app.alertSuccess('woot') are wrappers for app.alert(); haha emoji still parsing code blocks (flex)

  • Plugin & Theme Dev

    @baris nice.
    I got used to reading Emoji code. the emoji-image repo maintainer doesn't seem wanting to fix it.

  • GNU/Linux Admin

    @bentael Yeah, he doesn't want to, and I tend to agree, it's a bit out of scope for him.

    In mentions, I literally excise out the blockcode blocks and only send notifications to the mentions in the rest of the thread. Something like that could be done with emoji to just ignore <code> and <pre>...

    Hint hint: PR (think)

  • Plugin & Theme Dev

    @julian said:

    Hint hint: PR (think)

    haha sure, athough, smiley faces don't bother me when looking at code, makes me think that we need come smiley faces programming language, similar to LOLcode
    I'll look into a fix.

  • Admin

    yeah what if I wanted smiley faces in my code

    if ('baris' === nib && 'julian' === nib) {
        console.log("this always executes. (mooning) ")
  • NodeBB Admin

    actually that will never execute šŸ˜›

  • GNU/Linux Admin

  • GNU/Linux Admin

    function loadTopic() {
    Ā  return šŸ˜;

  • Plugin & Theme Dev

    I know there is a way to specify the min version of a (sub-)module with package.json.

    But is there a way to specify a module(plugin) version to work with a specific version of NodeBB (for instance)?

    This way, the plugin should work regardless the nodebb version and api changes.

  • GNU/Linux Admin

    There is, but only in a "minimum version" capacity. A plugin itself can specify that it has a "minimum version", and NodeBB will throw warnings if that is the case (that does happen now, as some plugins have a minver of "0.4.0", and the latest published NodeBB is still technically v0.3.2.

    Perhaps I should add a "safe mode" option, which, if enabled, would skip the loading of incompatible plugins...

  • @julian a ./nodebb safe option would be a nice tool to help with errors.

  • 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.


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


       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="$1" frameborder="0" allowfullscreen></iframe>'
       callback(null, postContent)

  • 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 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

    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": "",
        "library": "./library.js",
        "hooks": [
            { "hook": "", "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

Suggested Topics

| | |

Ā© 2014 ā€“ 2022 NodeBB, Inc. ā€” Made in Canada.