Environment Settings

To provide configuration for your app, Joystick relies on settings.<env>.json files at the root of your app (where <env> is the name of your environment, like development or production). You should have one settings.<env>.json file for each environment your app will run in.

When you start your app with joystick start via the CLI, this defaults to development. If you deploy your app using Push, this defaults to production.

The following settings files and environments are recommended:

  • settings.development.json - Settings for your local/development environment.
  • settings.staging.json - Settings for your staging environment (a private but internet-accessible version of your app running on hardware similar to your production environment).
  • settings.production.json - Settings for your production environment.
  • settings.test.json Settings for your app used when running joystick test via the Joystick CLI.

Non-development environment behavior

While you can use any environment name you wish, keep in mind that Joystick treats any environment name other than development as a production-like environment.

When starting your app via joystick start in the CLI, the contents of the matching settings.<env>.json file will be automatically copied to process.env.JOYSTICK_SETTINGS (where your Joystick app looks for its settings internally).

API Reference

File API

For all of your supported environment files, the following structure should be utilized. A description of each field's behavior can be found below.

Settings File API

  "config": {
    "push": {},
    "databases": [],
    "i18n": {
      "default_language": "en-US"
    "middleware": {},
    "email": {
      "from": "",
      "smtp": {
        "host": "",
        "port": 587,
        "username": "",
        "password": ""
  "global": {},
  "public": {},
  "private": {}


  • push object

    Contains configuration for your app when deployed with Push. Only required in settings.<env>.json files other than settings.development.json for Push-deployed apps).

  • config object Required

    Contains Joystick-specific settings for your app.

    • databases array[object] Required

      Contains the connection settings for the database you'd like to connect to your app.

    • i18n object Required

      Contains the internationalization (i18n) settings for your app.

    • middleware object Required

      Contains overrides for Joystick's built-in middleware.

    • email object Required

      Contains the email and SMTP settings for your app (used internally when calling email.send() on the server).

  • global object Required

    Contains global settings for your app. Any settings placed here will be accessible on the both the client (browser) and server.

  • public object Required

    Contains public settings for your app. Any settings placed here will be accessible on the both the client (browser) and server.

  • private object Required

    Contains private settings for your app. Any settings placed here will only be accessible on the server.


File Structure


Adding a Database