Cheatsheet

A quick overview of the most important mojo.js classes, helpers and hooks.

Classes

App

The mojo.js application object. Created with the mojo function, which accepts a few options, but none of them are required.

  1. import mojo from '@mojojs/core';
  3. const app = mojo({
  5.   // Default configuration
  6.   config: {name: 'My Application'},
  8.   // Detect if the application has been imported and disable the command line interface if it has
  9.   detectImport: true,
  11.   // Format for HTTP exceptions ("html", "json", or "txt")
  12.   exceptionFormat: 'html',
  14.   // Rotating secret passphrases used for signed cookies and the like
  15.   secrets: ['s3cret'],
  17.   // Operating mode for application
  18.   mode: 'development'
  19. });

It is usually called app.

  1. // config: plain configuration object, filled with data by config plugins, use it to to store arbitrary information
  2. app.config.foo = 'bar';
  3. const foo = app.config.foo;
  5. // exceptionFormat: format for HTTP exceptions ("html", "json", or "txt")
  6. app.exceptionFormat = 'html';
  8. // secrets: rotating secret passphrases used for signed cookies and the like
  9. app.secrets = ['s3cret pa$$phrase'];
  11. // mode: operating mode for application
  12. const mode = app.mode;
  14. // home: a `Path` object with the path of the application home directory
  15. const path = app.home.child('config.json').toString();
  16. const content = app.home.child('views', 'foo.html.tmpl').readFile('utf8');
  18. // models: plain object, use it to store arbitray models
  19. app.models.frameworks = [{name: 'Catalyst'}, {name: 'Mojolicious'}, {name: 'mojo.js'}];
  21. // log: the application logger
  22. const child = app.log.child({someContextValue: 123, anotherContextValue: 'test'});
  23. child.debug('Shut up and take my money!');
  25. // validator: general purpose JSON schema validator
  26. app.validator.addSchema({type: 'object'}, 'testForm');
  27. const validate = app.validator.schema('testForm');
  29. // ua: a `UserAgent` object for use inside the application
  30. const res = await app.ua.get('https://mojolicious.org');
  31. const dom = await res.html();
  32. const title = dom.at('title').text();
  34. // session: the encrypted cookie based session manager
  35. app.session.cookieName = 'myapp';
  36. app.session.sameSite = 'strict';
  38. // mime: manage MIME types
  39. app.mime.custom['foo'] = 'text/foo; charset=utf-8';
  41. // renderer: the application renderer, use it to add template engines and view directories
  42. app.renderer.addEngine('foo', fooEngine);
  43. app.renderer.viewPaths.push(app.home.child('templates').toString());
  45. // cli: the command line interface, use it to add your own custom commands
  46. app.cli.commandPaths.push(app.home.child('cli').toString());
  48. // newMockContext: create a new mock context for application (very useful for testing)
  49. const ctx = app.newMockContext();
  50. const html = ctx.faviconTag();
  52. // newTestUserAgent: create a new test user-agent for application
  53. const ua = await app.newTestUserAgent();
  54. (await ua.getOk('/')).statusIs(200).bodyIs('Hello World!');
  56. // addAppHook: add an application hook to extend the framework
  57. app.addAppHook('server:start', async app => {
  58.   app.config.deployment = 'server';
  59. });
  61. // addContextHook: add a context hook to extend the framework
  62. app.addContextHook('dispatch:before', async ctx => {
  63.   ctx.res.set('Server', 'MyServer 1.0');
  64. });
  66. // addHelper: add a helper
  67. app.addHelper('debug', (ctx, str) => {
  68.   ctx.app.log.debug(str);
  69. });

The router is the most commonly used application property and there are various shortcut methods for it.

  1. // Create routes to controllers
  2. app.router.get('/users/:id').to('#users#show');
  4. // Create routes to controllers via shortcut method
  5. app.get('/users/:id').to('users#show');
  7. // Add placeholder types
  8. app.router.addType('futuramaName', ['bender', 'leela']);
  10. // Create routes directly to actions
  11. app.any('/hello/<name:futuramaName>', ctx => ctx.render({text: `Hello ${ctx.stash.name}`}));

Context

The main object representing an HTTP request or WebSocket handshake, usually called ctx.

  1. // req: the request object
  2. const path = ctx.req.path;
  4. // res: the response object
  5. await ctx.res.status(200).type('text/html').send('Hello World!');
  7. // params: all form parameters combined
  8. const params = await ctx.params();
  9. const foo = params.get('foo');
  11. // log: log messages with request id as context
  12. ctx.log.debug('Shut up and take my money!');
  14. // urlFor: generate URL for route or path
  15. const url = ctx.urlFor('index');
  17. // urlForFile: generate URL for static file
  18. const url = ctx.urlForFile('/foo/app.css');
  20. // urlWith: generate URL for route or path and preserve the current query parameters
  21. const url = ctx.urlWith('index');
  23. // session: persistent data storage for the next few requests.
  24. const session = await ctx.session();
  25. session.user = 'kraih';
  26. const user = session.user;
  28. // flash: data storage persistent only for the next request.
  29. const flash = await ctx.flash();
  30. flash.confirmation = 'The record has been updated';
  32. // config: access application config
  33. const foo = ctx.config.foo;
  35. // models: access application models
  36. const users = ctx.models.users;
  38. // schema: access validation function for JSON schema
  39. const validate = ctx.schema({$id: 'testForm', type: 'object'});
  40. const result = validate(await ctx.req.json());
  41. const valid = result.isValid;
  43. // redirectTo: send `302` redirect response
  44. await ctx.redirectTo('index');
  45. await ctx.redirectTo('https://mojojs.org');
  47. // respondTo: automatically select best possible representation for resource
  48. await ctx.respondTo({
  49.   json: {json: {hello: 'world'}},
  50.   any: {text: 'Hello World!'}
  51. });
  53. // sendFile: send static file
  54. await ctx.sendFile(ctx.home.child('index.js'));
  56. // exceptionFormat: format for HTTP exceptions ("html", "json", or "txt")
  57. ctx.exceptionFormat = 'html';
  59. // app: the mojo.js application object
  60. const app = ctx.app;

The ctx.render() method is the most common way to generate a response.

  1. // Create a response from a string
  2. await ctx.render({text: 'Hello World!'});
  4. // Create a JSON response from a data structure
  5. await ctx.render({json: {hello: 'world'}});
  7. // Create a YAML response from a data structure
  8. await ctx.render({yaml: {hello: 'world'}});
  10. // Create a response by rendering the view "views/foo/bar.*.*"
  11. await ctx.render({view: 'foo/bar'});
  13. // Create a response by rendering an inline view (tmpl by default)
  14. await ctx.render({inline: 'Hello <%= name %>'}, {name: 'Mojo'});
  16. // Render something, but return it as a string
  17. const json = await ctx.renderToString({json: {hello: 'world'}});

Request

The ctx.req property of the context object. All URLs use URL objects and form parameters URLSearchParams objects.

  1. // method: HTTP request method
  2. const method = ctx.req.method;
  4. // path: request path
  5. const path = ctx.req.path;
  7. // baseURL: base URL for request (protocol might be from the X-Forwarded-Proto header)
  8. const baseURL = ctx.req.baseURL;
  10. // ip: the client IP address (may be from the X-Forwarded-For header)
  11. const address = ctx.req.ip;
  13. // userinfo: Basic authentication data
  14. const userinfo = ctx.req.userinfo;
  16. // requestId: reasonably unique request id
  17. const requestId = ctx.req.requestId;
  19. // get: request headers
  20. const accept = ctx.req.get('Accept');
  22. // getCookie: get cookie values
  23. const cookie = ctx.req.getCookie('foo');
  25. // query: query parameters
  26. const params = ctx.req.query();

There are multiple methods to receive the request content in various formats.

  1. // Retrieve request body as a string
  2. const text = await ctx.req.text();
  4. // Retrieve request body as a `Buffer`
  5. const buffer = await ctx.req.buffer();
  7. // Retrieve "application/x-www-form-urlencoded" or "multipart/form-data" form parameters
  8. const params = await ctx.req.form();
  9. const foo = params.get('foo');
  11. // Retrieve request body as parsed JSON
  12. const data = await ctx.req.json();
  14. // Retrieve request body as parsed YAML
  15. const data = await ctx.req.yaml();
  17. // Retrieve request body as parsed XML via `@mojojs/dom`
  18. const dom = await ctx.req.xml();
  19. const title = dom.at('foo > title').text();
  21. // Retrieve request body as parsed HTML via `@mojojs/dom`
  22. const dom = await ctx.req.html();
  23. const title = dom.at('head > title').text();
  25. // Retrieve request body as a `Readable` stream
  26. const stream = ctx.req.createReadStream();
  28. // Pipe request body to `stream.Writable` object
  29. await ctx.req.pipe(process.stdout);
  31. // Retrieve request body from async iterator
  32. const parts = [];
  33. for await (const chunk of ctx.req) {
  34.   parts.push(chunk);
  35. }
  36. const buffer = Buffer.concat(parts);

Response

The ctx.res property of the context object.

  1. // status: set response code and message
  2. ctx.res.status(200);
  3. ctx.res.status(289, 'Custom Status');
  5. // set: set response headers
  6. ctx.res.set('Server', 'Mojo/1.0');
  8. // type: set "Content-Type" header
  9. ctx.res.type('quote/futurama');
  11. // length: set "Content-Length" header
  12. ctx.res.length(12);
  14. // setCookie: set cookie
  15. ctx.res.setCookie('user', 'Bender', {path: '/', httpOnly: true});

The ctx.res.send() method is used to actually send the response.

  1. // Send response with `stream.Readable` object as body
  2. await ctx.res.status(200).send(stream);
  4. // Send response with a string as body
  5. await ctx.res.status(200).type('text/plain').length(12).send('Hello World!');
  7. // Send response without a body
  8. await ctx.res.status(204).send();

Helpers

These generic utility helpers are currently available by default:

currentRoute

  1. const name = ctx.currentRoute();

Get the current route name.

inspect

  1. const serialized = ctx.inpsect({hello: 'world'});

Serialize data structure for debugging.

Exception Helpers

These exception helpers are currently available by default, they can be overloaded to change framework behavior:

exception

  1. await ctx.exception(new Error('Something went wrong!'));

Render an exception response in the appropriate format by delegating to more specific exception helpers for HTTP and WebSockets.

htmlException

  1. await ctx.htmlException(new Error('Something went wrong!'));

Render an HTML response and set the response status to 500.

htmlNotFound

  1. await ctx.htmlNotFound();

Render an HTML response and set the response status to 404.

httpException

  1. await ctx.httpException(new Error('Something went wrong!'));

Log the exception and render an HTTP exception response in the appropriate format and set the response status to 500 by delegating to more specific exception helpers for HTML, JSON and plain text rendering.

jsonException

  1. await ctx.jsonException(new Error('Something went wrong!'));

Render a JSON response and set the response status to 500.

jsonNotFound

  1. await ctx.jsonNotFound();

Render a JSON response and set the response status to 404.

notFound

  1. await ctx.notFound();

Render a not found response in the appropriate format by delegating to more specific exception helpers for HTTP and WebSockets.

txtException

  1. await ctx.txtException(new Error('Something went wrong!'));

Render a plain text response and set the response status to 500.

txtNotFound

  1. await ctx.txtNotFound();

Render a plain text response and set the response status to 404.

websocketException

  1. await ctx.websocketException(new Error('Something went wrong!'));

Log the exception and close the WebSocket connection with an 1011 error code.

View Helpers

These view helpers are currently available by default:

faviconTag

  1. %= ctx.faviconTag()
  2. %= ctx.faviconTag('/favicon.ico')

Generate <link> tag for a favison, defaults to the mojo.js favicon.

imageTag

  1. %= ctx.imageTag('/myapp/logo.png')

Generate <img> tag for image file.

include

  1. %= await ctx.include('_navbar')

Include a partial template.

linkTo

  1. %= ctx.linkTo('some_route', {class: 'foo'}, 'Link to some route');

Generate portable a tag with ctx.urlFor().

scriptTag

  1. %= ctx.scriptTag('/bootstrap/bootstrap.bundle.min.js')

Generate <script> tag for JavaScript file.

styleTag

  1. %= ctx.styleTag('/bootstrap/bootstrap.min.css')

Generate <link> tag for CSS file.

tag

  1. %= tag 'div'
  2. %= tag 'div', {class: 'wrapper'}
  3. %= tag 'div', {class: 'wrapper'}, 'Hello World!'

Generate HTML tag.

Hooks

These are all application hooks that are currently available, in the same order they usually run:

command:before

Runs after app.start() has been called, and before the application reaches a command or prints the command list.

  1. app.addAppHook('command:before', async (app, args) => {
  2.   if (args[2] === 'legacy-server') args[2] = 'server';
  3. });

Useful for reconfiguring the application before running a command or to modify the behavior of a command. Passed the application object and command arguments.

server:start

Runs whenever the server has been started.

  1. app.addAppHook('server:start', async app => {
  2.   app.config.deployment = 'server';
  3. });

Useful for reconfiguring the application or warming up caches. Passed the application object.

server:stop

Runs whenever the server has been stopped.

  1. app.addAppHook('server:stop', async app => {
  2.   await app.models.foo.someCleanupCode();
  3. });

Useful for cleanup tasks. Passed the application object.

command:after

Runs after a command is finished or the command list has been printed.

  1. app.addAppHook('command:after', async (app, args) => {
  2.   if (args[2] === 'server') await app.models.foo.someCleanupCode();
  3. });

Useful for cleanup tasks. Passed the application object and command argument.

Context Hooks

These are all context hooks that are currently available, in the same order they usually run:

dispatch:before

Runs after a new request has been received and before the static file server and router start their work.

  1. app.addContextHook('dispatch:before', async ctx => {
  2.   const agent = ctx.req.get('user-agent') ?? '';
  3.   if (/Internet Explorer/.test(agent) === true) ctx.stash.browser = 'ie';
  4. });

Useful for rewriting incoming requests and other preprocessing tasks. Passed the context object. Can return true to intercept the static file server and router.

static:before

Runs before the static file server sends a response.

  1. app.addContextHook('static:before', async (ctx, file) => {
  2.   ctx.res.set('Cache-Control', 'max-age=3600, must-revalidate');
  3. });

Mostly used for post-processing static file responses. Passed the context object and the static file to be sent. Can return true to intercept sending the static file.

router:before

Runs after the static file server determined if a static file should be served and before the router starts its work.

  1. app.addContextHook('router:before', async ctx => {
  2.   if (ctx.req.path !== '/test') return;
  3.   await ctx.render({text: 'Intercepted!'});
  4.   return true;
  5. });

Mostly used for custom dispatchers and collecting metrics. Passed the context object. Can return true to intercept the router.

send:before

Runs after ctx.res.send() has been called and before dynamically generated content is sent with the response.

  1. app.addContextHook('send:before', async (ctx, body) => {
  2.   ctx.res.set('Cache-Control', 'max-age=3600, must-revalidate');
  3. });

Useful for post-processing dynamically generated content. Passed the context object and the dynamically generated content. Can return an arbitrary value to replace the dynamic content.

Support

If you have any questions the documentation might not yet answer, don’t hesitate to ask in the Forum, on Matrix, or IRC.