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:
- Kyle — https://www.youtube.com/@WebDevSimplified
- James — https://www.youtube.com/@JamesQQuick
- Matija — https://www.youtube.com/@JoyofCodeDev
Javascript best practices
Here are some good summaries of modern javascript best practices:
Setting up VSCode
I have adopted VSCode as the recommended editor for web development and am taking suggestions from the following:
- Kyle — https://www.youtube.com/watch?v=VknMxAIbJj4&t=410s
- James — https://www.youtube.com/watch?v=_aWDQVxZP6A
- Wesley — https://javascript.plainenglish.io/10-visual-studio-code-extensions-you-dont-need-6f7904132a57
Based on James’ suggestions, I have customized VSCode with:
- Cobalt2 theme
- ‘CascadiaCode SemiLight’ font (need to install it systemwide first)
- https://github.com/microsoft/cascadia-code/releases
- After the download, you can open the .ttf file and click on “Install”.
- 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
- staring ideas from Kyle — https://www.youtube.com/watch?v=J4b_T-qH3BY&t=361s
- install from GitHub — https://sebhastian.com/npm-install-from-github/
First off, you have to understand the difference between ES modules and CommonJS modules:
- https://www.freecodecamp.org/news/modules-in-javascript/
- https://hacks.mozilla.org/2018/03/es-modules-a-cartoon-deep-dive/
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.
- Create a GitHub repository
- Clone; step into the directory and
npm init
- Edit
package.json
to include"type": "module"
- Add index
.js
andapp.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 .
- (Sep 2022) https://snyk.io/blog/best-practices-create-modern-npm-package/
- (Sep 2022) https://www.geeksforgeeks.org/steps-to-create-and-publish-npm-packages/
- (Apr 2021) https://whitep4nth3r.com/blog/how-to-build-test-and-release-node-module-es6/
- (Jan 2019) https://vmarchesin.medium.com/how-to-publish-a-npm-package-in-four-steps-4344ab88e852
- Source code should go in the
src/
directory - Tests should go in the
tests/
direcdtory - 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:
- ava — https://www.npmjs.com/package/ava
- Jasmine — https://www.npmjs.com/package/jasmine
- uvu — https://www.npmjs.com/package/uvu
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