Coding 3 by phoneix faerie-d7idtti
Blacksmiths are vital to the success of Habitica. Your contributions are needed and appreciated! There are several ways to contribute coding expertise to the website and mobile apps. A great first step in getting acquainted with what needs to be done is joining the Aspiring Blacksmiths (Habitica Coders) guild to discuss programming for the site, learn some tips, and get ideas for what to work on. Important announcements that need to be broadcast to all coders can also be found on The Forge, Habitica's blog for blacksmiths.

Be sure to also read Setting up Habitica Locally for important information about getting started.

Ways to HelpEdit


Below are tips for finding items to work on, depending on how you would like to contribute. In all cases, check the notes for the current status of the issue and whether anyone else is actively working on it (if a pull request is linked, someone has already submitted a fix).

It is strongly recommended that before you start work, you post a comment on the GitHub issue or Trello card asking about the status of the item and expressing your interest in helping resolve it, and then wait a couple of days to see if there are any responses. This is because some issues and feature requests are not suitable for working on because Habitica's chief developers are currently making some large-scale changes to some parts of the code, which will partially or fully fix some issues. This is true even of the issues labeled with the GitHub Labels listed below.

If someone else has already recently commented to say they are working on an issue or Trello card, please leave the work for them. However, if it has been many days since their last comment, they might no longer have time to contribute to Habitica, and then it could be appropriate for you to ask if you can take it over.

Before starting work on an issue or feature, you might like to describe your suggested approach so that we can comment on whether it's suitable.

  • I want to start small: Check out the Github issue queue and search for items labeled type: entry level coding for issues where you can ask to contribute.
  • I want to help where I'm most needed: Search for Github issues labeled status: issue: help welcome now, priority: critical, and priority: important and ask to contribute before starting. Solving a bug labeled priority:critical will allow you to earn the Critical Hammer of Bug-Crushing.
  • I want to create unit tests & Karma tests!: Welcome, bug-slayer! Please refer to the Tests section for further information.
  • I want to build things!: Make way for the new hero! Check out the Trello feature queue. It is important that you ask first to find out if a feature request you select is approved by the staff. Some feature suggestions are not suitable for implementation and a pull request that implements them would not be accepted.

The website's repository uses other labels in addition to the ones listed above. You can read about them in GitHub Labels, but the ones listed above will be of most use in finding useful issues to work on.

Mobile App for iOSEdit

  • If you want to contribute to the iOS app, the Issue list contains a list of already requested features and known bugs. Feel free to look through them to find things you would like to work on. In order to prevent duplicate work, a comment should be left on the issue you intend to work on. If you would like to work on a feature that does not yet have an existing issue, please create one first, so that implementation details can be discussed.

Mobile App for AndroidEdit

  • If you want to contribute to the Android app, the Issue list contains a list of already requested features and known bugs. Feel free to look through them to find things you would like to work on. In order to prevent duplicate work, a comment should be left on the issue you intend to work on. If you would like to work on a feature that does not yet have an existing issue, please create one first, so that implementation details can be discussed.

BountySource Edit

Some issues will have BountySource bounties on them, posted by staff or users. If your fix for such an issue is accepted, you will be able to claim the money as payment. In all other ways, these issues are treated identically to issues without bounties, so follow all the normal guidelines for them (e.g., asking first if it's okay for you to work on the issue).

Website Technology StackEdit

The technologies Habitica uses for its website are listed below. You don't need to be familiar with all of them, or even most of them, to be able to contribute! Some links to high-quality learning material are also included. Many of these technologies (namely, the ones with '.js' or 'JS' in the name or URL) are based on the programming language JavaScript, which you can learn here.

Server Edit

Technology Further Information
Node.js How do I get started with Node.js

nodeschool -- included in the Stack Overflow article linked above, but a particularly useful entry-level interactive Node curriculum.

See the Angular/Node/Pug Tips and Best Practices section.

MongoDB See the MongoDB section.
Gulp Check out the Gulp GitHub page to get started.
Git and Github Pro Git -- Taking the time to read this excellent resource will help you become more comfortable with Git.

git-it -- This fun and interactive part of the nodeschool curriculum will help with learning Git and Github. (Scroll down for more information.)

ESLint Eslint config for HabitRPG projects

Client Edit

Technology Further Information
(Angular 1)
Habitica will stop using Angular in future, so if you are considering learning Angular specifically to help with Habitica, you might want to not spend too much time learning it in great depth. Vue.js will be used instead.
Shaping up with Angular.js -- A video tutorial series with accompanying exercises. Completing the exercises as well as viewing the videos is recommended to understand Habitica's AngularJS code.

Learn Angular -- Free interactive lessons.

See the Angular/Node/Pug Tips and Best Practices section.

Pug (Jade) Pug (formerly Jade) is used to meet the need for a server-side templating language to allow injection of variables (`res.locals` from Express).

Pug's "significant whitespace" paradigm also protects from committing common HTML errors such as missing or mismatched close tags.

See the Angular/Node/Pug Tips and Best Practices section.

Stylus Standard CSS was insufficient for our app, so Stylus was adopted.
Vue.js Vue.js is not currently used with the production code but will be used in future to replace Angular.js. Habitica's admins recommend these learning resources:

Testing Edit

Technology Further Information
Karma Running Unit Tests on KarmaSee the Tests section.
Selenium Used only for an end-to-end test of the static home page.
Travis CI Used to run all the tests for every pull request, and report results.

 Services Edit

Technology Further Information
New Relic
Amazon Web Service (AWS)

API ChangesEdit

On 21 May, 2016, version 3 of Habitica's API was released. Version 2 no longer works. Information about the new API is available at Application Programming Interface. Questions can be asked in the Aspiring Blacksmiths (Habitica Coders) guild. Important announcements on the API changes can also be found on The Forge, Habitica's blog for blacksmiths.

If you have a local install that was created when version 2 was in use, delete it and follow the process in Setting up Habitica Locally to create a new local install.

Working with a Local Installation Edit

Blacksmiths should create a local running instance of Habitica, for testing and development. The process to create a local instance can be difficult, so we've collected steps for each operating system at Setting up Habitica Locally.

The process of using your local installation to make changes and create pull requests is described in Using Your Local Install to Modify Habitica's Website and API.


These are quick tips for new developers to get the hang of using the Mongo database. In the commands below, the $ sign indicates a Unix, Windows or Git Shell prompt and the > sign indicates a Mongo shell prompt. Type only the text that appears after $ or > into your command line.

Access a shellEdit

Start the mongo shell then select the database:

   $ mongo
   > show dbs
   > use habitrpg

Alternatively, directly start the shell with the correct database:

   $ mongo habitrpg

Use the shellEdit

View the "collections" in the database ("users", "groups", etc):

   > show collections

Find your test user and examine its data. From localhost settings, copy the User ID, then run this command:

   > db.users.find({_id: '85b007a2-b5b9-4bb4-8b82-e4567edb4919'})[0]

Want to see the preferences only?

   > db.users.find({_id: '85b007a2...'})[0].preferences

To update something for your user, use the update method with $set. For example, edit your profile blurb:

   > db.users.update({_id: '85b007a2...'}, {$set: {'profile.blurb':'test'}})

Give yourself 10 gems (can also be done from the Debug menu in the lower right of the footer):

   > db.users.update({_id: '85b007a2...'}, {$set: {'balance':10}})

Get admin rights (you will then see extra options in the Hall):

   > db.users.update({_id: '85b007a2...'}, {$set: {'contributor': {'admin':1}}})

Assign yourself unpurchasable quest scrolls (e.g., for limited edition quests):

   > db.users.update({_id: '85b007a2...'}, {$set: {'items.quests': {"egg":2,"basilist":1,"evilsanta":1,"evilsanta2":1}}})

This gives the user two Egg Hunt scrolls and one scroll each for another three quests. Please note that this will clear all other quest scrolls that the user possesses. Other scrolls can be added in the same way (respective keys can be found in common/script/content/index.js, although this file name is likely to change soon because the code is being refactored) or can be purchased later from the market.

Creating a local user account identical to your production site accountEdit

Export your user data using the GET /user API route, and import it locally using MongoDB commands such as db.collection.insert(). This can be a fast way to create a local account prepopulated with tasks, equipment, currency and inventory.

Your account will need to be inserted into the users collection, but this collection won't exist in Mongo until an account is created in your local install. To do this, start your local install and create a test account, and then insert your production account.

The API does not export some authentication information for security reasons, so you will need to set it after inserting your user data. The command below sets the password to "test" and creates an API token:

   > db.users.update({'auth.local.username': 'your-username'}, {$set: {'auth.local.salt': '7eff6ff32a', 'auth.local.hashed_password': '5b5d5f748091e62aadf2f109f4a7379d2d8653dc', 'apiToken': '48ed9d70-0adf-431d-a001-1cb12d57590e'}});

Warning! Do not use the same API token or password that are used for your production site account!

If you ever need to seek support for your local install or report information from it, you might include the full authentication data, and if it were the same as for your production account, the security of your production account would be compromised. The token used in the example above was randomly generated and is safe to use in your local install.


Some Habitica website changes require existing user accounts to be modified (e.g., to assign a default value for a new setting to all users). Such database changes are done with a migration script, which contains JavaScript that connects to the database and makes modifications. All migration scripts are in migrations/. Read them and use them as examples to write your own script. The more recently edited scripts are likely to contain better, more up-to-date code than older scripts.

To test a migration script:

   $ mongo habitrpg migrations/name_of_script.js

Angular/Node/Pug Tips and Best PracticesEdit

Data Binding, and Template ConditionalsEdit

When working in the Pug templates, you may see element attributes such as ng-class, ng-show, or ng-if. These are bindings used to map model data to elements for display that are part of AngularJS. These bindings can be used to define styles or display elements based on conditionals.

You may also notice some other attributes such as bo-class or bo-if.... so what's the difference?

Bindings that begin with "ng" are part of Angular and are completely dynamic. This means every time something changes with the app, Angular will test all of these bindings with conditionals and take action again. Obviously this is a concern for performance.

Sometimes the data used to calculate these conditionals will not change often, if ever. In that case, we have an option for static binding, using a library called Bindonce. These are similar bindings, but they are only checked at the initial load of the application.This is the preferred method of binding as long as the data will not change.

Bindonce directives should only be used when the model data being used for the conditional will not change during a session, or will change infrequently enough that it's not unreasonable to expect the user to refresh the page. If this is not the case, then stick with traditional binding. If you can't decide or have no idea what you just read, just use the ng-<whatever> attributes.

Translatable Strings (locales files)Edit

Translatable strings appear in files in the website/common/locales/en directory. Each string consists of a key and a piece of text, for example:

   'clearAll': 'clear all items',

Adding Translatable StringsEdit

To add a new translatable string write it in the jade file as follows:


Then, in the website/common/locales/en directory, edit the appropriate json files, adding the new string as follows:

       'lastLabel': 'Add a comma at the end of this line',
       'stringLabel': 'String Title'

If there are already strings in the json file about the same topic, then it's preferred that you add your new string in the same place as the existing ones, to keep similar strings together.

Do not edit files in other directories under website/common/locales because all translations are managed in Transifex.

To test the string:

  • stop npm if it is running (Ctrl-C)
  • run npm start

Modifying Translatable StringsEdit

Existing strings can be changed whenever necessary. Only change the strings in the website/common/locales/en directory, never in any of the other language directories.

Do not change the keys unless there's a good reason to do so. For example: if you needed to change the string 'clear all items' to 'delete all items', you would not also change its key 'clearAll' to 'deleteAll', since the meaning of the original key is still accurate.

The reason the keys are usually not changed is because they can be referenced in more than one place in Habitica's code and so all of those pieces of code would need to be updated; this is undesirable unless there's a good reason for it. In addition, when a key is changed the translators need to redo the translations without having the original translation visible for comparison. Note that when there is a reason to change the keys, you still should not modify the locales directories for languages other than English.


Refer to Using Your Local Install to Modify Habitica's Website and API for information about tests.


For information about creating new images for Habitica, see Guidance for Artisans.

When a new image has been prepared and approved by the staff, an issue will be created to request it be added to Habitica. A Blacksmith will then need to add it to the repository. Most images will need to be copied into suitable subdirectories under common/img/sprites

After adding new images or new versions of existing images, run npm run sprites to recompile the image spritesheets.

Sometimes, this command will result in a new spritesheet being created, in which case use git add to add the new files. You will find them under common/dist/sprites (look for a *.png and *.css file for each spritesheet).

Other Useful CommandsEdit

Here are various helpful commands.

Search codeEdit

In the console, type:

   grep -R "STRING" *

To search for STRING in all files in the current directory and all the directories within it.

To make a search case insensitive (STRING or String or string etc), add -i

   grep -iR "STRING" *

You'll often want to search all files containing some keyword, in order to determine what files need to be edited when adding/editing some feature.

The grep command also takes a regex as its search parameter:

grep -R "REGEX" *

Read more about grep and regex here.

Preference SettingsEdit

Habitica has preference settings for the users to customize the website's behavior. New settings may be added if necessary. Please do not add settings only a small proportion of users are likely to use, or settings for trivial customizations. Instead choose a behavior the majority of users are likely to enjoy.

Too many preferences makes the settings screen look cluttered and increases the appearance of complexity. If you're uncertain about whether a preference setting is desirable, you can discuss it in the Aspiring Blacksmiths (Habitica Coders) guild or in a relevant Github issue or pull request.

Tip for storing preferences Edit

When a new user preference setting is necessary, it can be added to website/src/models/user.js. Generally, the database will then pick them up the new setting automatically and add it to user accounts as necessary. If it is ever necessary for the database to be modified manually, admins can do that.

Generating Shrinkwrap Edit

Shrinkwrap is how we manage to lock in dependency versions for npm modules. This helps when deploying or distributing the app to multiple sources. The shrinkwrap file will update automatically if you use --save, but if you need to recompile manually, follow these steps:

  1. Run npm prune
  2. Run npm shrinkwrap

"Information for Developers" Sections on General Wiki PagesEdit

At the bottom of some wiki pages, are sections called Information for Developers. These contain useful tips for Blacksmiths related to the content on that page.

The information is hidden behind a spoiler-style show/hide toggle button so it doesn't clutter the page for non-technical users.

The sections use the {{InfoForDevs Start}} and {{InfoForDevs End}} templates to ensure correct formatting and wording for the buttons and other text. To see how that is done, open any page with an Information for Developers section in the source editor.

To see a list of all pages with this section, use the "What links here" tool for the 'Start' template.

To see all Information for Developers sections unhidden by default:

  • Create a Wikia account if you don't already have one.
  • Edit your personal Wikia css file, located at:
  • Insert these lines into CSS file:
   /* Force all "Information for Developers" sections to always be visible */
   .habitrpg-InfoForDevs {
       display:block !important;
   .habitrpg-InfoForDevs-hideIfDev {

You can see an example at User:LadyAlys/wikia.css

Contributor Tier Process Edit

You're in luck! Blacksmiths do not need to do anything special, like complete a Contributor Tier request (as Scribes are requested to do), in order to earn Contributor Tiers. Contributor Tiers for Blacksmiths will be granted by the admins as they review and accept Blacksmith submissions. Admins will track Blacksmith contributions for credit toward future Contributor Tiers.

The first one or two Contributor Tiers from Blacksmithing are fairly easy to get, and you might find that a single pull request being completed is enough for each of them. The higher tiers require progressively more work, and several successful pull requests might be needed. Admins will record each pull request when it is completed, and will award a tier when enough contributions have been made.

Generally, when a PR is merged, an admin will write in both the PR and Hall of Heroes something like "I've given you Tier x" or "Noted toward your next contributor tier." If they write something like the latter, it means that PR alone was not enough for a tier by itself, or not enough to increase your tier to the next level if you already had other partial credit towards it.

See Also Edit

Ad blocker interference detected!

Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.