Environment & Setup

Modelence provides flexible configuration options for your application. You can configure your app through the startApp() function, environment variables, and Modelence Cloud settings.

Configuration Methods

There are three ways to configure your Modelence application, listed in order of precedence:

Environment Variables - Highest priority, overrides everything
Modelence Cloud - Synced configuration from cloud.modelence.com
startApp() Options - Direct code configuration, lowest priority

Environment variables always take precedence, allowing you to override any configuration when deploying to different environments.

Basic Configuration with startApp()

The startApp() function is your application’s entry point where you configure core settings:

src/server/app.ts

import { startApp } from 'modelence/server';
import todoModule from './todo';
import userModule from './users';

startApp({
  // Register your modules
  modules: [todoModule, userModule],

  // Email configuration
  email: {
    provider: resendProvider,
    from: 'noreply@yourapp.com'
  }
});

Environment Variables

Environment variables provide a way to configure your application without hardcoding values. They override all other configuration methods.

Core Environment Variables

.modelence.env

# MongoDB connection string
MONGODB_URI="mongodb+srv://user:pass@cluster.mongodb.net/myapp"

# Server configuration
PORT=3000
MODELENCE_SITE_URL=http://localhost

All Environment Variables

Every MODELENCE_* variable (plus the few non-prefixed ones) that the framework or first-party packages read. Anything not listed here is application-specific and should go through defineConfigs / getConfig instead.

Core

Variable	Type	Default	Consumed by
`MONGODB_URI`	string	—	`packages/modelence` (database connection)
`MONGODB_POOL_SIZE`	number	driver default	`packages/modelence` (pool size override)
`MODELENCE_SITE_URL`	string	—	`packages/modelence` (public site URL, used by auth callbacks and emails)
`PORT`	number	`3000`	`packages/modelence/app/server.ts`
`MODELENCE_PORT`	number	falls back to `PORT`	`packages/modelence/app/server.ts`
`MODELENCE_TRUSTED_PROXIES`	string (comma-separated addresses/ranges)	all proxies trusted for backward compatibility	`packages/modelence/app/server.ts`
`NODE_ENV`	`development` \| `production`	`development`	Build pipeline, cookie `secure` flag, Vite dev server
`MODELENCE_LOG_LEVEL`	`debug` \| `info` \| `warn` \| `error`	`info`	`packages/modelence/telemetry`
`MODELENCE_ENV_TYPE`	string	—	`packages/modelence/config` (`_system.env.type`)
`MODELENCE_MULTI_INSTANCE`	boolean	`false`	`packages/modelence/config` (`_system.multiInstance`)

Modelence Cloud

Variable	Type	Default	Consumed by
`MODELENCE_SERVICE_ENDPOINT`	string	`https://cloud.modelence.com`	`packages/modelence/app` (cloud API endpoint)
`MODELENCE_SERVICE_TOKEN`	string	—	`packages/modelence/app/backendApi.ts` (cloud auth token, written by `setup --token`)
`MODELENCE_CONTAINER_ID`	string	—	`packages/modelence/app/backendApi.ts` (assigned per running container)
`MODELENCE_ENVIRONMENT_ID`	string	—	`packages/modelence/app` (cloud environment binding)
`MODELENCE_TRACKING_ENABLED`	boolean	`true`	`packages/modelence/app` (set to `false` to opt out of tracking)

Authentication (OAuth providers)

Variable	Type	Default	Consumed by
`MODELENCE_AUTH_GOOGLE_ENABLED`	boolean	`false`	`packages/modelence/auth/providers/google.ts`
`MODELENCE_AUTH_GOOGLE_CLIENT_ID`	string	—	`packages/modelence/auth/providers/google.ts`
`MODELENCE_AUTH_GOOGLE_CLIENT_SECRET`	string	—	`packages/modelence/auth/providers/google.ts`
`MODELENCE_AUTH_GITHUB_ENABLED`	boolean	`false`	`packages/modelence/auth/providers/github.ts`
`MODELENCE_AUTH_GITHUB_CLIENT_ID`	string	—	`packages/modelence/auth/providers/github.ts`
`MODELENCE_AUTH_GITHUB_CLIENT_SECRET`	string	—	`packages/modelence/auth/providers/github.ts`
`MODELENCE_AUTH_GITHUB_CLIENT_SCOPES`	string (comma-separated)	`read:user,user:email`	`packages/modelence/auth/providers/github.ts`
`MODELENCE_AUTH_MOBILE_REDIRECT_URLS`	string (comma-separated)	—	`packages/modelence/auth/providers/mobileRedirect.ts` (deep links native OAuth may return to, e.g. `myapp://auth`; merged with `auth.mobile.redirectUrls`)

Email providers

Variable	Type	Default	Consumed by
`MODELENCE_EMAIL_RESEND_API_KEY`	string	—	`@modelence/resend`
`MODELENCE_EMAIL_AWS_SES_REGION`	string	—	`@modelence/aws-ses`
`MODELENCE_EMAIL_AWS_SES_ACCESS_KEY_ID`	string	—	`@modelence/aws-ses`
`MODELENCE_EMAIL_AWS_SES_SECRET_ACCESS_KEY`	string	—	`@modelence/aws-ses`
`MODELENCE_EMAIL_SMTP_HOST`	string	—	`@modelence/smtp`
`MODELENCE_EMAIL_SMTP_PORT`	number	—	`@modelence/smtp`
`MODELENCE_EMAIL_SMTP_USER`	string	—	`@modelence/smtp`
`MODELENCE_EMAIL_SMTP_PASS`	string	—	`@modelence/smtp`

Any variable not listed here is application-specific. Define it through your modules’ configSchema so Modelence Cloud can manage it and getConfig() can read it type-safely.

Modelence Cloud Configuration

On Modelence Cloud, the environment’s variables and its configSchema values reach the app when it starts, both when it is deployed and when it runs locally in a connected environment. See Environment Variables for what the platform provides and how variables are declared, and Local Setup for connecting a project on your machine.

Next Steps

Authentication

Configure authentication and user management

Email Setup

Set up email providers for transactional emails

Roles & Permissions

Define user roles and permissions

WebSockets

Enable real-time communication

Get Started

Core Concepts

Features

Tutorials

Environment & Setup

Configuration Methods

Basic Configuration with startApp()

Environment Variables

Core Environment Variables

All Environment Variables

Core

Modelence Cloud

Authentication (OAuth providers)

Email providers

Modelence Cloud Configuration

Next Steps

Authentication

Email Setup

Roles & Permissions

WebSockets

​Configuration Methods

​Basic Configuration with startApp()

​Environment Variables

​Core Environment Variables

​All Environment Variables

​Core

​Modelence Cloud

​Authentication (OAuth providers)

​Email providers

​Modelence Cloud Configuration

​Next Steps

Authentication

Email Setup

Roles & Permissions

WebSockets

Configuration Methods

Basic Configuration with startApp()

Environment Variables

Core Environment Variables

All Environment Variables

Core

Modelence Cloud

Authentication (OAuth providers)

Email providers

Modelence Cloud Configuration

Next Steps