(re-)Learning Javascript

It’s been several years since I worked full time on a javascript project and a lot has improved in that time. This post will document my journey and will hopefully contain some best practice suggestions.

Video tutorials

Some of the best information is now in video format rather than written. My favorite video bloggers include:

Setting up VSCode

I have adopted VSCode as the recommended editor for web development and am taking suggestions from the following:

Based on James’ suggestions, I have customized VSCode with:

  • Cobalt2 theme
  • ‘CascadiaCode SemiLight’ font (need to install it systemwide first)
  • turn font ligatures on
  • various settings suggested by Wesley

I have added the following extensions recommended by Kyle & James:

  • LiveServer
  • TabNine
  • Prettier
  • Code Spell Checker
  • TODO Highlight

Creating an ES Module that can be loaded by npm

First off, you have to understand the difference between ES modules and CommonJS modules:

It looks like Node is moving toward ES 6 Modules (ESM) so we will adopt that pattern. Here is a quick example of creating an npm loadable package with an ES module.

  1. Create a GitHub repository
  2. Clone; step into the directory and npm init
  3. Edit package.json to include "type": "module"
  4. Add index.js and app.js
// index.js
export default class Car {
  constructor(brand) {
    this.brand = brand;
  }
  run() {
    console.log("The %s is running...", this.brand);
  }
}

// app.js
import Car from "./myModule.js";

let mercedes = new Car("Mercedes");
console.log(mercedes);
mercedes.run();

NOTE: The package.json file must specify: "main": "index.js".

You should be able to run app.js at the command line:

% node app.js
Car { brand: 'Mercedes' }
The Mercedes is running...

Now add-commit-push to GitHub. Then create a new directory to test things. In this new directory you can install the node module with:

npm install github:your-account/your-package-name

Now you should be able to create script.js as seen below and run it with node test.js. Note that it is importing from a package rather than a file:

// test.js
import Car from "first-npm-package";

let mercedes = new Car("Mercedes");
console.log(mercedes);
mercedes.run();

Yay!!

Best practices for a modern npm package

Some examples that include scoped packages, project structure, etc .

  1. Source code should go in the src/ directory
  2. Tests should go in the tests/ direcdtory
  3. Use babel and webpack
npm i -D @babel/core babel-loader webpack webpack-cli

Use build and test scripts by including this in package.json:

"scripts": {
  "build": "webpack --mode production",
  "test": "uvu"
},

Scientific Examples

Here is one example of a statistical package built in javascript but not using ES modules. Still, it shows how a full package might be organized and documented.

Testing a Node package

I tried using Jest but things just got very complicated because of no ESM support! I couldn’t get anything to work after an hour of so I’ll bail on unit testing with Jest.

The following three testing frameworks have native ESM support:

Uvu looks to be gaining the most traction so I’ll try again with Uvu.

Install uvu as a dev dependency:

npm install uvu --save-dev

Modify package.json so that it has:

"scripts": {
  "test": "uvu"
},

Now write scripts with the normal ESM import statements.

Yay!! It works!!!

Versioning

Too simple — use npm version at the command line while in your package directory.

npm version a.b.c
# or
npm patch

Documentation with jsdoc

npx jsdoc src -r --destination docs --readme ./README.md --package ./package.json

asdf

Leave a Reply