Skip to main content
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:
  1. Environment Variables - Highest priority, overrides everything
  2. Modelence Cloud - Synced configuration from cloud.modelence.com
  3. 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

VariableTypeDefaultConsumed by
MONGODB_URIstring—packages/modelence (database connection)
MONGODB_POOL_SIZEnumberdriver defaultpackages/modelence (pool size override)
MODELENCE_SITE_URLstring—packages/modelence (public site URL, used by auth callbacks and emails)
PORTnumber3000packages/modelence/app/server.ts
MODELENCE_PORTnumberfalls back to PORTpackages/modelence/app/server.ts
NODE_ENVdevelopment | productiondevelopmentBuild pipeline, cookie secure flag, Vite dev server
MODELENCE_LOG_LEVELdebug | info | warn | errorinfopackages/modelence/telemetry
MODELENCE_ENV_TYPEstring—packages/modelence/config (_system.env.type)
MODELENCE_MULTI_INSTANCEbooleanfalsepackages/modelence/config (_system.multiInstance)

​
Modelence Cloud

VariableTypeDefaultConsumed by
MODELENCE_SERVICE_ENDPOINTstringhttps://cloud.modelence.compackages/modelence/app (cloud API endpoint)
MODELENCE_SERVICE_TOKENstring—packages/modelence/app/backendApi.ts (cloud auth token, written by setup --token)
MODELENCE_CONTAINER_IDstring—packages/modelence/app/backendApi.ts (assigned per running container)
MODELENCE_ENVIRONMENT_IDstring—packages/modelence/app (cloud environment binding)
MODELENCE_TRACKING_ENABLEDbooleantruepackages/modelence/app (set to false to opt out of tracking)

​
Authentication (OAuth providers)

VariableTypeDefaultConsumed by
MODELENCE_AUTH_GOOGLE_ENABLEDbooleanfalsepackages/modelence/auth/providers/google.ts
MODELENCE_AUTH_GOOGLE_CLIENT_IDstring—packages/modelence/auth/providers/google.ts
MODELENCE_AUTH_GOOGLE_CLIENT_SECRETstring—packages/modelence/auth/providers/google.ts
MODELENCE_AUTH_GITHUB_ENABLEDbooleanfalsepackages/modelence/auth/providers/github.ts
MODELENCE_AUTH_GITHUB_CLIENT_IDstring—packages/modelence/auth/providers/github.ts
MODELENCE_AUTH_GITHUB_CLIENT_SECRETstring—packages/modelence/auth/providers/github.ts
MODELENCE_AUTH_GITHUB_CLIENT_SCOPESstring (comma-separated)read:user,user:emailpackages/modelence/auth/providers/github.ts

​
Email providers

VariableTypeDefaultConsumed by
MODELENCE_EMAIL_RESEND_API_KEYstring—@modelence/resend
MODELENCE_EMAIL_AWS_SES_REGIONstring—@modelence/aws-ses
MODELENCE_EMAIL_AWS_SES_ACCESS_KEY_IDstring—@modelence/aws-ses
MODELENCE_EMAIL_AWS_SES_SECRET_ACCESS_KEYstring—@modelence/aws-ses
MODELENCE_EMAIL_SMTP_HOSTstring—@modelence/smtp
MODELENCE_EMAIL_SMTP_PORTnumber—@modelence/smtp
MODELENCE_EMAIL_SMTP_USERstring—@modelence/smtp
MODELENCE_EMAIL_SMTP_PASSstring—@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:
  1. Navigate to your application
  2. Select your environment
  3. Open the Application tab
  4. 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