This article will walk you through the development process of OS.js modules and packages.

  1. Introduction
    1. Webpack
    2. Docker
    3. Testing
  2. Bulding
    1. Environment
    2. Server
  3. Naming
  4. Modules
    1. Replacement
    2. Linking
  5. Packages
    1. Next steps
  6. Contributing
  7. Publishing
    1. npm
    2. git

For prototyping solutions you can use the following templates for online development environments:


Before beginning read the overview article. You also need to familiarize yourself with the following technologies:


OS.js uses Webpack 4 for building and bundling by default with Babel 7 and Sass CSS.

These are some of the plugins and loaders used throughout codebases:


If you're using Docker, you do your work normally on the local filesystem, but when performing commands and tasks related to building and dependency management, you have to run them within the context of the container:

# Watch for changes
docker-compose exec osjs npm run watch


Use the provided .eslintrc and .stylelint files to keep consistent code styles.

All official packages provides running one or more of these tasks:

  • npm run eslint - ESLint pass
  • npm run stylelint - Stylelint pass
  • npm run test - Jest unit tests


All official packages provides running one or more of these tasks:

  • npm run build Build changes once
  • npm run watch Watch and build changes automatically

As described above, building is done using Webpack.


Using the required tools (above) you can set up a development environment in a couple of minutes.

Make sure to set the NODE_ENV=production environmental variable if you're compiling for a production environment.

By default the configurations are set to development mode, which will reload your applications and stylesheets whenever the distribution is rebuilt.


You can launch the server with nodemon to automatically reload upon changes as the npm run watch tasks does not apply here.


OS.js has a format for naming projects:

  • osjs-<project>-application - Application package
  • osjs-<project>-provider - Service Provider module
  • osjs-<project>-auth - Authentication adapter
  • osjs-<project>-settings - Settings storage adapter
  • osjs-<project>-adapter - VFS Adapters
  • osjs-<project>-theme - Theme package
  • osjs-<project>-icons - Icons package
  • osjs-<project>-sounds - Sounds package
  • osjs-<project>-cli - CLI Plugin
  • osjs-<project> - Core modules

Official projects are scoped with @osjs/<project>-<suffix>.


The OS.js client and server are split up into several modules provided by npm packages (see package.json).

You can place your own modules inside the src/ if you don't want to work with npm.

To make your own module(s), you can use the CLI Wizard:

If you want to modify the official modules (which are installed via npm) you have two choices which are explained in detail below:

  1. Replace the module by checking out local source-code
  2. Override module with local source-code using npm link


Your first option is to simply replace the import statements in your bootstrap scripts.


# In your OS.js installation
cd src/
git clone
cd osjs-client
npm install
// In `src/client/index.js` replace this:
import {/* some code here */} from '@osjs/client';

// With:
import {/* some code here */} from '../osjs-client/index.js';


With the npm link feature you override the paths in node_modules/ and link them to the actual source-code instead of the distributed builds.

[warning] It is highly recommended that you either manage your node installation with nvm or modify you npm setup to prevent permission errors when using the npm link feature.

Assuming you've already installed OS.js, this is an example of how you set up linking:

# Somewhere in your filesystem (or use src/ directory)

# First check out the code of package @osjs/client
git clone
cd osjs-client

# Install required dependencies
npm install

# Build source (or `npm run watch` in while developing to automatically rebuild)
npm run build

# Then register the package in npm
npm link

# In your OS.js root directory

# Subscribe to the npm registered package
npm link @osjs/client


  1. Using npm link will not link its dependencies. You have to do this yourself or use a monorepo uitlity to automate the process.
  2. Running npm install after linking will remove the links


By default, the packages provided by the OS.js repository are installed via npm (node_modules/), but the directory src/packages can also be used. To set up custom package discovery paths, see CLI Guide.

Packages installed in node_modules/ always have the lowest priority, and discovery paths are prioritized by their order. This way you can replace officially installed packages without removing them from package.json.

Run npm run make:application to create a new application package package from a wizard using the standard template:

Theme templates currently not provided, use the theme repositories a starting point. Note that you have to manually install the dependencies and build the package afterwards.

npm run make:application
npm run package:discover


  1. Each time you add/remove (or modify the metadata) a package you need to run npm run package:discover to update the global package manifest.
  2. Package name must be unique.
  3. The package:discover task creates a file named packages.json and creates symlinks inside the dist/{apps|themes} directories to {package}/dist.
  4. OS.js expects you to output your bundles etc. in a directory called dist/ (which is default in Webpack).

Next steps

Now that you have your package set up, look at the Tutorial section in the menu on how to proceed with implementing features.

If you're developing an application, these are the relevant articles in order:

  1. Core Tutorial
  2. Application Tutorial
  3. Window Tutorial
  4. GUI Tutorial


Using the documentation above, you have everything you need to make changes.

[info] To submit changes into the official repositories need a github account.

This is the basic workflow for making submissions:

  • Fork the repository you want to make changes to
  • Clone repository
  • Create a new branch (from up-to-date master)
  • Test your work (see above)
  • Commit your work
  • Create a pull request

It is important to write good commit messages, having a clean git history and using the provided linter configurations. This saves a lot of time when reviewing the work and things gets merged faster.


It is recommended that you distribute your modules and packages in a compiled form.

The official npm packages does this and delivers the files in a dist/ directory.

Using NODE_ENV=production is recommended to avoid bloat and allow for proper tree-shaking, etc.

You can distribute the sources in addition, but it all depends on the target (ES vs commonjs etc).


This is a typical setup of package.json that distributes only the runtime files and metadata.

  "scripts": {
    "build": "webpack",
    "watch": "webpack --watch",
    "test": "jest",
    "eslint": "eslint *.js",
    "stylelint": "stylelint index.scss src/**/*.scss",
    "prepublishOnly": "npm run test && npm run eslint && npm run stylelint && rm ./dist/* && NODE_ENV=production npm run build"

  "files": [

  // These are not required for packages
  "main": "dist/main.js",
  "style": "dist/main.css"

This ensures that all your tests are valid before you publish your final pack.

You can run tar tvf $(npm pack) to confirm what files are published before actually running npm publish.


You can also distribute via git, where everything in the npm section above still applies.

A disadvantage using git for deployment is that you have to create a specific branch to avoid users downloading unwanted files and sources.

results matching ""

    No results matching ""