cli.md

Command Line Interface

Installing nhp makes the nhp executable available to npm scripts and package-manager command shims.

Syntax

nhp [-j|--js|--module] <input.nhp> [output.html|output.js]

Compiling to HTML

When run without JavaScript output flags, nhp compiles and renders the template to static HTML:

nhp views/index.nhp
# writes views/index.html

nhp views/index.nhp public/index.html
# writes public/index.html

Compiling to JavaScript Node.js Modules

Use -j, --js, or --module to precompile an .nhp file into a standalone JavaScript Node.js module:

nhp -j views/page.nhp
# writes views/page.js

nhp --js views/page.nhp dist/page.js
# writes dist/page.js

When no output path is given with -j / --js / --module, NHP replaces .nhp with .js alongside the input file.

Using compiled modules in Node.js

Other Node.js modules and projects can require() the compiled JavaScript file directly:

const renderPage = require("./dist/page.js");

// Render to string (callback or Promise)
renderPage({ title: "My Page", user: "Alice" }, (err, html) => {
    if (err) throw err;
    console.log(html);
});

// Promise support
const html = await renderPage({ title: "My Page" });

// Render to stream
await renderPage.renderToStream({ title: "My Page" }, responseStream);

// Access detected variables or underlying template
console.log(renderPage.variables); // ['title', 'user']

Compiled modules are self-contained: renderPage(locals) and renderPage.renderToStream(locals, stream) build their own minimal render context from locals and do not require "nhp" to run. nhp is only lazily required, and only when one of these features is actually used at runtime:

• renderPage.createTemplate(nhp?, options?) — builds a full Template instance (file watching, caching, etc.) instead of the lightweight self-contained renderer.
• A dynamic <?include expression?> whose file isn't a plain string literal. Includes with a literal path (e.g. <?include "partials/header"?>) are inlined into the compiled module at compile time and never touch nhp.
• A named resolver moustache, e.g. {{#currentUser}}, since resolvers are registered on an NHP instance via installResolver().

Pass an existing instance with renderPage(locals, { nhp }) (or renderPage.renderToStream(locals, stream, { nhp })) to reuse its constants and registered resolvers instead of lazily creating a bare one.

This means nhp can be listed as a devDependency of the project that compiles templates, as long as it remains an installed dependency (direct or transitive) wherever the compiled module actually needs one of the features above at runtime.

The command creates missing parent directories for the output path. It prints the resolved output path on success and exits with status 1 after writing an error to stderr on failure.

Package scripts

For a project dependency, npm automatically exposes the binary in scripts:

{
  "scripts": {
    "build:html": "nhp src/pages/home.nhp dist/home.html",
    "build:templates": "nhp -j src/pages/home.nhp dist/home.js"
  }
}

Run it with:

npm run build:templates

Rendering context

When compiling directly to HTML, the CLI executes with an empty render context. Values that rely on application locals are undefined unless the template provides a fallback expression.

When compiled to JavaScript modules with -j / --js / --module, dynamic render locals can be passed to the exported render function at runtime in Node.js. See Getting started and API reference.