The .nextwebrc file

.nextwebrc tells pkg create how to build a folder into a package, and tells pkg validate what to check. It is a JSON file at the root of the application's folder. The package's name and version come from the command line, pkg create <name> <version>, never from this file.

When the folder has no .nextwebrc, pkg create writes a starter one from what it finds there and stops, so we can review it before anything is built. For the Node.js application in the Package lesson it wrote:

{
  "type": "application",
  "distribution": "internal",
  "runtime": "node",
  "site": {
    "entry": "app.js",
    "verify": {
      "path": "/",
      "statusCode": 200
    }
  },
  "encrypt": {
    "source": []
  },
  "validate": {
    "endpoints": [
      {
        "path": "/",
        "status": 200
      }
    ]
  }
}

A field Nextweb does not know is refused, so a typo is an error and not a setting that is quietly ignored.

Fields

hooks, commands, and verification are for Nextweb's own packages. A package built for an account cannot carry install hooks yet: pkg create refuses a build whose files include a hooks/ folder of scripts.

site

"site": {
  "entry": "app.js",
  "verify": { "path": "/health", "statusCode": 200, "marker": "ok" }
}

• entry is a path inside the folder. Nextweb runs it as the main module; Your application on Nextweb says what it is given.
• verify.path starts with /. statusCode is the status it must answer with, 200 when left out. marker, when given, is text the page must contain.

validate

"validate": {
  "endpoints": [{ "path": "/", "status": 200, "contains": "Hello" }],
  "steps": [{ "name": "the package is listed", "command": "pkg info example-hello", "expect": { "outputContains": "example-hello" } }],
  "platforms": ["ubuntu-24.04"],
  "timeout": 600
}

pkg validate always checks the built file itself: its header, that our license can unlock it, and what is inside it. endpoints and steps are checked in a fresh virtual machine for each name in platforms: it installs the package, deploys the site, requests each endpoint, and runs each step. With no platforms listed, pkg validate stops after its own checks, unless it is run with --vm. timeout is the time in seconds each machine may take, from 10 to 7200, and 600 when left out.

• An endpoint has a path starting with /, the status it must answer with (200 when left out), and optionally text it must contain.
• A step has a name and a command, or a list of commands, run as Nextweb commands. expect can name the exitCode and text the output outputContains; with neither, every command must succeed.

What is always left out

The build never includes:

• node_modules, .git, .nextweb-cache, and .nextweb-pkg folders, at any depth;
• dist, nextweb_server, and verification-reports at the top of the folder;
• .env files, log files, private keys, and the credential files of common tools such as .npmrc, .aws/, and .ssh/, whatever include says.

Files named like secrets, such as credentials.json, are built in, and pkg create names them so we can check. .gitignore is not read: a file git ignores is still built in.

When the application's package.json lists dependencies, the package carries its node_modules, because nothing installs them on the server. Run npm install --omit=dev in the folder before pkg create.

.nextwebignore

To leave out more, list it in .nextwebignore at the root of the folder, one pattern per line, the way .gitignore is written. Lines starting with # are comments.

notes/
*.psd
test/fixtures/large/

A bare name such as *.psd matches at any depth. A pattern with a / at the start or in the middle, such as test/fixtures/large/, matches from the top of the folder, and a / at the end matches folders only. A line starting with ! stops the build: nothing listed here can be put back. To name exactly what goes in instead, use include.