Skip to content

Latest commit

 

History

History
209 lines (147 loc) · 9.94 KB

README.adoc

File metadata and controls

209 lines (147 loc) · 9.94 KB

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

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.

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

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

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

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