Understanding the directory structure


Hi All,

This post explains a few aspects of the directory structure of OS.js.

The codebase is split up into these parts:

Server Source

You can find all the server code in src/server where there are currently two available services: php and node.

These are webservers running simply to serve files and provide APIs to the underlying system.

Client Source

The client code is stored in src/client and split into three categories:

  • javascript
    All client source code, split up into modules.
  • dialogs
    Contains all the dialog implementations
  • gui
    Contains all the GUI element implementations
  • handlers
    Contains all the Handlers
  • helpers
    A collection of helper libraries to ease development. Has some useful third party stuff.
  • locales
    All translations for the core
  • utils
    All global utility methods and functions
  • vfs
    All VFS modules, mounts and transports
  • stylesheets
    All the base stylesheets.
  • core.css
    Contains the basic boilerplate for basic UI, like splash screens and windows
  • gui.css
    Contains the boilerplate for OS.js GUI.
  • theme.less
    This is the base file used in compilation of styles (themes).
  • themes
  • fonts
    Font theme packs
  • icons
    Icon theme packs
  • sounds
    Sound theme packs
  • styles
    Style theme packs
  • wallpapers
    Wallpaper images

Package Sources

Packages are provided by “repositories”, which are stored in src/packages/<repo>/<package>. A package consists of these files (depends on what type of package):

  • metadata.json - Build information and metadata about this package
  • main.js - The client javascript file
  • main.css - The client stylesheet file
  • api.js - The Node javascript file, for custom server Application API

Configuration Files

Configuration files are stored in src/conf. These files are all merged together to form one configuration object, hence the numbered prefix. This ensures they are loaded in the correct order.

The file 900-custom.json is generated by Grunt when you do changes. It is higly recommended that you use this file instead of making changes to the files provided by the codebase.


OS.js comes with a custom build system with built-in tools. It uses Grunt as the CLI.

Some of the tasks (like create-package), uses files from src/templates as templates to generate files, configurations etc.

You can find the build system source in src/build.js (yeah, it needs a spring cleanup).


There are two different build directories in OS.js.These are the “base directories” served by the webserver(s).

You can customize the builds using configuration files, like branding and adding of custom scripts and resources.

  • index.html - The main HTML document that contains sorces
  • blank.css - Just a blank CSS document
  • packages.js - All package metadata files, collected in one manifest
  • settings.js - All the client configuration entries
  • dialogs.html - All the dialog Scheme files (dist only)
  • locales.js - All the locales (dist only)
  • osjs.js - OS.js Core javascript (dist only)
  • osjs.css - OS.js Core stylesheet (dist only)
  • splash.png - The splash screen image
  • vendor - All third party libraries
  • themes - Built themes
  • packages - Packages


This is not exactly a build directory, per-se, but rather a directory containing symlinks to the original source-code in src/client and src/packages.

This is useful if you’re developing or testing changes since you don’t have to run any build scripts etc. to view your changes.


This is the “production build” of OS.js It consist of a concatenated version (which can also be compressed) of src/client and src/packages.

With correctly configured package manifest files, this directory will be scrubbed of any unwanted files (like docs, vendor blob etc).

This makes it suitable for running in production environments and to make custom builds for deployment on devices (like Arduino or Raspi).


  • bin - A collection of shellscripts for developers and deployers
  • doc - A collection of documents for installation and general setup
  • src/gfx - Source files of logos and misc documentation stuff
  • src/installer Source-code of the automatic OS.js installers
  • src/x11-launcher - X11 launcher source-code
  • vfs - Default directory for storing files in the VFS (Like user directories)

Ref: https://os.js.org/doc/manuals/man-build-grunt.html