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`
`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`

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

When connected to Modelence Cloud, you can manage configuration through the cloud dashboard at cloud.modelence.com:

Navigate to your application
Select your environment
Open the Application tab
Configure settings like:
- Email providers
- Environment variables
- Database connections
- Custom configuration

Changes made in the cloud dashboard are automatically synced to your application when it starts.

Connecting to Modelence Cloud

npx modelence@latest setup --token <your_token>

This command creates a .modelence.env file with your cloud connection token.

See the Setup documentation for detailed instructions on connecting to Modelence Cloud.

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

Connecting to Modelence Cloud

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

​Connecting to Modelence Cloud

​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

Connecting to Modelence Cloud

Next Steps