UPDATE: Version bump - alpha81

Hi All,

Todays release update brings quite a few major changes to the internals OS.js.

The goal of this update was to redo some parts to make development [of certain aspects] much easier to approach and understand. Let me know if I succeeded…



These are the major changes coming with this update. For a digest of all changes, look in the bottom of this article.

  • Rewritten backends with drop-in module support
  • Handlers is now phased out in favor of Connection, Storage and Authenticator
  • Server-side VFS Transport modules
  • CoreWM Widget support
  • Grunt no longer a main dependency
  • Entirely new documentation

You can read about all the new stuff (and the old) here: https://os.js.org/manual/

CLI Changes

Since Grunt is no longer used as the task runner (which I wasn’t really using anyway… it all ran a custom solution, with Grunt as a CLI parser for the most part), you now do: node osjs <task> instead of grunt <task> (You can also just do ./osjs <task>).

For testing, linting etc, Grunt is still used and installed via devDependencies.

You can read all about this in the new manual linked above.

Misc Changes

Some files have also been moved around in the client codebase. More spesifically a new directory named src/client/javascript/core now holds the core files.

Migration Guides

This update has backward compability, but it is not guaranteed to work 100% due to the changes in the mechanics of the backend.

NOTE: This update also ignores your Handler completely (if you made one). You’ll have to make use of the new abstractions (but your code should still work… it has just been moved and modified slightly.).

Application APIs

Nothing major here. Just some changes to the arguments passed on and the export layout:

// From:
module.exports.methodName = function(args, callback, request, response) {
  callback(false, 'test');

module.exports._onServerStart = function(server, instance, metadata) {

// To:
module.exports.api = {};
module.exports.api.methodName = function(env, http, resolve, reject, arguments) {
  // resolve({someData: true}); // Success!
  // reject('Error message'); // Error!
  // http.respond.<custom>(content); // Custom HTTP response

module.exports.register = function(env, metadata, servers) {

Extension APIs

Same as with the Application API.

// From:
module.exports.register = function(API, VFS, instance) {
  API.methodName = function(server, args, cb) {
    // ...

// To:
module.exports.api = {};
module.exports.api.methodName = function(http, data) {


You can look up the included Connection, Authenticator and Storage modules to get an idea of how it is implemented.

It has mostly stayed the same, but methods have been moved around to get a better abstraction.


Changes to mount definition:

// "home" is now dynamic
  "server" : {
    "vfs": {
      "mounts": {
        "home": "%DROOT%/vfs/home/%USERNAME%",
        "osjs": "%DROOT%/%DIST%",
        "shared": "%DROOT%/vfs/public"

// Now possible to have server-side transports
  "server" : {
    "vfs": {
      "mounts": {
        "home": {
          "transport": "custom_name"

Some notes

Make sure to run: npm install --production or else you’ll be presented with lots of errors. Also make sure to rebuild!

If you get errors while building, it might be possible that your src/conf/900-custom.json file contains some settings that are no longer interpreted correctly. This should only be relevant if you’ve enabled HTTPS/HTTP2 via configuration. Remove these entries and try again.

Relevant Links


This is a curated list of changes since last release:

  • Settings: Make sure window title is translated (#511)
  • Settings: Add back window switcher toggle saving
  • Settings: Better handling of startup category argument
  • Settings: Better VFS mounting
  • Preview: Support opening external locations
  • CoreWM: Widget Support
  • CoreWM: Iconview bugfixes
  • CoreWM: Added a developer tool notification icon with menu
  • VFS: Add missing VFS.File parameter in delete check (Fixes #509)
  • VFS: Added client-side watch() and unwatch() methods
  • VFS: scandir() can now concat entries from a given metadata file
  • VFS: Bugfixes and cleanups
  • VFS: Fixed backlink showing on roots
  • VFS: Server-side watching
  • API: Fixed resolving custom icons for packages
  • API: getFileIcon() now supports ‘application’ VFS Files
  • GUI: Added add() remove() and set() methods to Tabs
  • GUI: Some bugfixes to menu events
  • GUI: Moved some element/scheme stuff around, better creation of elements
  • Dialogs: Added ‘create directory’ to File (on save and directory select)
  • Window: Corrected wrong scope in resize finished callback (Fixes #506)
  • Window: Added _create() shortcut to create new GUI elements
  • Utils: Added more keycodes and freezed namespace
  • Utils: Added full ASCII key map
  • Utils: Removed some deprecated methods
  • Utils: Fixed early (too) early cleanup of XHR request
  • Utils: Added deep-clone object method alternative
  • Utils: Updated pathJoin()
  • iframe-application: Added callback-style messaging sypport
  • default-application: Removed some deprecated stuff
  • default-application: Added callback support on save
  • client: Now uses a Connection class instead of Handler methods
  • client: Now uses a Authenticator class instead of Handler methods
  • client: Now uses a Storage class instead of Handler methods
  • client: Now supports subscriptions when using WS
  • server: Now supports drop-in modules for API, VFS Transports, etc.
  • server: Now uses a Storage module instead of Handler class
  • server: Now uses a Authenticator module instead of Handler class
  • server-node: Entirely rewritten
  • server-php: Entirely rewritten
  • locales: Updated it_IT
  • locales: Updated fr_FR
  • build: Added better bugreport configuration support
  • build: Static build files can now be skipped if already exists
  • build: Added support for build file overlays
  • build: Now possible to pick login screen via config
  • build: Added help to the ‘osjs’ command
  • build: Updated build system
  • misc: Updated various lose documentation files in the codebase
  • misc: Grunt is no longer a main dependency
  • misc: Removed some unnesecarry dotfiles
  • misc: Updated documentation
  • misc: Updated NIX installer
  • misc: Updated eslint rules
  • misc: Cleaned up some CSS
  • misc: Updated unit tests

216 files changed, 13399 insertions(+), 11025 deletions(-)