@hapipal/hpal

中文文档
3.1.0发布于 2021/12/08MITCommonJS近 30 天下载 7138

hapi pal CLI

原始使用文档
文档目录3 节
  1. Installation
  2. Usage
  3. Commands

hpal

hapi pal CLI

Build Status Coverage Status

Lead Maintainer - Devin Ivy

hpal was designed to help you,

  • :sparkles: create new hapi projects from the pal boilerplate
  • :bouquet: generate files for routes, extensions, models, services, etc. via haute-couture
  • :books: search the hapi docs from the command line– plus many others such as joi and toys
  • :honeybee: run custom commands defined by your server's hapi plugins

Installation

It is recommended to install the hpal CLI as a dev dependency within your project, then invoke it using npx.

npm install --save-dev @hapipal/hpal
npx hpal --help

However, if you want to try the hpal CLI right now, just copy and paste this right into your terminal!

npx @hapipal/hpal docs --ver 20.0.0 h.response

Usage

The hpal CLI is intended for use with hapi v19+ and nodejs v12+ (see v2 for lower support).

Usage: hpal <command> <options>

Commands:

  hpal new <new-project-directory>
    e.g. hpal new ~/node-projects/new-pal-project

  hpal make [--asDir|--asFile] <haute-couture-item> [<item-name>]
    e.g. hpal make route create-user

  hpal docs[:<package-name>] [--ver x.y.z|ref] <docs-section> [<config-item>]
    e.g. hpal docs --ver 20.0.0 h.continue

  hpal run [--list] <cmd> [<cmd-options>]
    e.g. hpal run plugin-name:command-name


Options:

  -h, --help       show usage options
  -v, --version    show version information
  -d, --asDir      [make] creates new haute-couture item in a directory index file
  -f, --asFile     [make] creates new haute-couture item in a file
  -V, --ver        [docs] specifies the version/ref of the API docs to search for the given package
  -l, --list       [run] lists all available commands on your server

Commands

hpal new

hpal new <new-project-directory>
  e.g. hpal new ~/node-projects/new-pal-project

Clones the pal boilerplate, helps you fill-in initial details with npm init, pulls down the pal flavors, and leaves you prepared to make the first commit to your new project.

hpal make

hpal make [--asDir|--asFile] <haute-couture-item> [<item-name>]
  e.g. hpal make route create-user

Creates a new file for a haute-couture item with details ready to be filled-in. This is the best way to add a route, plugin, model, service, etc. to any project that uses haute-couture.

Relies on the presence of a .hc.js file in the project, even if it's empty, in order to determine the base directory of the plugin in which to write the file. If .hc.js contains amendments then those will be respected– in this way you can customize the behavior of hpal make per project. Projects created with hpal new are already configured to work with hpal make.

The --asDir and --asFile flags can be used to determine where the file is written. For a list item like routes, specifying --asFile (hpal make route --asFile) will create routes.js rather than routes/index.js. For a single item like auth/default, specifying --asDir (hpal make auth/default --asDir) will create auth/default/index.js rather than auth/default.js. When an optional <item-name> is specified then that will always place a file in the relevant directory with the name <item-name>.js. For example, hpal make route create-user will write the file routes/create-user.js.

In order to omit the statement to enable strict mode to the top of the generated files (per the hapi style guide), you may specify exampleUseStrict as false inside the meta property of the relevant haute-couture amendment.

hpal docs

hpal docs[:<package-name>] [--ver x.y.z|ref] <docs-section> [<config-item>]
  e.g. hpal docs --ver 20.0.0 h.continue

Searches the hapi API reference for the relevant section or configuration item then prints it formatted to the console.

:dizzy: This command can also search the API reference for any package within the pal and hapijs ecosystems by specifying <package-name>, e.g. hpal docs:toys noop or hpal docs:joi any.strip.

<docs-section> can be,

When <config-item> is also specified, the first list item within the matched <docs-section> that matches text from <config-item> will be displayed on its own. For example, hpal docs request.setUrl is a long section of the docs but hpal docs request.setUrl stripTrailingSlash contains only information relevant to the stripTrailingSlash argument.

All searches are case-insensitive.

When --ver is specified as a semver version or a git ref (branch, tag, or commit), then that version of the docs will be searched. Otherwise, when inside a project the docs for the currently installed version of the given package will be searched. When not in a project and --ver is not specified, the master branch of the package's docs will be searched.

hpal run

hpal run [--list] <cmd> [<cmd-options>]
  e.g. hpal run plugin-name:command-name

Runs the command <cmd> defined by some plugin on your hapi server. If the plugin my-plugin defines a command do-the-thing, then that command can be run with hpal run my-plugin:do-the-thing. If the plugin's name is prefixed with hpal-, then hpal- may be omitted when running the command. Plugins may also have a "default" command that can be run as hpal run my-plugin.

A list of commands available on the server and their descriptions may be viewed with hpal run --list.

Upon running a command hpal will initialize the server if it is not already initialized, then stop the server when the command exits successfully.

Requirements

In order to use hpal run, hpal must be able to find your hapi server. It will look in server.js and server/index.js relative to the root of your project. That file should export a property deployment which contains a function that returns a hapi server, or a promise for a hapi server (for example, an async function).

If you're using the pal boilerplate then you should already be all set!

Here is a very basic example,

// server/index.js
const Hapi = require('hapi');
const AppPlugin = require('../app');

exports.deployment = async ({ start } = {}) => {

    const server = Hapi.server();

    await server.register(AppPlugin);

    if (start) {
        await server.start();
    }

    return server;
};

// Start the server only when this file is
// run directly from the CLI, i.e. "node ./server"

if (!module.parent) {
    exports.deployment({ start: true });
}
Creating your own commands

Any hapi plugin can create commands that are runnable with hpal run! Commands are exposed to hpal using hapi's server.expose(). Inside your plugin my-plugin simply call server.expose('commands', commands), where commands is an object,

  • whose keys are command names. The name default is reserved for the command hpal run my-plugin. Camel-cased command names are converted to kebab-case, so if the key is someCommand then it is run using hpal run my-plugin:some-command.
  • whose values are either objects { command, description } or functions command where,
    • command - a function with the signature async function(server, args, root, ctx).
      • server - the initialized hapi server.
      • args - an array of all the command's CLI arguments. For example, running hpal run my-plugin --custom-flag value will result in args being ['--custom-flag', 'value'].
      • root - an absolute path to the project's root directory.
      • ctx - a context object containing some hpal internals that may be useful during testing, plus some public helpers. The following are public:
        • colors - an object with functions for basic formatting of CLI output with colors and styles: colors.green(str), colors.yellow(str), colors.red(str), colors.grey(str), and colors.bold(str). When the CLI does not support color, these functions take no effect.
        • DisplayError - a class that can be used to indicate a "safe" failure to hpal. Throwing a DisplayError will output the error's message and exit the process with code 1, but not display a stack trace as would happen with an unexpected error.
    • description - a string description of the command displayed by hpal run --list. May alternatively be a function with signature function (ctx) that receives ctx as described above and returns a string description.

For example, here is a plugin that creates a command to display the server's route table,

// hpal run route-table:show

module.exports = {
    name: 'hpal-route-table', // The hpal- prefix is ignored when running the command
    register(server) {

        server.expose('commands', {
            show(srv) {

                console.log('Route table:');

                srv.table().forEach(({ method, path }) => {

                    console.log(`  ${method} ${path}`);
                });
            }
        });
    }
};

版本与发布记录

@hapipal/hpal 共发布 2 个版本,首次发布于 2020/12/14;过去 12 个月发布了 0 个版本。

版本发布日期距今
3.1.0latest2021/12/084 年前
3.0.02020/12/145 年前

关于 @hapipal/hpal 的常见问题

@hapipal/hpal 是什么?

hapi pal CLI

如何安装 @hapipal/hpal?

在项目目录运行 npm install @hapipal/hpal,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 hpal,可以用 npx hpal 直接运行。

@hapipal/hpal 支持 TypeScript 吗?

该包的 package.json 没有声明类型入口。需要类型提示时,可以在 npm 上查找社区维护的 @types/hapipal__hpal 是否存在。

@hapipal/hpal 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@hapipal/hpal 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=12。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@hapipal/hpal 可以商用吗?

@hapipal/hpal 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@hapipal/hpal 的下载量有多少?

根据 npm 官方下载统计,@hapipal/hpal 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,138 次,日均约 238 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@hapipal/hpal 还在维护吗?

最新版本 3.1.0 发布于 2021/12/08(4 年前);至今共发布 2 个版本,其中过去 12 个月发布了 0 个;首次发布于 2020/12/14。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。