Node's Pastoral Musicians


    1.2.1 • Public • Published


    soundworks plugin to parse and watch directories and distribute their contents to all clients in real-time.

    Table of Contents


    npm install @soundworks/plugin-filesystem --save


    A working example can be found in the repository.


    Server installation

    Registering the plugin

    // index.js
    import { Server } from '@soundworks/core/server';
    import pluginFilesystemFactory from '@soundworks/plugin-filesystem/server';
    const server = new Server();
    server.pluginManager.register('filesystem', pluginFilesystemFactory, {
      directories: [{
        // key at which the file tree will be accessible
        name: 'my-name',
        // path to the watched directory, can be relative to process.cwd()
        // or absolute, in all cases file paths in the tree will be normalized
        // to be relative to `process.cwd()`
        path: 'path/to/directory',
        // if defined, add an `url` to each tree node, that defines the
        // route at which the files will be publicly accessible.
        publicDirectory: '',
    }, []);

    Requiring the plugin

    // MyExperience.js
    import { AbstractExperience } from '@soundworks/core/server';
    class MyExperience extends AbstractExperience {
      constructor(server, clientType) {
        super(server, clientType);
        // require plugin in the experience
        this.filesystem = this.require('filesystem');

    Client installation

    Registering the plugin

    // index.js
    import { Client } from '@soundworks/core/client';
    import pluginFilesystemFactory from '@soundworks/plugin-filesystem/client';
    const client = new Client();
    client.pluginManager.register('filesystem', pluginFilesystemFactory, {}, []);

    Requiring the plugin

    // MyExperience.js
    import { Experience } from '@soundworks/core/client';
    class MyExperience extends Experience {
      constructor(client) {
        // require plugin in the experience
        this.filesystem = this.require('filesystem');

    Getting current values and subscribing to changes

    The following API is the same on the client as well as the server side:

    // get the current values of all registered directories
    const trees = this.filesystem.getValues();
    for (let name in trees) {
      const tree = trees[name];
      console.log(name, tree);
    // or get a single tree
    const tree = this.filesystem.get(name);
    // be notified when a change occurs in a watched filesystem
    this.filesystem.subscribe(updates => {
      for (let name in updates) {
        const tree = updates[name];
        console.log(name, tree);

    Uploading and deleting file from a client

    The plugin allows you to upload and delete files directly from a client

    const files = {
      'a.txt': fileA,
      'b.json': fileB,
    // This uploads the files to the first registered directory
    // This uploads the files to the directory registered with the name `dir`
    this.filesystem.upload(dir, files); 
    // Similarly to delete a file 
    this.filesystem.delete(dir, filename);

    File tree format

    The plugin is built on top of the node-directory-tree library and therefore follows the format described here. The only addition to the format is the addition of a url field on each node to simplify the access of the resources for the clients.

    Routing and publicDirectory option

    The publicDirectory option allows to create an valid url from the filesystem paths. It can be use in conjunction with server.router.use to open specific routes for static assets.

    For example, let's consider a case where you watch the directory /misc/audio but want to publicly access the audio files through http://my.domain/audio/*.wav. You can do the following:

    // server/index.js
    server.router.use('audio', serveStatic('misc/audio'));
    server.pluginManager.register('filesystem', pluginFilesystemFactory, {
      // default to `.data/scripts`
      directories: [{
          name: 'audio-files',
          path: 'misc/audio,
          publicDirectory: 'audio',
    }, []);

    Note that if publicDirectory is not defined in the configuration object, the url field won't be added to the nodes of the tree.

    Watching a directory outside the project

    The plugin and url strategy described above should even work with directories located at arbitrary locations in your file system.


    The code has been initiated in the framework of the WAVE and CoSiMa research projects, funded by the French National Research Agency (ANR).






    npm i @soundworks/plugin-filesystem

    DownloadsWeekly Downloads






    Unpacked Size

    19.4 kB

    Total Files


    Last publish


    • b-ma