psychic

Psychic exposes a few different configuration points within the conf directory, but most of the configuration is done in conf/app.ts. This file enables you to express the underlying configuration for your psychic application, including encryption keys, cookie configurations, and much more.

├── app
│   ├── conf
│   │   ├── app.ts             // main psychic config
│   │   ├── dream.ts           // dream bindings
│   │   ├── global.ts          // loaded by app entry points
│   │   ├── inflections.ts     // loaded by app entry points
│   │   ├── loadEnv.ts         // loaded by app entry points
│   │   ├── repl.ts            // entry point for console
│   │   ├── routes.ts          // describes your application routes

conf/app.ts

The conf/app.ts file is the primary configuration entrypoint for Psychic applications. In here, you can specify your cookie configuration, encryption keys, as well as integration options for redis, socket.io, bullmq, etc...

set method

The set method is the primary method used to configure a Psychic application. The first argument to the set call is the specific configuration option that you want to adjust, such as appName, or apiOnly. Based on what is provided to the first argument, careful type helpers will guide you through specifying the second argument, which will be different based on what was provided to the first argument.

Below is a brief example of some of the settings that can be adjusted, while each option will be carefully illustrated in the subsequent sections of this guide.

export default (psy: Psyconf) => {
  psy.set('appName', 'howyadoin')
  psy.set('packageManager', 'pnpm')
  psy.set('apiOnly', false)
  psy.set('encryption', {
    cookies: {
      current: {
        algorithm: 'aes-256-gcm',
        key: AppEnv.string('APP_ENCRYPTION_KEY'),
      },
    },
  })
  psy.set('apiRoot', srcPath('..', '..'))
  psy.set('clientRoot', srcPath('..', '..', '..', 'client'))
  psy.set('inflections', inflections)
  psy.set('routes', routesCb)
  // ...etc
}

appName

This configuration informs Psychic what your app's name is, which is primarily used for logging purposes.

export default (psy: Psyconf) => {
  psy.set('appName', 'howyadoin')
  ...
}

packageManager

Determines which package manager to use when provisioning your psychic app, as well as any client apps that were requested during provisioning. Psychic also leverages your package manager choice during syncing, so it needs to be both provided and correct, meaning that if you switch somewhere down the road, you need to remember to update this line, or else you may get errors during type syncing.

export default (psy: Psyconf) => {
  psy.set('packageManager', 'yarn')
  ...
}

apiOnly

The apiOnly configuration option informs Psychic whether or not you are attaching a web application directly to this application. If you are building a front end to couple to your application, we recommend you turn this on, since it enables you to run feature tests with puppeteer, a testing tool which enables you to run a headless browser through your client application and connect to a Psychic test application. This tool is extremely powerful, and completely front-end agnostic, enabling you to build your front end however you want and connect it seamlessly with Psychic for testing.

export default (psy: Psyconf) => {
  psy.set('apiOnly', true)
  ...
}

apiRoot

The apiRoot configuration option specifies the root of your backend application. If you are building an api-only application, this would just be the path to your project root. However, if you are building with a client application, this would be the path to the api folder within your project root.

export default (psy: Psyconf) => {
  psy.set('apiRoot', srcPath('..', '..'))
  ...
}

clientRoot

The clientRoot configuration option specifies the root of your client (front end) application. If you are building an api-only application, you would not set this. Otherwise, it would be the path to your front-end application, usually located at /client.

export default (psy: Psyconf) => {
  psy.set('clientRoot', srcPath('..', '..', '..', 'client'))
  ...
}

controllers

In order for your web application to function, you must provide Psychic with your application files. To make this happen, the following must be included in your app (and is autogenerated automatically when you provision a new Psychic app):

export default (psy: Psyconf) => {
  psy.load('controllers', srcPath('app', 'controllers'), await importControllers())
  ...
}

Having the underlying Psychic app perform these imports could lead to many complexities not worth solving, so it is best for everyone if the actual importing happens app-side. The importControllers function is automatically provided for you, and already does this.

inflections

The inflections configuration option provides both Psychic and Dream with pluralization information specific to the DSL of your application. This is useful when utilizing generators, which will automatically perform pluralization operations on provided arguments to generate files within your application. This is all being drivin under the hood by the pluralize package.

// conf/inflections.ts
import pluralize from 'pluralize'

export default function inflections() {
  pluralize.addUncountableRule('paper')
}

// conf/app.ts
import inflections from './inflections'

export default (psy: Psyconf) => {
  psy.set('inflections', inflections)
  ...
}

routes

The routes configuration option provides Psychic with the routing schema for your webserver. More information about configuring routes can be found in our routing guides.

// conf/routes.ts
export default function routes(r: PsychicRouter) {
  r.get('/', WelcomeController, 'home')
}

// conf/app.ts
import routes from './routes'

export default (psy: Psyconf) => {
  psy.set('routes', routes)
  ...
}

json

Use the PsychicApplication#set method to apply json (body parser) options. Json options are driven through the body-parser package.

export default (psy: Psyconf) => {
  psy.set('json', {
    limit: '20kb',
  })
}

cookie

Use the PsychicApplication#set method to apply cookie options. Cookie options are driven through the express-cookie package.

export default (psy: Psyconf) => {
  // set options for cookie usage
  psy.set('cookie', {
    maxAge: {
      days: 14,
      hours: 0,
      minutes: 0,
      seconds: 0,
      milliseconds: 0,
    },
  })
}

ssl

Encryption between the load balancer and your Psychic webservers is an important part of encryption-in-transit. This SSL certificate will be a self-signed certificate. It is separate from the SSL certificate that you'll install on your load balancer.

export default (psy: Psyconf) => {
  if (AppEnv.isProduction) {
    psy.set('ssl', {
      key: AppEnv.string('SSL_KEY_PATH'),
      cert: AppEnv.string('SSL_CERT_PATH'),
    })
  }
}

encryption

Use the PsychicApplication#set method to apply encryption options.

export default (psy: Psyconf) => {
  psy.set('encryption', {
    cookies: {
      current: {
        algorithm: 'aes-256-gcm',
        key: AppEnv.string('APP_ENCRYPTION_KEY'),
      },
      // legacy is used when you are in the process of switching out your encryption keys
      legacy: {
        algorithm: 'aes-256-gcm',
        key: AppEnv.string('LEGACY_APP_ENCRYPTION_KEY'),
      },
    },
  })
}

cors

Use the PsychicApplication#set method to apply cors options. Cors options are driven through the express-cors package.

export default (psy: Psyconf) => {
  // set options for cors
  psy.set('cors', {
    credentials: true,
    origin: [AppEnv.string('CLIENT_HOST') || 'http://localhost:3000'],
  })
}

hooks

Hooks are called during specific lifecycle events in the server initialization process.

export default (psy: PsychicConfig) => {
  // run once an express app is initialized by the psychic server
  psy.on('server:init', (app) => {
    if (!testEnv() || AppEnv.boolean('REQUEST_LOGGING')) {
      const SENSITIVE_FIELDS = [
        'password',
        'token',
        'authentication',
        'authorization',
        'secret',
      ]

      app.use(
        expressWinston.logger({
          transports: [new winston.transports.Console()],
          format: winston.format.combine(
            winston.format.colorize(),
            winston.format.json(),
          ),
          ignoredRoutes: ['/health_check'],
          bodyBlacklist: SENSITIVE_FIELDS,
          // ...etc
        }),
      )
    }
  })

  // run a callback on server boot (but before routes are processed)
  psy.on('boot', () => {})

  // run a callback after routes are done processing
  psy.on('after:routes', () => {})

  // run a callback after the config is loaded
  psy.on('load', async () => {
    // uncomment to initialize background jobs
    await background.connect()
  })

  // run a callback after the config is loaded, but only if NODE_ENV=development
  psy.on('load:dev', () => {})

  // run a callback after the config is loaded, but only if NODE_ENV=test
  psy.on('load:test', () => {})

  // run a callback after the config is loaded, but only if NODE_ENV=production
  psy.on('load:prod', () => {})

  // this function will be run any time a server error is encountered
  // that psychic isn't sure how to respond to (i.e. 500 internal server errors)
  psy.on('server:error', (err, _, res) => {
    if (!res.headersSent) res.sendStatus(500)
    else if (developmentOrTestEnv()) throw err
  })
}