NukeBase

Custom POST Endpoints

Define POST routes by attaching handlers to nukebase.app. Two flavors are available:

  • app.postWithBody(path, handler) - POST endpoint with automatic body parsing and authentication.
  • app.post(path, handler) - Lightweight POST handler with no automatic parsing.
Parameter order: All handlers receive (res, req) — res first, then req. This matches the underlying uWebSockets convention and is the opposite of Express.

For serving static files (HTML, CSS, JS, images), see Serving Static Files.

postWithBody (POST with Body Parsing)

Use postWithBody to create POST endpoints with automatic body parsing and authentication. It automatically calls checkAuth(req, res) and populates req.admin with the authenticated user's information.

postWithBody — automatic auth via req.admin
// postWithBody automatically parses the body AND runs checkAuth()
nukebase.app.postWithBody('/api/contact', (res, req) => {
  // req.admin is automatically populated by checkAuth()
  if (!req.admin.uid) {
    return res.send(JSON.stringify({ status: "Failed", message: "Not authenticated" }));
  }

  const { name, email, message } = req.body;

  // Save to database with the authenticated user's ID
  set(["contactForms", generateRequestId()], {
    name,
    email,
    message,
    userId: req.admin.uid,
    timestamp: Date.now()
  });

  res.send(JSON.stringify({ status: "Success" }));
});

// req object includes:
// req.admin    - Auth object from checkAuth() (always present)
// req.body     - Parsed request body
// req.host     - Request host header
// req.method   - HTTP method
// req.getHeader(name) - Get any request header
//
// req.admin includes (always present):
// req.admin.cookies   - Parsed cookies object
// req.admin.urlParams - Parsed query string parameters
// req.admin.referer, req.admin.userAgent, req.admin.ip, req.admin.url
//
// req.admin includes (only when authenticated):
// req.admin.uid, req.admin.username, req.admin.token, req.admin.claims

Supported content types for postWithBody:

  • application/json - Parsed as JSON object
  • application/x-www-form-urlencoded - Parsed as key-value pairs
  • multipart/form-data - Parsed with file upload support (file fields become arrays of { filename, type, data: Buffer })
  • text/plain - Available as req.body.text
res.send() helper: res.send(body, status) writes the status (default "200 OK") and ends the response in one call. Only available in postWithBody handlers — raw post uses res.writeStatus() + res.end() directly.

Raw post (Lightweight)

Use raw post for lightweight endpoints that don't need body parsing. You must manually call checkAuth(req, res) to get authentication information:

Raw post — manual checkAuth(req, res)
// Raw post — no automatic parsing, no req.admin
nukebase.app.post('/api/status', (res, req) => {
  // Must manually call checkAuth(req, res) to get auth info
  const auth = checkAuth(req, res);

  if (!auth.uid) {
    res.writeStatus("401 Unauthorized");
    return res.end(JSON.stringify({ status: "Failed", message: "Not authenticated" }));
  }

  res.end(JSON.stringify({
    status: "Success",
    user: auth.username,
    role: auth.claims.role
  }));
});

// Raw post only has access to raw uWebSockets methods:
// req.getHeader(name) - Get a request header
// req.getUrl()        - Get the URL path
// req.getQuery()      - Get the raw query string
// req.getMethod()     - Get the HTTP method

Auth Context

Both req.admin (in postWithBody) and the return value of checkAuth(req, res) (in raw post) return the standard auth context object — see Auth Context for the full property list and shape.

When to use which?

  • Use postWithBody when you need to read the request body (JSON, form data, file uploads). Authentication is handled automatically via req.admin.
  • Use raw post when you don't need body parsing (simple status checks, redirects, lightweight responses). Call checkAuth(req, res) manually to get auth info.
↑