Nocms-server NPM

NoCMS Server

Web server for NoCMS sites.

API

init(config)

Initializes the server with config values.

import nocmsServer from 'nocms-server';

const configObj = {
  port: 8000,
  pageService: 'http://localhost:8001',
  i18nApi: 'http://localhost:8002',
  tokenSecret: 'shhhhhh',
};

nocmsServer.init(configObj);

Available config values

Field	Description	Default
port	Port of which the server is listening.	`3000`
tokenSecret	Secret for verifying user tokens. Required for publishing features	`''`
pageService	URL for accessing page service. Required for nocms solutions	`null`
logger	Logger function, supporting `debug`, `warn`, `info` and `error`	`console`
i18nApi	URL for accessing i18n servive. Required for translation features	`null`
languageList	Array of languages availabke to pages.	`[]`
assetsFolder	Path to folder containing static files, relative to process dir	`assets`
assetsBasePath	Assets mount path pointing to where the files can be requested by the browser.	`/assets`
clientAppScript	Path to the client application part of the universally rendered pages	`/assets/js/nocms.js`
commonAppScript	If the client script is built with a commons chunk, it can be put here.	`null`
adminAppScript	Path to the admin interface application script	`/assets/js/admin.js`
adminAppCss	Path to CSS file for the admin interface	`/assets/css/admin.css`
includeMainCss	Flag for controlling if css should be included in the generic page output	`true`
mainCss	Path to the main css file	`/assets/css/main.css`
verbose	Flag for controlling verbose logging output	`false`
compressResponses	Flag for controlling if responses should be compressed or not	`true`

addRedirects(redirectsArr)

Add an array of redirects on the form, [{ from: '<source>', to: '<target>' }, ... ].

nocmsServer.addRedirects([{ from: '/foo', to: '/bar' }])

When the user tries to access /foo the response ends with status 301 and Location: /bar-header is sent.

addRedirect(to, from)

Adds a single redirect to the redirect list. nocmsServer.addRedirect('/foo', '/bar') is equivalent to the above example.

addDataSource(urlPattern, handlerFunc)

Although NoCMS Server uses a page datasource by default, you can override the datasource by using the addDataSoruce function.

const peopleDataSource = (nocms) => {
return new Promise((resolve) => {
    nocms.pageData = {
      templateId: 'my-template',
      pageTitle: 'Tom is a great guy',
      uri: '/people/tom',
      // ...
      // other page data
      // ...
    };
    resolve(nocms);
  });
};
nocmsServer.addDataSource('/people/*', peopleDataSource);

Instead of requesting the page data service, page data are resolved using the peopleDataSource function for urls matching /people/*. It is important that the pageData object assigned to nocms.pageData contains the following fields: uri, templateId and pageTitle as these are used by the included nocmsServer components.

addComponentDataSource(componentType, handlerFunc)

// TODO

addSites(sites)

Add site configuration for the server. If no site configuration is added, server will default to site named localhost with language en on all domains. If the sites run on multiple domains, you can specify which domains should be resolbed to which sites. The Host header is used for site resolving.

const sites = [
  {
    "name": "example-en",
    "domains": ["example.com", "xmpl.com"],
    "lang": "en"
  },
  {
    "name": "example-no",
    "domains": ["example.no"],
    "lang": "no"
  }
];
nocmsServer.addSites(sites);

If you access the server with http://xmpl.com in the example, the site is resolved to example-en with language en.

setDefaultSite(name)

Set which site the requests that don't match any domain should be resolved to. The function takes the name of the site as an argument.

nocmsServer.setDefaultSite('example-en');

addMiddleware(name, url, middlewareFunc)

You can add your own middleware to execute custom operations at request scope. This is useful for adding custom tracking, applying a content security policy (CSP), check- or set cookies, etc. The middleware takes a name argument, which is for convenience, an optional url argument, which filters which URLs the middleware should be applied to, and the middleware function which is a connect compliant function.

const middleware = (req, res, next) => {
	res.append('X-Was-Here', 'Jørgen');
	next();
};

nocmsServer.addDataSource('Jørgen was here', '*', middleware);

setAreas(areas)

When NoCMS Server receives a request for an HTML page, the server renders a react component named Page. The component includes the <html>, <head> and <body> elements, and within the body tag, the requested template is rendered. In addition, there are certain fixed areas that are outputted if they are provided. These areas can be set using the setAreas function.

Available areas are:

headContent: Last in the head element
topContent: First in the top in the body element
bottomContent: After the #mainContent element
script: Last in the body element, useful for placing custom javascript files in

Note that headContent needs to be a react fragment, as the head element doesn't support nesting of elements. ( <> <meta name="foo" content="foo" /> </>)

const areas = {
  topContent: (pageData) => { return <p>{pageData.title}: Put your top content here</p>; },
  bottomContent: <p>Put your bottom content here</p>,
  headContent: <><meta name="was here" content="Jørgen" /></>,
};

nocmsServer.setAreas(areas);

setTemplates

This function is used to pass in the templates for the different pages of the site. A template has an id which should be a human readable identificator and a component which is the react component that are eventually rendered into the #mainContent element.

If the template are supposed to be available in the ""Create Page" dialog in the NoCMS Publishing interface, it would also need to have set a flag named siteTemplate and a name object containing a field for each admin interface language. Finally it could have an array of section components which will be available for inclusion in the "Add Component" dialog in NoCMS Publishing.

import Article from './Article.jsx';

const templates = [
  {
    id: 'article',
    component: Article, // Do not use jsx like <Aricle /> here, as it will be rendered later on.
    name: { // Translations for each admin interface language
      no: 'Artikkel',
      en: 'Article',
    },
    siteTemplate: true,
    sections: [
      {
        name: 'text', // section identificator
        description: 'Plain rich text component', // component description, visible in NoCMS Publishing
        categories: ['newsAndBlogpost', 'all'], // available in these groups in the NoCMS Publishing, Add Component interface.
        icon: '', // optional icon from "material icons" that is associated with the section component
        label: 'News',
        defaultData: { content: '...' },
      }
    ],
  },
  {
    id: 'custom-data-soruce-template',
    component: CustomTemplateComponent,
  },
]

nocmsServer.setTemplates(templates);

Page data is passed on to the template components using the spread operator, meaning that pageData.pageTitle will be available as props.pageTitle.

setRobotsTxt

You can set the robots.txt file by pointing to a file relative to the project root and process working directory. The content will be returned for /robots.txt requests

nocmsServer.setRobotsTxt('files/robots.txt');

start

This function starts the party by initializing the middlewares and passing on configuration values to them, and finally starting the server.

Middleware

#	Name	Description	url pattern
1	assets	Serving static files	config.assetsBasePath	`/assets`
2	defaultFaviconHandler	Handling default favicon requests *	`/favicon.ico`
3	robotsTxtHandler	Serving robots.txt file content	`/robots.txt`
4	correlator	Middleware for assigning correlation id to requesst, using `nocms-express-correlation-id`	`*`
5	health	Endpoint for health monitoring tools using `express-healthcheck`	`/health`
6	metrics	Middleware for recording request metrics using Prometheus and `nocms-express-metrics`	`*`
7	prepare	Middleware for preparing request for request pipeline	`*`
8	cookieParser	Express cookie-parser	`*`
9	redirectTrailingSlashRequests	Urls ending with `/` are redirected. `/foo/` is redirected to `/foo`	`*`
10	redirects	If url matches a redirect (using `addRedirects`), location header are sent and response is completed.	`*`
11	siteResolver	Setting site and lang on `res.locals` based on host header.	`*`
12	nocms-auth	Verifying and reading tokens. Populating `claims` field on `res.locals`.	`*`
13	nocms-reauth	If access token are expired, but refresh token are valid, user is redirected to `/api/login/refresh`	`*`
14	clearCacheMiddleware	Middleware for clearing entire Varnish cache. Requires publisher claim	`*`
15	externalMiddlewares	Per project custom middleware added using `addMiddleware`.	`*`
16	compression	Compress responses using `compression` package.	`*`
17	requestHandler	Request pipeline middleware	`*`
18	errorHandler	Error handler middleware catching exceptions and providing error responses	`*`