README.adoc

Njs TypeScript Starter

A full-featured starting template for developing njs (NGINX JavaScript) scripts for NGINX server in TypeScript.

This template uses Babel and Rollup to compile TypeScript sources into a single JavaScript file for njs and Mocha with nginx-testing for running integration tests against NGINX sever.

Table of Contents

• Pre-requisites
• Getting Started
• Project Structure
• Build Scripts
• Dependencies
• License

Pre-requisites

To build and run this project locally you will need:

• Linux system ^[1], macOS ^[2] or Windows Subsystem for Linux (WSL) ^[3]

• Node.js 18.12 or newer

• npm (distributed with Node.js) or yarn

NOTE: You do not need Docker or other containerization tool for developing and testing njs scripts on Linux and macOS! See nginx-testing for more information.

Getting Started

1. Clone this repository:

   git clone --depth=1 https://github.com/jirutka/njs-typescript-starter.git <project-name>
   cd <project-name>

2. Install dependencies:

   npm install  # or yarn install

3. Build the project and run tests:

   npm test

4. Start nginx and project’s build in the watch mode:

   npm run start

5. Open http://127.0.0.1:8090/hello in the browser and now you should see the output of src/hello.ts:

       Meow, world!
   
           ("`-''-/").___..--''"`-._
           `6_ 6  )   `-.  (     ).`-.__.`)
           (_Y_.)'  ._   )  `._ `. ``-..-'
         _..`--'_..-_/  /--'_.' ,'
         (il),-''  (li),'  ((!.-'

At least before publication of your project (e.g. on GitHub), do the following:

• Change name, version, description, author, license (if you prefer a license other than MIT), homepage, bugs, and repository fields in package.json to reflect your project.

• Add your name to LICENSE and/or change the license text if you prefer a license other than MIT. You don’t have to keep my name in the license.

• Replace this README file. If you prefer Markdown to AsciiDoc, replace this file with README.md and remove scripts.prepublishOnly from package.json.

Project Structure

Files and directory structure of the project.

Path	Description
.github/workflows/	Contains GitHub Actions workflows.
dist/	Contains the built JavaScript file for NGINX’s JS module.
integration‑tests	Contains your integration tests.
lib/	Contains type declarations generated from TypeScript sources in src/ directory.
node_modules/	Contains all your npm dependencies.
src/	Contains your source code that will be compiled to the dist/ directory.
src/tsconfig.json	Config settings for type checking your TypeScript source code that will be compiled for njs.
.editorconfig	Defines very basic code style used in the project. See editorconfig.org for more information.
.eslintrc.js	ESLint config for linting your TypeScript and JavaScript files.
.mocharc.js	Mocha config for integration tests.
babel.config.js	Babel config for compiling TypeScript sources into plain JavaScript compatible with njs and Node.js.
package.json	File that contains npm dependencies as well as build scripts.
package‑lock.json	Describes the exact dependency tree that was generated, including exact versions and checksums of the installed packages. This file is automatically generated by npm when you run e.g. npm install. (read more…)
rollup.config.js	Rollup config for compiling and bundling your source code in src/ together with the dependencies into a single JavaScript file for NGINX JS module.
tsconfig.json	Config settings for type checking code written in TypeScript or JavaScript that will be executed by Node.js (i.e. integration tests and JS configs).
yarn.lock	If you use yarn instead of npm; this file has the same purpose as package-lock.json for npm.

NOTE: Some of the files and directories will be created after installing dependencies or building the project.

Build Scripts

All the build steps are orchestrated via npm scripts. Npm scripts basically allow us to call (and chain) terminal commands via npm. If you open package.json, you will see a scripts section with all the different scripts you can call. To call a script, simply run npm run <script-name> (or yarn <script-name>) from the command line.

Below is a list of all the scripts this template has available:

Npm Script	Description
build	Compiles and bundles all source .ts files together with their dependencies into a single .js file in the dist directory.
clean	Cleans dist, lib, and node_modules/.cache directories.
lint	Runs both lint:eslint and lint:types in parallel.
lint:eslint	Runs ESLint linter on project files.
lint:types	Runs TypeScript type checker on project files.
start	Runs start-nginx and watch in parallel.
start‑nginx	Starts nginx 1.24.x on port 8090 with config integration-tests/nginx.conf and reloads it on each change of the config file and files in dist/.
test	Runs all tests in the integration-tests directory using Mocha test runner.
watch	Same as build but continuously watches project’s .ts files and re-compiles when needed.

Dependencies

Project’s dependencies are specified in file package.json, sections dependencies (runtime dependencies) and devDependencies (build-time dependencies). They are managed by npm or yarn.

The following is a list of devDependencies with their description.

• typescript — TypeScript compiler and type checker. Used for type checking the TypeScript sources.

  • njs-types — TypeScript type definitions for njs.

  • @types/* — Packages that provide TypeScript types.

• @babel/core — A Babel compiler core. Babel is used to compile TypeScript sources into plain JavaScript compatible with njs and Node.js.

  • babel-preset-njs — A Babel preset for transforming JavaScript code with modern language features into code compatible with njs.

  • @babel/preset-typescript — A Babel preset to transform TypeScript code into plain JavaScript. It basically just strips the type annotations.

  • @babel/plugin-transform-modules-commonjs — A Babel plugin to transform ES2015 modules into CommonJS modules. Used for running integration tests with Node.js.

  • @babel/register — A Babel require hook. Used for Mocha integration with TypeScript.

  • babel-register-ts — A @babel/register wrapper with additional .ts and .tsx extensions. Used for Mocha integration with TypeScript.

• rollup — A module bundler for JavaScript which compiles small pieces of code into a single JavaScript file.

  • @rollup/plugin-babel — A Rollup plugin for seamless integration between Rollup and Babel.

  • @rollup/plugin-commonjs — A Rollup plugin to convert CommonJS modules to ES6, so they can be included in a Rollup bundle.

  • @rollup/plugin-node-resolve — A Rollup plugin which locates modules using the Node resolution algorithm, for using third party modules in node_modules.

  • rollup-plugin-add-git-msg — A Rollup plugin that inserts git tag, commit hash, build date and copyright at top of the generated JS bundle.

• mocha — A flexible JavaScript test framework for Node.js.

  • mocha-suite-hooks — Suite-level hooks for Mocha; allows to run hook before/after describe block.

• nginx-testing — Support for integration/acceptance testing of nginx configuration.

• got — A human-friendly and powerful HTTP request library for Node.js. Used in integration tests. Do not update it to version 12.x (see #3)!

• eslint — ESLint is a tool for identifying and reporting on patterns found in JavaScript and TypeScript code.

  • @typescript-eslint/eslint-plugin — A TypeScript plugin for ESLint.

  • @typescript-eslint/parser — An ESLint parser which leverages TypeScript ESTree to allow for ESLint to lint TypeScript source code.

• npm-run-all — A CLI tool to run multiple npm-scripts in parallel or sequential. Used in npm scripts.

License

This project is licensed under MIT License.

---

1. It should work on any recent Linux distribution for x86_64, aarch64, or ppc64le architecture.

2. I’m not sure what is the lowest version you need. It should work both on Intel and M1.

3. njs doesn’t support Windows, so integration tests won’t run on Windows out of the box. If you’re stuck with Windows, WSL is the easiest way to go.