Creating a JavaScript Library for your Shiny Application

Ashley Baldry

Shiny & JavaScript

• {shiny} + JS = ❤️
• tags$script(HTML("
    $(document).ready(function() {
        $('[data-toggle="tooltip"]').tooltip()
    })
"))
• tags$script(src="custom.js")
• Shiny.inputBindings.register(inputBinding, "your.inputBinding")
• 🤷

• JavaScript can easily be included into shiny applications to enhance the capabilities already present within shiny
• Adding your first custom JavaScript feels like a massive milestone, and as you try out different JavaScript commands, you start adding more to your shiny application
• Then you write enough to add it into its own separate script
• Eventually you get comfortable enough to create custom inputs and outputs for shiny application in JavaScript, and the codebase continues to grow
• But what is the next step after that?

Motivation

Demo of the {designer} application

• Why I needed to learn to create a JavaScript library
• This is the application within the designer package. It allows a code-free way to template the UI of shiny applications.

Motivation

Structure of the JavaScript code in the {designer} package for version 0.1.0

• Adding more components would make the code harder to read
• Lots of duplicated code that could be simplified

• In the initial release of the designer package, there are 4 JavaScript files:
  • Three that are between 50 and 100 lines
    • A custom input for the content of the template (canvas-page-input.js)
    • Behaviour to trigger on application load (designer-app-setup.js)
    • Helper functions for the initial set-up (designer-app-utils.js)
  • The fourth (create-element.js) is 650 lines - most amount of JS I’ve written
    • How to create each type of component
• In the second iteration I was including some bs4Dash components to the application, and adding them to that file was becoming unmanageable
• Most of the code in that file was functionality about adding a new draggable element that was copying and pasting code from other components

JavaScript Library

Library Set-Up

• Choose your IDE of choice
• Create a directory in your project for JS code
  • Standard name: srcjs
  • If included in an R package, add folder to .Rbuildignore
• Download and install Node.js
• Open srcjs directory up in your IDE
• Run npm init in the terminal and initialise your project

• (IDE) In R, we tend to have one or two products/packages that are much more salient and well used for any given task. JS tends to have at least 10 of anything you want to use - so it’s always useful to search for “top x in JavaScript” for some listicles
• Personally like VS Code, it comes with loads of extensions that help with developing JavaScript (formatting, snippets, linting), plus the debugging functionality is particularly nice to use
• “src” stands for “source”
• If you are including the application in the package then it won’t need to be included in the published version of the package
• Node is the runtime for JavaScript, it allows to run JavaScript code without having to be in a browser. It is much more powerful than that, it includes npm, a package manager to install all the required dependencies for your JS code

Library Set-Up

Running npm init in VS Code

• npm init will ask a series of questions around the package like name, version and description. It will add this all into the package.json file
• The package.json file is the JS version of the description file
• Two key differences:
  • “main” is the entry point of the library. It is a single file where all of exported code is available to call or run.
• “scripts” is a list of commands that can be used in the terminal
  • Run by calling npm run test
    • Dependency package commands can be used, or node file.js to run like Rscript file.R
    • One of the options that is asked when running npm init is the testing command.
• Anything defined in this list can be performed in the terminal with the prefix “node”
• Speaking of dependencies…

Dependency Management

• Node.js includes a package manager, npm, within its installation
  • This works like {renv}, including a lock file within the project
• Include shiny and jQuery as dependencies
  • npm install github:rstudio/shiny
  • npm install @types/jquery@3.5.14
• Project specific dependencies can also be added here

Important

Create a .gitignore in your JavaScript directory and include node_modules

Unlike renv, npm doesn’t cache the dependencies, it adds them all within the node_modules sub-directory. Unless you want to add all these files on your remote Git repository, add this file to your gitignore at the first opportunity

The shiny repository has the package.json in the top level of the repository, making it easy for us to grab the JavaScript part of it through npm install. This helps us not have issues with using the Shiny object for custom messages and sending input values to the UI within our own JavaScript

Baked into shiny, so they are used for development process

Specifying the version of jQuery so that it matches the version available in shiny. The types refers to TypeScript

Mention that additional libraries can be installed with npm install

Twice I’ve contributed to packages with JavaScript and twice we’ve forgotten to include this file.

Dependency Management

JS library structure after installing required dependencies

You can now see the dependencies specified within the package.json file

Heavily dependent on sortable js in my project, so included as a dependency

Bundling/Minifying Code

import { build } from 'esbuild'

build({
  entryPoints: ['index.js'],
  bundle: true,
  sourcemap: true,
  outfile: '../inst/app/www/designer.min.js',
  platform: 'node',
  minify: true
}).catch(
  () => process.exit(1)
)

• npm install esbuild --save-dev
  • --save-dev only includes package for development purposes
• Include a source map to help debug errors in console

As a start, we can add all the code in the scripts into a single index.js file.

Several bundlers available, however when searching found that esbuild is significantly quicker, and have rarely seen it take longer than 0.5 seconds to bundle my JavaScript code.

Save dev is an option that will add the library to a development dependency, sort of like a Suggets in the DESCRIPTION, but this will never need to be installed by the end user.

The minifying will reduce all variable names you set into single letters. This makes it really hard to know what is going on in the console when debugging shiny applications. By including a source map you can at least see what code is being run when it errors. Alternatively include a build option that doesn’t minify the code.

Bundling/Minifying Code

JS library structure after installing bundling library

Might notice the “type” option added to the package.json file. This is required for esbuild to bundle up the JS code.

Linting

• Linting helps improve code quality and consistency
• npm install eslint --save-dev
  • Extension in VS Code that applies the eslint linting standards
  • Customisable by adding own rules into .eslintrc.yml

Big believer that all projects should include linting from the offset Lints in JS that wasn’t aware of before: - No longer requiring “;” at the end of calls

Linting

JS library structure after installing linting

Communication Between Files

• JavaScript files work in a modular fashion
• Only exported objects are accessible in other modules
• Objects have to be explicitly imported before use
• Add "type": "module" to package.json to enable import to work

// component/component.js
export class Component {
  html = '<div></div>'
  constructor () {
    // runs when class is created
  }
  
  createComponent () {
    return this.html
  }
}

// component/button.js
import {Component} from './Component'

class Button extends Component {
  html = '<button ...>...</button>'
  constructor () {
    // runs Component constructor
    super()
  }
}

R is one of the few languages where the location of a file in a package doesn’t matter, it is all bundled into a single namespace. JavaScript assumes that nothing has been imported in the script, so any call to another function object will result in an error.

If you’ve ever used the {box} package (one of the dependencies of the {rhino} application infrastructure) then it is similar in how it works.

Whilst this might cause some time to split out your JavaScript into several files and reference using import/export methods will make it a lot easier to manage your code in the long run.

If you want to use the import calls, then you will need to add the type field to the package.json file in order for it to bundle

Class Inheritance

• A way to reduce duplicated code
• Extremely useful when creating 20+ components
  • Component class contains several methods accessible to individual components
  • Overwrite methods when needed

// component/component.js
export class Component {
  html = '<div></div>'
  constructor () {
    // runs when class is created
  }
  
  createComponent () {
    return this.html
  }
}

// component/button.js
import {Component} from './Component'

class Button extends Component {
  html = '<button ...>...</button>'
  constructor () {
    // runs Component constructor
    super()
  }
}

• R is predominantly a functional language
• Most programming languages, including JavaScript, are more object orientated - similar to how {R6} works
• Use class inheritance to avoid the repeating code to create the different UI components in the designer application
• Component class included methods to generate random IDs, or validating the CSS unit string
• Also included the method to initialise the dragging behaviour from sortable JS
• Usually overwrote a method that created the the HTML, as most components have options that can be set by the user

Other things that I have used the inheritance

Library Structure

JS library structure after modularising code

Unit Testing

• Many testing frameworks available in JS
• Jest has similar structure to {testthat}
  • Add tests to __tests__ directory
  • Suffix filename with .test.js
• npm install --save-dev jest
• npm install --save-dev @babel/plugin-transform-modules-commonjs
  • Required to run tests using modular format

Many different testing frameworks available in JavaScript, each with their own syntaxes Using Jest as was recommended due to it having a very similar structure as {testthat} Define the test name in the first argument, then run the test in the second. Individual tests used as expect().to() Other unit testing packages include MochaJS, ChaiJS and Cypress.io

Unit Testing

// component/button.js
import Component from 'Component'

class Button extends Component {
  html = '<button ...>...</button>'
  constructor = {
    // runs Component constructor
    super()
  }
}

// component/__tests__/Button.test.js
import { Button } from '../Button'

test('sanity test - button constructs successfully', () => {
  const button = new Button()
  expect(button.html).toBe('<button ...>...</button>')
})

Unit Testing

Running npm run test in VS Code

Continuous Integration (CI)

Include JavaScript unit tests as part of your GitHub Actions

name: Run JS Tests (Jest)
on:
  push:
    branches: [dev, main]
  pull_request:
    branches: [dev, main]
defaults:
  run:
    working-directory: srcjs
jobs:
  js-unit-tests:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Install modules
      run: npm install
    - name: Run tests
      run: npm run test 

I have found when running unit tests through GH actions that certain JS libraries are pre-installed on the build servers, so no steps are required prior to installing the dependencies for your own JavaScript code.

The whole process takes little over a minute

CI Results

JavaScript unit test results of the {designer} package

Test Suites: 32 passed, 32 total
Tests:       38 passed, 38 total
Snapshots:   0 total
Time:        5.948 s
Ran all test suites.
Done in 6.82s.

Finished Result

Structure of JavaScript code of the {designer} package

Finished Result

Minified JavaScript file in the dev branch of the {designer} package

Q&A.