Your application on Nextweb

deploy <site> to <domain> using <package> runs a Node.js package as a website. This page is what the application can count on once apply starts it.

How it is started

Nextweb runs the package's site.entry file with the Node.js 22 built into the nextweb program. The entry is the main module, as it is under node app.js, so require.main === module is true in it and code guarded by that check runs.

It runs from the package's install folder, such as nextweb_server/pkg/app/example-hello, not from a copy. After pkg upgrade, the next apply or reload <site> runs the new version.

The application has 30 seconds to start listening. If it exits before it listens, even with code 0, or is not listening by then, the apply fails and names the site, with the last lines the application wrote to standard error. The other sites are still applied. The failed site is marked failed, verify <site> repeats the error, and the next apply tries it again.

What it is given

Listen on exactly NEXTWEB_HOST and NEXTWEB_PORT. The Visit address that apply prints is made of those two, and nothing else forwards to the application.

Where it keeps files

Do not write into the package's install folder: upgrading the package replaces it. Write to NEXTWEB_DATA_DIR. Nextweb creates it at the first apply, readable only by the user Nextweb runs as, and leaves it alone when the package is upgraded or the site is reloaded.

What it prints

Everything the application writes to standard output and standard error goes to nextweb_server/logs/<site>.log. The end of it:

nextweb:/> service logs hello

--lines=100 shows more than the 50 lines it shows by default. The log is kept to 5 MB, with one older file beside it.

When it stops

If the application exits with an error after it has started listening, Nextweb starts it again after 5 seconds, up to three times. A copy that exits again before it listens uses up one of the three. An application that exits before it first listens is not started again: apply says so, and the next apply or reload hello starts it. service hello restart restarts it. Stopping Nextweb, or service hello stop, sends it SIGTERM; close the server on that signal to finish requests cleanly.

An application that uses all of it

const fs = require('fs')
const http = require('http')
const path = require('path')

const host = process.env.NEXTWEB_HOST || '127.0.0.1'
const port = Number(process.env.NEXTWEB_PORT || 3000)
const dataDir = process.env.NEXTWEB_DATA_DIR || path.join(__dirname, 'data')
const visits = path.join(dataDir, 'visits.txt')

const server = http.createServer((req, res) => {
  const count = (fs.existsSync(visits) ? Number(fs.readFileSync(visits, 'utf8')) : 0) + 1
  fs.writeFileSync(visits, String(count))
  console.log(`visit ${count}`)
  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' })
  res.end(`Visit number ${count}\n`)
})

if (require.main === module) {
  fs.mkdirSync(dataDir, { recursive: true })
  server.listen(port, host)
  process.on('SIGTERM', () => server.close(() => process.exit(0)))
}

module.exports = server

The count survives pkg upgrade because it lives in NEXTWEB_DATA_DIR, and each visit shows up in service logs. Run on its own with node app.js, the same file listens on port 3000 and keeps its count in data/ beside it.

The .nextwebrc file describes how the folder is built into a package.