Configuration

You have access to different configuration that change the behaviour of Novel.

These configuration live in the /configdirectory of your Novel instance. Different files annotate which parts of the app the configuration impacts.

Usage

You can use configuration from the config directory like below

app/feature.ts
import config from 'novel/config';

config('app.host');

Quick guide on how to modify these files are discussed here

config(path: string, defaultValue: string)

You can fetch any configuration from the configuration registry using JSON path. The values are available in the Configuration reference below

app/feature.ts
import config from 'novel/config';
// Using default value
config('app.host', 'some-other-host-if-it-doesnt-exist.com');

set(path: string, value: any)

You can also modify any setting in runtime. This is not advisable but you may have a need for it regardless.

app/feature.ts
import { set } from 'novel/config';

config('custom.setting', '[email protected]');

It is advisable to do this in a place before your app starts preferrably in /app/index.tsbecause in production mode, multiple processes will be spun up, and your setting may not be applied in different processes.

Environment

Environment variables are loaded during startup-time.

Your instance will respect the values available in your current terminal context as well as the supplied .envfile in the project root.

You can refer to the sample file in https://github.com/madewithnovel/novel/blob/main/.env.sample

Minimum Required Environment Variables

Environment Variable
Description

HOST

The full domain that is used to access the instance

DB_HOST

The connection string used by /config/database.js

STRIPE_API_TOKEN

The API token used by Stripe

POSTMARK_API_TOKEN

The API token used by Postmark

Configuration

Configuration is loaded during startup-time.

The default configuration that you can reference lives in /packages/novel/lib/default.js

The configuration files in the /configdirectory are in .jsfiles and not typescript files. They do, however, can be written in esm format. They are not transpiled.

App

This file controls application level flags. This file is located in /config/app.js

Key
Description
Default Value

host

The hostname that this instance will be run from. In production, it is advisable to use your domain name here

  • process.env.HOST

  • http://localhost:7634

web

If you are using Novel Web standalone in vercel, you need to modify this to point to the hostname you use in vercel. See With Novel Web

  • process.env.WEB_HOST

  • process.env.HOST

  • http://localhost:7634

secure

Controls whether the instance should run in https

false

cors.origin

Controls where requests can come from, this can be an array or a boolean, or a string of the domain that is trying to access Novel API. See https://github.com/fastify/fastify-cors for more information

true

session.lifetime

Controls how long the session lasts for logged in users

1h

socket

Controls whether sockets are enabled in the instance. See Sockets for more information

false

notify_webhook

Used internally if you would like various internal events to be emitted to the destination of your choice. Accepts slack or discord endpoints for now.

process.env.NOTIFY_WEBHOOK

devtools

Enables Novel devtool inspection

true

telemetry

Enables telemetry collection of transactions/errors within the packages/novel directory. Used for product improvements.

true

Database

This file controls database settings. This file is located in /config/database.js

Key
Description
Default Value

connection

Connection string of the PostgreSQL database.

process.env.DB_HOST

cloudsql.enabled

Experimental. Enable CloudSQL endpoints

false

cloudsql.tables

Experimental. The tables that are allowed to be exposed by CloudSQL.

[]

Auth

This file controls authentication related settings. This file is located in /config/auth.js

Key
Description
Default Value

mfa

Enable the use of MFA

true

register_on_oauth

Register the account if it doesnt exist if coming from an Oauth flow

false

allow_unverified

Allow accounts to access the app even if they are unverified

false

verification_expiry

The time the verification link is available.

3d

routes.login

The URL in the front end for use in redirects

/login

routes.mfa

The URL in the front end for use in redirects

/login/mfa

routes.link

The URL in the front end for use in redirects

/login/link

routes.forget

The URL in the front end for use in redirects

/login/forget

routes.verify

The URL in the front end for use in redirects

/mail/verify

routes.signup

The URL in the front end for use in redirects

/signup

routes.after_login

The URL in the front end for use in redirects

/dashboard

routes.logout

The URL in the front end for use in redirects

/logout

roles

Roles available in the app. See Authorization

Mail

This file controls mail delivery. This file is located in /config/mail.js

Key
Description
Default Value

driver

Driver used for sending mail. smtp or postmark

postmark

credentials.token

The token used by postmark

process.env.POSTMARK_SERVER_TOKEN

credentials.host

The connection string of your SMTP server

process.env.SMTP_HOST

defaults.from

Default from address and name to sign off your emails

process.env.DEFAULT_MAIL_FROM

SaaS

This file controls how your SaaS behaves. This file is located in /config/saas.js

Key
Description
Default Value

driver

Driver used to manage your SaaS

stripe

credentials.token

The API token used by Stripe

process.env.STRIPE_API_TOKEN

credentials.webhook

The secret used by Stripe to validate the webhook payload

process.env.STRIPE_WEBHOOK_SECRET

sync

Recommended. If changes in the plans config are applied to Stripe automatically

true

archive_on_remote

If the plans are removed in the plans config, remove them in Stripe as well

true

tax_included

If tax is included for any automatically generated products/prices

false

currencies

Available currencies you support

['USD']

aggregate_usage

If usage based billing is used. See Usage Based BIlling

sum

upfront

Enable if upfront collection is required for subscriptions to be created.

false

plans

See Plans below

[]

Plans

config/saas.js
{
    // Unique ID for the plan
    id: 'standard-2024',
    
    // A human-readable name for the plan
    name: 'Standard',
    
    // Show this plan on the plans endpoint
    frontpage: true,
    
    // The monthly price for the plan
    monthly: [29],
    
    // The yearly price for the plan
    yearly: [290],
    
    // If the plan supports a trial period
    trial: 30,
    
    // The meter used for usage based billing
    meter: null,
    
    // Flags that are enabled to users/orgs that have this plan
    flags: ['projects'],
    
    // Limits applied to the users/orgs that have this plan
    limits: {
        projects: 5,
        seats: 2,
    },
}

See https://github.com/madewithnovel/novel/blob/main/config/saas.js

Filesystem

This file controls how files are handled during uploads and management. This file is located in /config/filesystem.js

Key
Description
Default Value

driver

Driver to use for file management

s3

public_url

The URL assets use to generate their public URLs

process.env.FILESYSTEM_PUBLIC_URL

default_bucket

A bucket that files belong to. To comply with S3 schemes.

  • process.env.FILESYSTEM_DEFAULT_BUCKET

  • default

credentials.endpoint

URL where uploads can be sent to

process.env.FILESYSTEM_ENDPOINT

credentials.client_id

Credentials of the remote file system

process.env.FILESYSTEM_ACCESS_KEY_ID

credentials.secret_key

Credentials of the remote file system

process.env.FILESYSTEM_SECRET_ACCESS_KEY

types

Types supported by the upload. See https://www.npmjs.com/package/mime

['image', 'audio', 'video', 'application/pdf', 'application/vnd.', 'text']

Changelog

  • 2024-12-20 - Initial Documentation

Last updated

Was this helpful?