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.

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

Getting Started

Clone this repository:

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

Install dependencies:
```
npm install  # or yarn install
```
Build the project and run tests:
```
npm test
```
Start nginx and project’s build in the watch mode:
```
npm run start
```

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.19.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 (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.

License

This project is licensed under MIT License.

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

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

mofe23/nginx-geoip