Setting up your development environment

Overview

Totara 13+ needs some development environment setup to optimise your workflows. There are some changes compared to pre-13 versions.

Config

Add the following settings to your config.php, they work independently from non-Tui JS and Theme settings within config.php. They will enable more efficient development for working with the Tui framework:

$CFG->forced_plugin_settings['totara_tui'] = [
    'cache_js' => false, // Disable JS caching of Tui JS
	'cache_scss' => false, // Disable JS caching of Tui CSS
    'development_mode' => true, // Put Tui into development mode so that you get non-minified source
];

These settings are also available from within Totara's UI, by navigating to /admin/settings.php?section=totara_tui_settings.

Editor/IDE setup

VS Code

Syntax highlighting and Vue file support: Install Vue - Official
(optional) Install Prettier, ESLint, Stylelint, and EditorConfig plugins

PhpStorm/WebStorm

Vue.js syntax highlighting is built into PHPStorm
The ESlint plugin is built in and supported out of the box
Install Prettier plugin (optional)
To enable format-on-save (optional), go to Preferences > Tools > File watchers and create a new file watcher with the following options:
- File type: Vue.js Template
- Scope: Project Files
- Program: $ProjectFileDir$/node_modules/.bin/prettier
- Arguments: --write $FilePathRelativeToProjectRoot$

Web browser extensions

There are two extensions available for developers that facilitate working with GraphQL and Vue.js technologies. They are:

Apollo Client devtools (Chrome / Firefox)
Vue.js devtools (Chrome / Firefox)

Adding either/both of these extensions to your web browser will add the relevant Tab inside Devtools.

Node

Check the package.json engines.node field for the minimum required Node.js version. Generally the latest LTS version is supported.

Docker

A number of Totara developers use Docker to isolate development environments. Totara maintains totara-docker-dev on GitHub specifically for this purpose. Follow the setup instructions on that repo for details. This setup is particularly useful when working with multiple Git branches or repositories that have different environment requirements, such as PHP and database version.

Linting and formatting

We use Prettier to format code and components. This removes the need to discuss style in code review, improves efficiency and makes our code more consistent with third-party code and documentation.

Internally, we don't enforce when Prettier is run during local development, however code will be formatted with Prettier during our CI/CD checks, and so all of our PRs are formatted when they're ready for review by team members.

ESLint is used to catch issues that aren't related to formatting.

To run these linters, you have a few options:

Install ESLint and Prettier plugins in your editor and configure it to format on save or on demand
The following commands can be used to run lint

// The following will report any style problems
npm run tui-style-check

// The following will fix any style problems for you (handy huh!)
npm run tui-style-fix

The following command will install a git hook that will automatically lint and format for you when you commit code:

npm run setup-hooks

Tips and known limitations

Windows developers might consider using the following combination of technologies: WSL2 + VS Code + Remote WSL extension.

Running into JavaScript compilation issues? There might have been a Node dependency difference between your current working files and a different set. For example, if you regularly switch Git branches and between those branches you have different dependencies. A good catch-all command to run is:

This will perform a clean installation of /node_modules based on the contents of /package.json located at the root of the Totara codebase.

Public developer documentation