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.

ATTENTION!

Do not commit sensitive information like passwords and API keys to your repository.

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

Configuring Novel | Novel

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

ATTENTION!

Do not commit sensitive information like passwords and API keys to your repository.

Using Sentry | Novel

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.

Configuration in these files are not dependent on the environment except if the config values reference environment variables.

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

Email Providers | Novel

Getting Postmark Keys | Novel

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

Getting Stripe Keys | Novel

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

Configuring Pricing | Novel

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']

Using AWS S3 | Novel

Using Cloudflare R2 | Novel

ATTENTION!

Do not commit sensitive information like passwords and API keys to your repository.

Changelog

• 2024-12-20 - Initial Documentation