citizen/README.md

Node.js MVC web application framework. Includes routing, serving, caching, session management, and other helpful tools.

# citizen

citizen is an MVC-based web application framework designed for people interested in quickly building fast, scalable web sites instead of digging around Node's guts or cobbling together a wobbly Jenga tower made out of 50 different packages.

Use citizen as the foundation for a traditional server-side web application, a modular single-page application (SPA), or a RESTful API.

**There were numerous breaking changes in the transition from 0.9.x to 1.0.x.** Please consult the changelog for an itemized list and review this updated documentation thoroughly.


## Benefits

- Convention over configuration, but still flexible
- Zero-configuration server-side routing with SEO-friendly URLs
- Server-side session management
- Key/value store: cache requests, controller actions, objects, and static files
- Simple directives for managing cookies, sessions, redirects, caches, and more
- Powerful code reuse options via includes (components) and chaining
- HTML, JSON, JSONP, and plain text served from the same pattern
- ES module and Node (CommonJS) module support
- Hot module replacement in development mode
- View rendering using template literals or any engine supported by [consolidate](https://github.com/ladjs/consolidate)
- Few direct dependencies

Clearly, this is way more content than any NPM/Github README should contain. I'm working on a site for this documentation.


## Is it production ready?

I use citizen on [my personal site](https://jaysylvester.com) and [originaltrilogy.com](https://originaltrilogy.com). OT.com handles a moderate amount of traffic (a few hundred thousand views each month) on a $30 cloud hosting plan running a single instance of citizen, where the app/process runs for months at a time without crashing. It's very stable.


## Quick Start

These commands will create a new directory for your web app, install citizen, use its scaffolding utility to create the app's skeleton, and start the web server:

```bash
$ mkdir myapp && cd myapp
$ npm install citizen
$ node node_modules/citizen/util/scaffold skeleton
$ node app/start.js
```

If everything went well, you'll see confirmation in the console that the web server is running. Go to http://127.0.0.1:3000 in your browser and you'll see a bare index template.

citizen uses [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) in its default template engine. You can install [consolidate](https://github.com/ladjs/consolidate), update the [template config](#config-settings), and modify the default view templates accordingly.

For configuration options, see [Configuration](#configuration). For more utilities to help you get started, see [Utilities](#utilities).


<!-- ### Demo App

Check out [model-citizen](https://github.com/jaysylvester/model-citizen), a basic responsive web site built with citizen that demonstrates some of the framework's functionality. -->


### App Directory Structure

```
app/
  config/             // These files are all optional
    citizen.json      // Default config file
    local.json        // Examples of environment configs
    qa.json
    prod.json
  controllers/
    hooks/            // Application event hooks (optional)
      application.js
      request.js
      response.js
      session.js
    routes/           // Public route controllers
      index.js
  helpers/            // Utility modules (optional)
  models/             // Models (optional)
    index.js
  views/
    error/            // Default error views
      404.html
      500.html
      ENOENT.html
      error.html
    index.html        // Default index view
  start.js
logs/                 // Log files
  access.log
  error.log
web/                  // public static assets
```



### Initializing citizen and starting the web server

Import citizen and start your app:

```js
// start.js
import citizen from 'citizen'
    
global.app = citizen
app.start()
```

Run from the terminal:

```bash
$ node start.js
```



### Configuration

You can configure your citizen app with a config file, startup options, and/or custom controller configurations.

The config directory is optional and contains configuration files in JSON format that drive both citizen and your app. You can have multiple citizen configuration files within this directory, allowing different configurations based on environment. citizen builds its configuration based on the following hierarchy:

1. If citizen finds a config directory, it parses each JSON file looking for a `host` key that matches the machine's hostname, and if it finds one, extends the default configuration with the file config.
2. If citizen can't find a matching `host` key, it looks for a file named citizen.json and loads that configuration.
3. citizen then extends the config with your [optional startup config](#startup-configuration).
4. Individual route controllers and and actions can have [their own custom config](#controller-configuration) that further extends the app config.

Let's say you want to run citizen on port 8080 in your local dev environment and you have a local database your app will connect to. You could create a config file called local.json (or dev.json, whatever you want) with the following:

```js
{
  "host":       "My-MacBook-Pro.local",
  "citizen": {
    "mode":     "development",
    "http": {
      "port":   8080
    }
  },
  "db": {
    "server":   "localhost",  // app.config.db.server
    "username": "dbuser",     // app.config.db.username
    "password": "dbpassword"  // app.config.db.password
  }
}
```

This config would extend the default configuration only when running on your local machine. Using this method, you can commit multiple config files from different environments to the same repository.

The database settings would be accessible anywhere within your app via `app.config.db`. The `citizen` and `host` nodes are reserved for the framework; create your own node(s) to store your custom settings.


#### Startup configuration

You can set your app's configuration at startup through `app.start()`. If there is a config file, the startup config will extend the config file. If there's no config file, the startup configuration extends the default citizen config.

```js
// Start an HTTPS server with a PFX file
app.start({
  citizen: {
    http: {
      enabled: false
    },
    https: {
      enabled: true,
      pfx:    '/absolute/path/to/site.pfx'
    }
  }
})
```


#### Controller configuration

To set custom configurations at the route controller level, export a `config` object (more on route controllers and actions in the [route controllers](#route-controllers) section).

```js
export const config = {
  // The "controller" property sets a configuration for all actions in this controller
  controller: {
    contentTypes: [ 'application/json' ]
  }

  // The "submit" property is only for the submit() controller action
  submit: {
    form: {
      maxPayloadSize: 1000000
    }
  }
}
```


#### Default configuration

The following represents citizen's default configuration, which is extended by your configuration:

```js
{
  host                 : '',
  citizen: {
    mode               : process.env.NODE_ENV || 'production',
    global             : 'app',
    http: {
      enabled          : true,
      hostname         : '127.0.0.1',
      port             : 80
    },
    https: {
      enabled          : false,
      hostname         : '127.0.0.1',
      port             : 443,
      secureCookies    : true
    },
    connectionQueue    : null,
    templateEngine     : 'templateLiterals',
    compression: {
      enabled          : false,
      force            : false,
      mimeTypes        : [
                          'application/javascript',
                          'application/x-javascript',
                          'application/xml',
                          'application/xml+rss',
                          'image/svg+xml',
                          'text/css',
                          'text/html',
                          'text/javascript',
                          'text/plain',
                          'text/xml'
                          ]
    },
    sessions: {
      enabled          : false,
      lifespan         : 20 // minutes
    },
    layout: {
      controller       : '',
      view             : ''
    },
    contentTypes       : [
                          'text/html',
                          'text/plain',
                          'application/json',
                          'application/javascript'
                          ],
    forms: {
      enabled          : true,
      maxPayloadSize   : 524288 // 0.5MB
    },
    cache: {
      application: {
        enabled        : true,
        lifespan       : 15, // minutes
        resetOnAccess  : true,
        encoding       : 'utf-8',
        synchronous    : false
      },
      static: {
        enabled        : false,
        lifespan       : 15, // minutes
        resetOnAccess  : true
      },
      invalidUrlParams : 'warn',
      control          : {}
    },
    errors             : 'capture',
    logs: {
      access           : false, // performance-intensive, opt-in only
      error: {
        client         : true, // 400 errors
        server         : true // 500 errors
      },
      debug            : false,
      maxFileSize      : 10000,
      watcher: {
        interval       : 60000
      }
    },
    development: {
      debug: {
        scope: {
          config       : true,
          context      : true,
          cookie       : true,
          form         : true,
          payload      : true,
          route        : true,
          session      : true,
          url          : true,
        },
        depth          : 4,
        showHidden     : false,
        view           : false
      },
      watcher: {
        custom         : [],
        killSession    : false,
        ignored        : /(^|[/\\])\../ // Ignore dotfiles
      }
    },
    urlPath            : '/',
    directories: {
      app              : <appDirectory>,
      controllers      : <appDirectory> + '/controllers',
      helpers          : <appDirectory> + '/helpers',
      models           : <appDirectory> + '/models',
      views            : <appDirectory> + '/views',
      logs             : new URL('../../../logs', import.meta.url).pathname
      web              : new URL('../../../web', import.meta.url).pathname
    }
  }
}
```


#### Config settings

Here's a complete rundown of citizen's settings and what they do.

When starting a server, in addition to citizen's `http` and `https` config options, you can provide the same options as Node's [http.createServer()](https://nodejs.org/api/http.html#httpcreateserveroptions-requestlistener) and [https.createServer()](https://nodejs.org/api/https.html#httpscreateserveroptions-requestlistener).

The only difference is how you pass key files. As you can see in the examples above, you pass citizen the file paths for your key files. citizen reads the files for you.

<table>
  <caption>citizen config options</caption>
  <thead>
    <tr>
      <th>
        Setting
      </th>
      <th>
        Type
      <th>
        Default Value
      </th>
      <th>
        Description
      </th>
    </tr>
  </thead>
  <tr>
    <td>
      <code>host</code>
    </td>
    <td>
        String
    </td>
    <td>
      <code>''</code>
    </td>
    <td>
      To load different config files in different environments, citizen relies upon the server's hostname as a key. At startup, if citizen finds a config file with a <code>host</code> key that matches the server's hostname, it chooses that config file. This is not to be confused with the HTTP server <code>hostname</code> (see below).
    </td>
  </tr>
  <tr>
    <td colspan="4">
      citizen
    </td>
  </tr>
  <tr>
    <td>
      <code>mode</code>
    </td>
    <td>
      String
    </td>
    <td>
      Checks <code>NODE_ENV</code> first, otherwise <code>production</code>
    </td>
    <td>
      The application mode determines certain runtime behaviors. Possible values are <code>production</code> and <code>development</code> Production mode silences console logs. Development mode enables verbose console logs, URL debug options, and hot module replacement.
    </td>
  </tr>
  <tr>
    <td>
      <code>global</code>
    </td>
    <td>
      String
    </td>
    <td>
      <code>app</code>
    </td>
    <td>
      The convention for initializing citizen in the start file assigns the framework to a global variable. The default, which you'll see referenced throughout the documentation, is <code>app</code>. You can change this setting if you want to use another name.
    </td>
  </tr>
  <tr>
    <td>
      <code>contentTypes</code>
    </td>
    <td>
      Array
    </td>
    <td>
      <code>
        [
          'text/html',
          'text/plain',
          'application/json',
          'application/javascript'
        ]
      </code>
    </td>
    <td>
      An allowlist of response formats for each request, based on the client's <code>Accept</code> request header. When configuring available formats for individual route controllers or actions, the entire array of available formats must be provided.
    </td>
  </tr>
  <tr>
    <td>
      <code>errors</code>
    </td>
    <td>
      String
    </td>
    <td>
      <code>capture</code>
    </td>
    <td>
      When your application throws an error, the default behavior is for citizen to try to recover from the error and keep the application running. Setting this option to <code>exit</code> tells citizen to log the error and exit the process instead.
    </td>
  </tr>
  <tr>
    <td>
      <code>templateEngine</code>
    </td>
    <td>
      String
    </td>
    <td>
      <code>templateLiterals</code>
    </td>
    <td>
      citizen uses [template literal](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) syntax for view rendering by default. Optionally, you can install <a href="https://github.com/tj/consolidate.js">consolidate</a> and use any engine it supports (for example, install Handlebars and set <code>templateEngine</code> to <code>handlebars</code>).
    </td>
  </tr>
  <tr>
    <td>
      <code>urlPath</code>
    </td>
    <td>
      String
    </td>
    <td>
      <code>/</code>
    </td>
    <td>
      Denotes the URL path leading to your app. If you want your app to be accessible via http://yoursite.com/my/app and you're not using another server as a front end to proxy the request, this setting should be <code>/my/app</code> (don't forget the leading slash). This setting is required for the router to work.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      http
    </td>
  </tr>
  <tr>
    <td>
      <code>enabled</code>
    </td>
    <td>
        Boolean
    </td>
    <td>
      <code>true</code>
    </td>
    <td>
      Enables the HTTP server.
    </td>
  </tr>
  <tr>
    <td>
      <code>hostname</code>
    </td>
    <td>
        String
    </td>
    <td>
      <code>127.0.0.1</code>
    </td>
    <td>
      The hostname at which your app can be accessed via HTTP. You can specify an empty string to accept requests at any hostname.
    </td>
  </tr>
  <tr>
    <td>
      <code>port</code>
    </td>
    <td>
        Number
    </td>
    <td>
      <code>3000</code>
    </td>
    <td>
      The port number on which citizen's HTTP server listens for requests.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      https
    </td>
  </tr>
  <tr>
    <td>
      <code>enabled</code>
    </td>
    <td>
        Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Enables the HTTPS server.
    </td>
  </tr>
  <tr>
    <td>
      <code>hostname</code>
    </td>
    <td>
        String
    </td>
    <td>
      <code>127.0.0.1</code>
    </td>
    <td>
      The hostname at which your app can be accessed via HTTPS. The default is localhost, but you can specify an empty string to accept requests at any hostname.
    </td>
  </tr>
  <tr>
    <td>
      <code>port</code>
    </td>
    <td>
        Number
    </td>
    <td>
      <code>443</code>
    </td>
    <td>
      The port number on which citizen's HTTPS server listens for requests.
    </td>
  </tr>
  <tr>
    <td>
      <code>secureCookies</code>
    </td>
    <td>
        Boolean
    </td>
    <td>
      <code>true</code>
    </td>
    <td>
      By default, all cookies set within an HTTPS request are secure. Set this option to <code>false</code> to override that behavior, making all cookies insecure and requiring you to manually set the <code>secure</code> option in the cookie directive.
    </td>
  </tr>
  <tr>
    <td>
      <code>connectionQueue</code>
    </td>
    <td>
        Integer
    </td>
    <td>
      <code>null</code>
    </td>
    <td>
      The maximum number of incoming requests to queue. If left unspecified, the operating system determines the queue limit.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      sessions
    </td>
  </tr>
  <tr>
    <td>
      <code>enabled</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Enables the user session scope, which assigns each visitor a unique ID and allows you to store data associated with that ID within the application server.
    </td>
  </tr>
  <tr>
    <td>
      <code>lifespan</code>
    </td>
    <td>
      Positive Integer
    </td>
    <td>
      <code>20</code>
    </td>
    <td>
      If sessions are enabled, this number represents the length of a user's session, in minutes. Sessions automatically expire if a user has been inactive for this amount of time.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      layout
    </td>
  </tr>
  <tr>
    <td>
      <code>controller</code>
    </td>
    <td>
      String
    </td>
    <td>
      <code>''</code>
    </td>
    <td>
      If you use a global layout controller, you can specify the name of that controller here instead of using the <code>next</code> directive in all your controllers.
    </td>
  </tr>
  <tr>
    <td>
      <code>view</code>
    </td>
    <td>
      String
    </td>
    <td>
      <code>''</code>
    </td>
    <td>
      By default, the layout controller will use the default layout view, but you can specify a different view here. Use the file name without the file extension.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      forms
    </td>
  </tr>
  <tr>
    <td>
      <code>enabled</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>true</code>
    </td>
    <td>
      citizen provides basic payload processing for simple forms. If you prefer to use a separate form package, set this to <code>false</code>.
    </td>
  </tr>
  <tr>
    <td>
      <code>maxPayloadSize</code>
    </td>
    <td>
      Positive Integer
    </td>
    <td>
      <code>524288</code>
    </td>
    <td>
      Maximum form payload size, in bytes. Set a max payload size to prevent your server from being overloaded by form input data.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      compression
    </td>
  </tr>
  <tr>
    <td>
      <code>enabled</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Enables gzip and deflate compression for rendered views and static assets.
    </td>
  </tr>
  <tr>
    <td>
      <code>force</code>
    </td>
    <td>
      Boolean or String
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Forces gzip or deflate encoding for all clients, even if they don't report accepting compressed formats. Many proxies and firewalls break the Accept-Encoding header that determines gzip support, and since all modern clients support gzip, it's usually safe to force it by setting this to <code>gzip</code>, but you can also force <code>deflate</code>.
    </td>
  </tr>
  <tr>
    <td>
      <code>mimeTypes</code>
    </td>
    <td>
      Array
    </td>
    <td>
      <p>See default config above.</p>
    </td>
    <td>
      An array of MIME types that will be compressed if compression is enabled. See the sample config above for the default list. If you want to add or remove items, you must replace the array in its entirety.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      cache
    </td>
  </tr>
  <tr>
    <td>
      <code>control</code>
    </td>
    <td>
      Object containing key/value pairs
    </td>
    <td>
      <code>{}</code>
    </td>
    <td>
      Use this setting to set Cache-Control headers for route controllers and static assets. The key is the pathname of the asset, and the value is the Cache-Control header. See <a href="#client-side-caching">Client-Side Caching</a> for details.
    </td>
  </tr>
  <tr>
    <td>
      <code>invalidUrlParams</code>
    </td>
    <td>
      String
    </td>
    <td>
      <code>warn</code>
    </td>
    <td>
      The route cache option can specify valid URL parameters to prevent bad URLs from being cached, and <code>invalidUrlParams</code> determines whether to log a warning when encountering bad URLs or throw a client-side error. See <a href="#caching-requests-and-controller-actions">Caching Requests and Controller Actions</a> for details.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      cache.application
    </td>
  </tr>
  <tr>
    <td>
      <code>enabled</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>true</code>
    </td>
    <td>
      Enables the in-memory cache, accessed via the <code>cache.set()</code> and <code>cache.get()</code> methods.
    </td>
  </tr>
  <tr>
    <td>
      <code>lifespan</code>
    </td>
    <td>
      Number
    </td>
    <td>
      <code>15</code>
    </td>
    <td>
      The length of time a cached application asset remains in memory, in minutes.
    </td>
  </tr>
  <tr>
    <td>
      <code>resetOnAccess</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>true</code>
    </td>
    <td>
      Determines whether to reset the cache timer on a cached asset whenever the cache is accessed. When set to <code>false</code>, cached items expire when the <code>lifespan</code> is reached.
    </td>
  </tr>
  <tr>
    <td>
      <code>encoding</code>
    </td>
    <td>
      String
    </td>
    <td>
      <code>utf-8</code>
    </td>
    <td>
      When you pass a file path to cache.set(), the encoding setting determines what encoding should be used when reading the file.
    </td>
  </tr>
  <tr>
    <td>
      <code>synchronous</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      When you pass a file path to cache.set(), this setting determines whether the file should be read synchronously or asynchronously. By default, file reads are asynchronous.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      cache.static
    </td>
  </tr>
  <tr>
    <td>
      <code>enabled</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      When serving static files, citizen normally reads the file from disk for each request. You can speed up static file serving considerably by setting this to <code>true</code>, which caches file buffers in memory.
    </td>
  </tr>
  <tr>
    <td>
      <code>lifespan</code>
    </td>
    <td>
      Number
    </td>
    <td>
      <code>15</code>
    </td>
    <td>
      The length of time a cached static asset remains in memory, in minutes.
    </td>
  </tr>
  <tr>
    <td>
      <code>resetOnAccess</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>true</code>
    </td>
    <td>
      Determines whether to reset the cache timer on a cached static asset whenever the cache is accessed. When set to <code>false</code>, cached items expire when the <code>lifespan</code> is reached.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      logs
    </td>
  </tr>
  <tr>
    <td>
      <code>access</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Enables HTTP access log files. Disabled by default because access logs can explode quickly and ideally it should be handled by a web server.
    </td>
  </tr>
  <tr>
    <td>
      <code>debug</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Enables debug log files. Useful for debugging production issues, but extremely verbose (the same logs you would see in the console in development mode).
    </td>
  </tr>
  <tr>
    <td>
      <code>maxFileSize</code>
    </td>
    <td>
      Number
    </td>
    <td>
      <code>10000</code>
    </td>
    <td>
      Determines the maximum file size of log files, in kilobytes. When the limit is reached, the log file is renamed with a time stamp and a new log file is created.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      logs.error
    </td>
  </tr>
  <tr>
    <td>
      <code>client</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>true</code>
    </td>
    <td>
      Enables logging of 400-level client errors.
    </td>
  </tr>
  <tr>
    <td>
      <code>server</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Enables logging of 500-level server/application errors.
    </td>
  </tr>
  <tr>
    <td>
      <code>status</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Controls whether status messages should be logged to the console when in production mode. (Development mode always logs to the console.)
    </td>
  </tr>
  <tr>
    <td colspan="4">
      logs.watcher
    </td>
  </tr>
  <tr>
    <td>
      <code>interval</code>
    </td>
    <td>
      Number
    </td>
    <td>
      <code>60000</code>
    </td>
    <td>
      For operating systems that don't support file events, this timer determines how often log files will be polled for changes prior to archiving, in milliseconds.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      development
    </td>
  </tr>
  <tr>
    <td colspan="4">
      development.debug
    </td>
  </tr>
  <tr>
    <td>
      <code>scope</code>
    </td>
    <td>
      Object
    </td>
    </td>
    <td>
    <td>
      This setting determines which scopes are logged in the debug output in development mode. By default, all scopes are enabled.
    </td>
  </tr>
  <tr>
    <td>
      <code>depth</code>
    </td>
    <td>
      Positive integer
    </td>
    <td>
      <code>3</code>
    </td>
    <td>
      When citizen dumps an object in the debug content, it inspects it using Node's util.inspect. This setting determines the depth of the inspection, meaning the number of nodes that will be inspected and displayed. Larger numbers mean deeper inspection and slower performance.
    </td>
  </tr>
  <tr>
    <td>
      <code>view</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Set this to true to dump debug info directly into the HTML view.
    </td>
  </tr>
  <tr>
    <td>
      <code>enableCache</code>
    </td>
    <td>
      Boolean
    </td>
    <td>
      <code>false</code>
    </td>
    <td>
      Development mode disables the cache. Change this setting to <code>true</code> to enable the cache in development mode.
    </td>
  </tr>
  <tr>
    <td colspan="4">
      development.watcher
    </td>
  </tr>
  <tr>
    <td>
      <code>custom</code>
    </td>
    <td>
      Array
    </td>
    </td>
    <td>
    <td>
      You can tell citizen's hot module replacement to watch your own custom modules. This array can contain objects with <code>watch</code> (relative directory path to your modules within the app directory) and <code>assign</code> (the variable to which you assign these modules) properties. Example:
      <br><br>
      <code>[ { "watch": "/util", "assign": "app.util" } ]</code>
    </td>
  </tr>
</table>

citizen uses [chokidar](https://www.npmjs.com/package/chokidar) as its file watcher, so `watcher` option for both logs and development mode also accepts any option allowed by chokidar.


These settings are exposed publicly via `app.config.host` and `app.config.citizen`.

This documentation assumes your global app variable name is `app`. Adjust accordingly.


### citizen exports

<table>
  <tr>
    <td>
      <code>app.start()</code>
    </td>
    <td>
      Starts a citizen web application server.
    </td>
  </tr>
  <tr>
    <td>
      <code>app.config</code>
    </td>
    <td>
      The configuration settings you supplied at startup. citizen's settings are within <code>app.config.citizen</code>.
    </td>
  </tr>
  <tr>
    <td>
      <code>app.controllers</code><br />
      <code>app.models</code><br />
      <code>app.views</code>
    </td>
    <td>
      It's unlikely you'll need to access controllers and views directly, but referencing <code>app.models</code> instead of importing your models manually benefits from citizen's built-in <a href="#hot-module-replacement">hot module replacement</a>.
    </td>
  </tr>
  <tr>
    <td>
      <code>app.helpers</code>
    </td>
    <td>
      All <a href="#helpers">helper/utility modules</a> placed in <code>app/helpers/</code> are imported into the helpers object.
    </td>
  </tr>
  <tr>
    <td>
      <code>app.cache.set()</code><br />
      <code>app.cache.get()</code><br />
      <code>app.cache.exists()</code><br />
      <code>app.cache.clear()</code>
    </td>
    <td>
      <a href="#object-caching">Application cache</a> and key/value store used internally by citizen, also available for your app.
    </td>
  </tr>
  <tr>
    <td>
      <code>app.log()</code>
    </td>
    <td>
      Basic <a href="#logs">console and file logging</a> used by citizen, exported for your use.
    </td>
  </tr>
</table>



## Routing and URLs

The citizen URL structure determines which route controller and action to fire, passes URL parameters, and makes a bit of room for SEO-friendly content that can double as a unique identifier. The structure looks like this:

```
http://www.site.com/controller/seo-content/action/myAction/param/val/param2/val2
```

For example, let's say your site's base URL is:

```
http://www.cleverna.me
```

The default route controller is `index`, and the default action is `handler()`, so the above is the equivalent of the following:

```
http://www.cleverna.me/index/action/handler
```

If you have an `article` route controller, you'd request it like this:

```
http://www.cleverna.me/article
```

Instead of query strings, citizen passes URL parameters consisting of name/value pairs. If you had to pass an article ID of 237 and a page number of 2, you'd append name/value pairs to the URL:

```
http://www.cleverna.me/article/id/237/page/2
```

Valid parameter names may contain letters, numbers, underscores, and dashes, but must start with a letter or underscore.

The default controller action is `handler()`, but you can specify alternate actions with the `action` parameter (more on this later):

```
http://www.cleverna.me/article/action/edit
```

citizen also lets you optionally insert relevant content into your URLs, like so:

```
http://www.cleverna.me/article/My-Clever-Article-Title/page/2
```

This SEO content must always follow the controller name and precede any name/value pairs, including the controller action. You can access it generically via `route.descriptor` or within the `url` scope (`url.article` in this case), which means you can use it as a unique identifier (more on URL parameters in the [Route Controllers section](#route-controllers)).

### Reserved words

The URL parameters `action` and `direct` are reserved for the framework, so don't use them for your app.



## MVC Patterns

citizen relies on a simple model-view-controller convention. The article pattern mentioned above might use the following structure:

```
app/
  controllers/
    routes/
      article.js
  models/
    article.js    // Optional, name it whatever you want
  views/
    article.html  // The default view file name should match the controller name
```

At least one route controller is required for a given URL, and a route controller's default view file must share its name. Models are optional.

All views for a given route controller can exist in the `app/views/` directory, or they can be placed in a directory whose name matches that of the controller for cleaner organization:

```
app/
  controllers/
    routes/
      article.js
    models/
      article.js
    views/
      article/
        article.html  // The default view
        edit.html     // Alternate article views
        delete.html
```

More on views in the [Views section](#views).

Models and views are optional and don't necessarily need to be associated with a particular controller. If your route controller is going to pass its output to another controller for further processing and final rendering, you don't need to include a matching view (see the [controller next directive](#controller-chaining)).



### Route Controllers

A citizen route controller is just a JavaScript module. Each route controller requires at least one export to serve as an action for the requested route. The default action should be named `handler()`, which is called by citizen when no action is specified in the URL.

```js
// Default route controller action

export const handler = async (params, request, response, context) => {

  // Do some stuff

  return {
    // Send content and directives to the server
  }
}
```

The citizen server calls `handler()` after it processes the initial request and passes it 4 arguments: a `params` object containing the parameters of the request, the Node.js `request` and `response` objects, and the current request's context.

<table>
  <caption>Properties of the <code>params</code> object</caption>
  <tr>
    <td><code>config</code></td>
    <td>Your app's configuration, including any <a href="#controller-configuration">customizations</a> for the current controller action</td>
  </tr>
  <tr>
    <td><code>route</code></td>
    <td>Details of the requested route, such as the URL and the name of the route controller</td>
  </tr>
  <tr>
    <td><code>url</code></td>
    <td>Any parameters derived from the URL</td>
  </tr>
  <tr>
    <td><code>form</code></td>
    <td>Data collected from a POST</td>
  </tr>
  <tr>
    <td><code>payload</code></td>
    <td>The raw request payload</td>
  </tr>
  <tr>
    <td><code>cookie</code></td>
    <td>Cookies sent with the request</td>
  </tr>
  <tr>
    <td><code>session</code></td>
    <td>Session variables, if sessions are enabled</td>
  </tr>
</table>


In addition to having access to these objects within your controller, they are also included in your view context automatically so you can reference them within your view templates as local variables (more details in the <a href="#views">Views section</a>).

For example, based on the previous article URL...

```
http://www.cleverna.me/article/My-Clever-Article-Title/id/237/page/2
```

...you'll have the following `params.url` object passed to your controller:

```js
{
  article: 'My-Clever-Article-Title',
  id: '237',
  page: '2'
}
```

The controller name becomes a property in the URL scope that references the descriptor, which makes it well-suited for use as a unique identifier. It's also available in the `params.route` object as `params.route.descriptor`.

The `context` argument contains any data or directives that have been generated by previous controllers in the chain using their `return` statement.

To return the results of the controller action, include a `return` statement with any data and [directives](#controller-directives) you want to pass to citizen.

Using the above URL parameters, I can retrieve the article content from the model and pass it back to the server:

```js
// article controller

export const handler = async (params) => {
  // Get the article
  const article = await app.models.article.get({
    article: params.url.article,
    page: params.url.page
  })
  const author = await app.models.article.getAuthor({
    author: article.author
  })

  // Any data you want available to the view should be placed in the local directive
  return {
    local: {
      article: article,
      author: author
    }
  }
}
```

Alternate actions can be requested using the `action` URL parameter. For example, maybe we want a different action and view to edit an article:

```js
// http://www.cleverna.me/article/My-Clever-Article-Title/id/237/page/2/action/edit

// article controller

export const handler = async (params) => {
  // Get the article
  const article = await app.models.article.get({
    article: params.url.article,
    page: params.url.page
  })
  const author = await app.models.article.getAuthor({
    author: article.author
  })

  // Return the article for view rendering using the local directive
  return {
    local: {
      article: article,
      author: author
    }
  }
}

export const edit = async (params) => {
  // Get the article
  const article = await app.models.article.get({
    article: params.url.article,
    page: params.url.page
  })

  // Use the /views/article/edit.html view for this action
  return {
    local: {
      article: article
    },
    view: 'edit'
  }
}
```

You place any data you want to pass back to citizen within the `return` statement. All the data you want to render in your view should be passed to citizen within an object called `local`, as shown above. Additional objects can be passed to citizen to set directives that provide instructions to the server (see [Controller Directives](#controller-directives)). You can even add your own objects to the context and pass them from controller to controller (more in the [Controller Chaining section](#controller-chaining).)



### Models

Models are optional modules and their structure is completely up to you. citizen doesn't talk to your models directly; it only stores them in `app.models` for your convenience. You can also import them manually into your controllers if you prefer.

The following function, when placed in `app/models/article.js`, will be accessible in your app via `app.models.article.get()`:

```js
// app.models.article.get()
export const get = async (id) => {

  let article = // do some stuff to retrieve the article from the db using the provided ID, then...

  return article
}
```



### Views

citizen uses [template literals](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals) for view rendering by default. You can install [consolidate.js](https://github.com/tj/consolidate.js) and use any supported template engine. Just update the `templateEngine` config setting accordingly.

In `article.html`, you can reference variables you placed within the `local` object passed into the route controller's return statement. citizen also injects properties from the `params` object into your view context automatically, so you have access to those objects as local variables (such as the `url` scope):

```html
<!-- article.html -->

<!doctype html>
<html>
  <body>
    <main>
      <h1>
        ${local.article.title} — Page ${url.page}
      </h1>
      <h2>${local.author.name}, ${local.article.published}</h2>
      <p>
        ${local.article.summary}
      </p>
      <section>
        ${local.article.text}
      </section>
    </main>
  </body>
</html>
```


#### Rendering alternate views

By default, the server renders the view whose name matches that of the controller. To render a different view, [use the `view` directive in your return statement](#alternate-views).

All views go in `/app/views`. If a controller has multiple views, you can organize them within a directory named after that controller.

```
app/
  controllers/
    routes/
      article.js
      index.js
  views/
    article/
      article.html  // Default article controller view
      edit.html
    index.html      // Default index controller view
```


#### JSON and JSON-P

You can tell a route controller to return its local variables as JSON or JSON-P by setting the appropriate HTTP `Accept` header in your request, letting the same resource serve both a complete HTML view and JSON for AJAX requests and RESTful APIs.

The article route controller `handler()` action would return:

```json
{
  "article": {
    "title": "My Clever Article Title",
    "summary": "Am I not terribly clever?",
    "text": "This is my article text."
  },
  "author": {
    "name": "John Smith",
    "email": "jsmith@cleverna.me"
  }
}
```

Whatever you've added to the controller's return statement `local` object will be returned.

For JSONP, use `callback` in the URL:

```
http://www.cleverna.me/article/My-Clever-Article-Title/callback/foo
```

Returns:

```js
foo({
  "article": {
    "title": "My Clever Article Title",
    "summary": "Am I not terribly clever?",
    "text": "This is my article text."
  },
  "author": {
    "name": "John Smith",
    "email": "jsmith@cleverna.me"
  }
});
```


### Forcing a Content Type

To force a specific content type for a given request, set `response.contentType` in the route controller to your desired output:

```js
export const handler = async (params, request, response) => {
  // Every request will receive a JSON response regardless of the Accept header
  response.contentType = 'application/json'
}
```

You can force a global response type across all requests within an [event hook](#application-event-hooks).



## Helpers

Helpers are optional utility modules and their structure is completely up to you. They're stored in `app.helpers` for your convenience. You can also import them manually into your controllers and models if you prefer.

The following function, when placed in `app/helpers/validate.js`, will be accessible in your app via `app.helpers.validate.email()`:

```js
// app.helpers.validate.email()
export const email = (address) => {
  const emailRegex = new RegExp(/[a-z0-9!##$%&''*+/=?^_`{|}~-]+(?:\.[a-z0-9!##$%&''*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?/i)

  return emailRegex.test(address)
}
```



## Hot Module Replacement

citizen stores all modules in the `app` scope not just for easy retrieval, but to support hot module replacement (HMR). When you save changes to any module or view in development mode, citizen clears the existing module import and re-imports that module in real time.

You'll see a console log noting the affected file, and your app will continue to run. No need to restart.



## Error Handling

citizen does its best to handle errors gracefully without exiting the process. The following controller action will throw an error, but the server will respond with a 500 and keep running:

```js
export const handler = async (params) => {
  // app.models.article.foo() doesn't exist, so this action will throw an error
  const foo = await app.models.article.foo(params.url.article)

  return {
    local: foo
  }
}
```

You can also throw an error manually and customize the error message:

```js
export const handler = async (params) => {
  // Get the article
  const article = await app.models.article.get({
    article: params.url.article,
    page: params.url.page
  })

  // If the article exists, return it
  if ( article ) {
    return {
      local: {
        article: article
      }
    }
  // If the article doesn't exist, throw a 404
  } else {
    // Error messages default to the standard HTTP Status Code response, but you can customize them.
    let err = new Error('The requested article does not exist.')

    // The HTTP status code defaults to 500, but you can specify your own
    err.statusCode = 404

    throw err
  }
}
```

Note that `params.route.controller` is updated from the requested controller to `error`, so any references in your app to the requested controller should take this into account.

Errors are returned in the format requested by the route. If you request [JSON](#json-and-json-p) and the route throws an error, citizen will return the error in JSON format.

The app skeleton created by the [scaffold utility](#scaffold) includes optional error view templates for common client and server errors, but you can create templates for any HTTP error code.

### Capture vs. Exit

citizen's default error handling method is `capture`, which attempts graceful recovery. If you'd prefer to exit the process after an error, change `config.citizen.errors` to `exit`.

```js
// config file: exit the process after an error
{
  "citizen": {
    "errors": "exit"
  }
}
```

After the application error handler fires, citizen will exit the process.


### Error Views

To create custom error views for server errors, create a directory called `/app/views/error` and populate it with templates named after the HTTP response code or Node error code.

```
app/
  views/
    error/
      500.html      // Displays any 500-level error
      404.html      // Displays 404 errors specifically
      ENOENT.html   // Displays bad file read operations
      error.html    // Displays any error without its own template
```


## Controller Directives

In addition to view data, the route controller action's return statement can also pass directives to render alternate views, set cookies and session variables, initiate redirects, call and render includes, cache route controller actions/views (or entire requests), and hand off the request to another controller for further processing.


### Alternate Views

By default, the server renders the view whose name matches that of the controller. To render a different view, use the `view` directive in your return statement:

```js
// article controller

export const edit = async (params) => {
  const article = await app.models.article.get({
    article: params.url.article,
    page: params.url.page
  })

  return {
    local: article,
    // This tells the server to render app/views/article/edit.html
    view: 'edit'
  }
}
```


### Cookies

You set cookies by returning a `cookie` object within the controller action.

```js
export const handler = async (params) => {
  return {
    cookie: {
      // Cookie shorthand sets a cookie called username using the default cookie properties
      username: params.form.username,

      // Sets a cookie called last_active that expires in 20 minutes
      last_active: {
        value: new Date().toISOString(),
        expires: 20
      }
    }
  }
}
```

Here's an example of a complete cookie object's default settings:

```js
myCookie = {
  value: 'myValue',

  // Valid expiration options are:
  // 'now' - deletes an existing cookie
  // 'never' - current time plus 30 years, so effectively never
  // 'session' - expires at the end of the browser session (default)
  // [time in minutes] - expires this many minutes from now
  expires: 'session',

  path: '/',

  // citizen's cookies are accessible via HTTP/HTTPS only by default. To access a
  // cookie via JavaScript, set this to false.
  httpOnly: true,

  // Cookies are insecure when set over HTTP and secure when set over HTTPS.
  // You can override that behavior globally with the https.secureCookies setting
  // in your config or on a case-by-case basis with this setting.
  secure: false
}
```

Once cookies are set on the client, they're available in `params.cookie` within controllers and simply `cookie` within the view:

```html
<!doctype html>
<html>
  <body>
    <section>
      Welcome, ${cookie.username}.
    </section>
  </body>
</html>
```

Cookie variables you set within your controller aren't immediately available within the `params.cookie` scope. citizen has to receive the context from the controller and send the response to the client first, so use a local instance of the variable if you need to access it during the same request.

#### Reserved Words

All cookies set by citizen start with the `ctzn_` prefix to avoid collisions. Don't start your cookie names with `ctzn_` and you should have no problems.

#### Proxy Header

If you use citizen behind a proxy, such as NGINX or Apache, make sure you have an HTTP `Forwarded` header in your server configuration so citizen's handling of secure cookies works correctly.

Here's an example of how you might set this up in NGINX:

```
location / {
  proxy_set_header Forwarded         "for=$remote_addr;host=$host;proto=$scheme;";
  proxy_pass                          http://127.0.0.1:8080;
}
```



### Session Variables

If sessions are enabled, you can access session variables via `params.session` in your controller or simply `session` within views. These local scopes reference the current user's session without having to pass a session ID.

By default, a session has four properties: `id`, `started`, `expires`, and `timer`. The session ID is also sent to the client as a cookie called `ctzn_session_id`.

Setting session variables is pretty much the same as setting cookie variables:

```js
return {
  session: {
    username: 'Danny',
    nickname: 'Doc'
  }
}
```

Like cookies, session variables you've just assigned aren't available during the same request within the `params.session` scope, so use a local instance if you need to access this data right away.

Sessions expire based on the `sessions.lifespan` config property, which represents the length of a session in minutes. The default is 20 minutes. The `timer` is reset with each request from the user. When the `timer` runs out, the session is deleted. Any client requests after that time will generate a new session ID and send a new session ID cookie to the client.

To forcibly clear and expire the current user's session:

```js
return {
  session: {
    expires: 'now'
  }
}
```

#### Reserved Words

All session variables set by citizen start with the `ctzn_` prefix to avoid collisions. Don't start your session variable names with `ctzn_` and you should have no problems.


### Redirects

You can pass redirect instruc