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.

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

To build and run this project locally you will need:

• Linux system ^[1], macOS ^[2], or Windows 10+ (x64)

• Node.js 14.15 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! See nginx-testing for more information.

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.

Files and directory structure of the project.

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

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:

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 (recommended).

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.

• power-assert — “Power Assert” in JavaScript. Provides descriptive assertion messages through standard assert interface.

  • babel-plugin-empower-assert — A Babel plugin to convert assert to power-assert at compile time.

  • babel-plugin-espower — A Babel plugin for power-assert.

• 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.

• 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.

• rimraf — A deep deletion module for node (like rm -rf). Used in npm scripts.

This project is licensed under MIT License.