Beginner's Guide to Creating Discourse Plugins - Part 1


(Robin Ward) #1

Building a plugin in Discourse can be really simple, once you learn a couple of quirks. The goal of this post is to create a skeleton plugin and introduce you to the basics.

Your development environment

Make sure you have a development environment of Discourse running on your computer. I recommend you use this setup guide and come back when you’re done.


When Discourse starts up, it looks in the plugins directory for subdirectories containing a plugin.rb file. The plugin.rb file has two purposes: it is the manifest for your plugin with the required information about your plugin including: its name, contact information and a description. The second purpose is to initialize any ruby code necessary to run your plugin.

In our case, we won’t be adding any ruby code but we still need the plugin.rb. Let’s create the directory basic-plugin with the file plugin.rb inside it, with the following contents:


# name: basic-plugin
# about: A super simple plugin to demonstrate how plugins work
# version: 0.0.1
# authors: Awesome Plugin Developer

Once you’ve created this file, you should restart your rails server and the plugin should be loaded.

An important Gotcha!

If you’re used to regular rails development you might notice that plugins aren’t quite as nice when it comes to reloading. In general, when you make changes to your plugin, you should Ctrl+c the server to stop it running, then run it again using bundle exec rails server.

My changes weren’t picked up! :warning:

Sometimes the cache isn’t cleared fully, especially when you create new files or delete old files. To get around this issue, remove your tmp folder and start rails again. On a mac you can do it in one command: rm -rf tmp; bundle exec rails s.

Checking that your plugin was loaded

Once you’ve restarted your rails server, visit the url /admin/plugins (make sure you’re logged in as an admin account first, as only admins can see the plugin registry).

If everything worked, you should see your plugin in the list:

Congratulations, you just created your first plugin!

Let’s add some Javascript

Right now your plugin doesn’t do anything. Let’s add a javascript file that will pop up an alert box when discourse loads. This will be super annoying to any user and is not recommended as an actual plugin, but will show how to insert Javascript into our running application.

Create the following file:


export default {
  name: 'alert',
  initialize() {
    alert('alert boxes are annoying!');

Now if you restart your rails server, you should see “alert boxes are annoying!” appear on the screen. (If you did not, see the “My Changes weren’t picked up” heading above).

Let’s step through how this worked:

  1. Javascript files placed in assets/javascripts/discourse/initializers are executed automatically when the Discourse application loads up.

  2. This particular file exports one object, which has a name and an initialize function.

  3. The name has to be unique, so I just called it alert.

  4. The initialize() function is called when the application loads. In our case, all it does is execute our alert() code.

You’re now an official Discourse plugin developer!

Where to go from here

Part 2: Plugin Outlets
Part 3: Site Settings
Part 4: git setup
Part 5: Admin interfaces
Part 6: Acceptance tests

Beginner's Guide to Creating Discourse Plugins Part 2: Plugin Outlets
Beginner's Guide to Creating Discourse Plugins Part 3: Custom Settings
Beginner's Guide to Creating Discourse Plugins Part 4: Git Setup
Beginner's Guide to Creating Discourse Plugins Part 5: Admin Interfaces
Beginner’s Guide to Creating Discourse Plugins Part 6: Acceptance Tests
Manipulating search box
How to start building stuff for Discourse if you're newbie (like myself)
Connecting to database with a plugin
Where to see if discourse can do what I want?
Beginners Guide to Install Discourse on Ubuntu for Development
How to create a plugin, that overrides the landingpage
Minimal Topic List Design with Sidebar for Navigation
Categories Topic Replies
How do you learn how to build these plugins
Create fully custom header
Discourse Development Contribution Guidelines
How to create a new plugins?
Overwriting controllers in plugin
Added custom initializer
Separating View from Data, Plugins, Modularity
Plugin Tutorial #1 - How to manipulate the text in the composer?
Discourse Hot Loader
Customization of discourse
Plugin API documentations?
How to properly display jalali dates for Persian language
Custom Layouts Plugin
LDAP login into Discourse
Allow reply-to individual instead of topic/forum (mailing list feature)
Best guides for creating Discourse plugins?
How do you learn how to build these plugins
Javascript getElement methods doesn't work
Custom home page to discourse
New columns in directory (/users)
Push to digital ocean from command line and rebuild
How can I add "dislike" button?
Which files can you override from a plugin?
Customizing CSS via plugin
How to convince my university to use/install Discourse?
Send Email to User When Mentioned
Hack to enable invitations for Trust level 1 users
Help needed in creating plugin to redirects user to pass reCAPTCHA v2
Customization of discourse
Putting username in header link
Dropcaps in Discourse - cannot override span tag
How to hide a DIV with javascript on Discourse? and then change as users navigate?
Few clarifications on Discourse
Plugin: add a menu icon (next to search)
Error When creating custom plugin
Error When creating custom plugin
IOTA as a currency for Discourse
Emails only to users with specific group?
Recompile discourse without pulling new version
Topic Ratings Plugin
Why do I need a block storage?
Beginners Guide to Install Discourse on Mac OS X (macOS) for Development
Rails Girls 2015 SoC Banter
About the Plugin category
About the Plugin category
Show "topic-excerpt" for all post on Latest Page
Visual diagraming to add visual dimension to Conversations?
Show "topic-excerpt" for all post on Latest Page
Hide features for non-admin users through plugin
Custom Onebox engine
(Mittineague) #2

Thanks for this plugin guide.
I appreciate it and hope to see many more soon.
I really do.
In fact, I tried it and it worked great!

So, no offense intended, … … …

I would like to suggest one small change for those not masochistically inclined :ambulance:

//    alert('alert boxes are annoying!');
    console.log('console logging is not annoying!');

(Robin Ward) #3

I considered console.log but I didn’t want to have to explain “open your dev console” too :smile:

(Ladydanger) #4

Great guide - we tried it today and worked perfectly :smile:

(Matt Jones) #5

Thanks for the guide. I expected it to be complicated, but it looks pretty simple! I’m looking forward to having a play around with plugin development! :smiley:

Is there anything more to the JS integration? Are there any other supported functions other than initialize?

You’ve whet my appetite! I’d love to see something more in depth.

(Michael Kitzman) #6

I followed the instructions to set up my development environment, and I now have my system ready to go.

I just don’t know how to log into this system now…

Any advice on getting set up with my first admin user would be much appreciated.

(Mittineague) #7

Try these

(Michael Kitzman) #8

That was absolutely it! Thank you very much for that!

Running rake admin:create was absolutely what I wanted.


Thanks for the guideline

(Frank Piva) #13

I followed these instructions and was not able to get the alert box to show up on my site.

I can view the plugin from the Admin panel, but after restarting my container there is no alert box that shows up. I have also tried console approach instead of using an alert, but have not had any luck. I have double-checked for typos, but haven’t found any.

Is this tutorial outdated?

(Jeff Atwood) #14

Anything here we need to update @eviltrout?

(Robin Ward) #15

Are you trying to use this guide in production? Because it is meant to be used in a development environment as a way of creating plugins. The reason I ask is you said container which is how we host discourse in production mode.

In production, you have to have a plugin installed using git clone commands.

(Frank Piva) #16

This makes sense then. I am running Discourse in production mode, and have previously installed plugins by adding git clone commands to the .yml file. I’ll try to get a development environment going and see if I have success.

(Frank Piva) #17

Ok, so I FINALLY got a development instance of Discourse running, but I am still unable to see the alert box. Again, I have checked to make sure I didn’t make any typos in the path name or in the code itself. After creating alert.js.es6 I ran ‘bundle exec rails s -b’. The site is still accessible through the browser, but no alert box. I can see the plugin in the admin panel, but it is only in black text; unlike the rest of the plugins which are in blue.

I am a Discourse/Rails newbie so I apologize if I am making an obvious mistake.

(Alan Tan) #18

Can you push your code to Github and link it here? Otherwise, it’ll be hard to see what is going wrong :slightly_smiling:

(Robin Ward) #19

Did you try the impotrant gotcha referred to here?

(Frank Piva) #20

I thought I tried clearing out the /tmp directory, but when I tried it a second time it worked. For the record though, bundle exec rails s does not start the server on my instance. I have to run bundle exec rails server -b in order to get the instance to serve pages.

(Tyler Thrailkill) #21

I also cannot get the alerts to load. Here’s a link to the repo with the plugin, nothing else has changed besides the plugins folder. GitHub - snowe2010/discourse_plugins: Writing some plugins


Did you nuke the tmp directory and restart rails?

I got to page 5 before issue popped up.

(Tyler Thrailkill) #23

Yeah I’ve nuked it almost every single time. What do you mean you got to page 5 before the issue popped up?