Settings Configuration

The src/settings.ts file is the central configuration hub for your StratusTS application. This guide explains every configuration option in simple, easy-to-understand language.

Overview

Your settings file controls:

• Which port your server runs on
• Which apps are loaded
• How to connect to databases
• Where templates are stored

Here’s what a typical settings file looks like:

src/settings.ts

import type { DatabaseType, SettingsType } from 'stratus-ts';

const PORT = 2000;
const APPS = ['users', 'blog'];
const DATABASE: DatabaseType = false;
const TEMPLATE_DIR = 'templates';

export default {
  PORT,
  APPS,
  DATABASE,
  TEMPLATE_DIR,
} satisfies SettingsType;

Let’s break down each setting in detail.

PORT - Server Port

What It Does

The PORT setting determines which port number your server listens on.

src/settings.ts

const PORT = 2000;

Understanding Ports

Think of ports as doors to your server:

• Port 80: Standard HTTP (web browsers)
• Port 443: Standard HTTPS (secure web)
• Port 3000: Common for Node.js development
• Port 2000: StratusTS default

Your server URL becomes: http://localhost:PORT

Common Values

src/settings.ts

const PORT = 2000;  // Default - good for development
const PORT = 3000;  // Popular alternative
const PORT = 8080;  // Common for APIs
const PORT = 4000;  // Any available port works

Using Environment Variables

For production, use environment variables:

src/settings.ts

const PORT = process.env.PORT ? parseInt(process.env.PORT) : 2000;

Why? Production servers (Heroku, Railway, etc.) assign ports dynamically.

Example: Dynamic Port Configuration

src/settings.ts

// Development: Use 2000
// Production: Use whatever the hosting platform provides
const PORT = process.env.ENV === 'prod'
  ? parseInt(process.env.PORT || '8080')
  : 2000;

Troubleshooting

“Port already in use” error?

Change to a different port:

src/settings.ts

const PORT = 3000;  // Try different numbers until one works

Or find and stop the process using that port:

terminal

# On macOS/Linux
lsof -ti:2000 | xargs kill -9

# On Windows
netstat -ano | findstr :2000
taskkill /PID <process_id> /F

APPS - Installed Applications

What It Does

The APPS array lists all the apps your application should load.

src/settings.ts

const APPS = ['users', 'blog', 'api'];

How It Works

When your server starts:

1. StratusTS reads this array
2. Finds each app directory in src/
3. Imports routes.ts from each app
4. Registers all routes automatically

No manual route configuration needed!

Empty Apps (Default)

src/settings.ts

const APPS = []; // No apps loaded

Use this when you first create a project. Add apps as you build them.

Single App

src/settings.ts

const APPS = ['users'];  // Only users app is loaded

Multiple Apps

src/settings.ts

const APPS = [
  'users',
  'blog',
  'api',
  'admin',
];

Order matters! Apps are loaded in this order. If two apps define the same route, the first one wins.

Example: Adding a New App

1. Create the app:

terminal

st create app payments

2. Add to settings:

src/settings.ts

const APPS = [
    'users',
    'blog',
    'payments',  // New app added
  ];

3. Start your development server — routes are now active!

Best Practices

Keep it organized:

src/settings.ts

const APPS = [
  // Core functionality
  'users',
  'auth',

  // Features
  'blog',
  'shop',

  // Admin
  'admin',
];

Start small, grow as needed:

src/settings.ts

// Small project
const APPS = ['api'];

// As it grows
const APPS = ['users', 'blog', 'api'];

// Larger project
const APPS = ['users', 'blog', 'api', 'admin', 'notifications'];

TEMPLATE_DIR - Template Directory

What It Does

Specifies where your EJS template files are stored.

src/settings.ts

const TEMPLATE_DIR = 'templates';

Understanding the Path

The path is relative to your project root:

src/settings.ts

const TEMPLATE_DIR = 'templates';

// Results in:
my-project/
├── templates/        ← Templates go here
│   ├── home.ejs
│   └── about.ejs
├── src/
└── package.json

Default Configuration

src/settings.ts

const TEMPLATE_DIR = 'templates';

This is the default and works for most projects.

Custom Locations

You can change where templates are stored:

src/settings.ts

const TEMPLATE_DIR = 'views';  // Common alternative

my-project/
├── views/            ← Templates here now
└── src/

src/settings.ts

const TEMPLATE_DIR = 'src/templates';  // Inside src

my-project/
└── src/
  ├── templates/    ← Templates here
  └── settings.ts

Nested Structure Example

src/settings.ts

const TEMPLATE_DIR = 'templates';

// Organize templates in subdirectories:
templates/
├── layouts/
│   └── base.ejs
├── partials/
│   ├── header.ejs
│   └── footer.ejs
└── pages/
  ├── home.ejs
  ├── about.ejs
  └── contact.ejs

When to Change It

Keep default ('templates') unless:

• Your team prefers views (common in Express)
• You want templates inside src directory
• You have a specific directory structure requirement

Using Templates

Once configured, render templates in controllers:

src/users/controllers.ts

const homeController: ControllerType = (question, reply) => {
  reply.render(reply, 'pages/home', {
    title: 'Home Page',
    user: { name: 'Alice' },
  });
};

Note: Path is relative to TEMPLATE_DIR:

• TEMPLATE_DIR = 'templates'
• Template at: templates/pages/home.ejs
• Use: 'pages/home'

If You Don’t Use Templates

If you’re building a pure API without HTML pages:

src/settings.ts

const TEMPLATE_DIR = 'templates';  // Keep it, even if unused

It won’t hurt to leave it—just don’t create template files.

Complete Configuration Examples

Example 1: Simple API (No Database, No Templates)

src/settings.ts

import type { DatabaseType, SettingsType } from 'stratus-ts';

const PORT = 3000;
const APPS = ['api'];
const DATABASE: DatabaseType = false;
const TEMPLATE_DIR = 'templates';

export default {
  PORT,
  APPS,
  DATABASE,
  TEMPLATE_DIR,
} satisfies SettingsType;

Example 2: Full-Stack App with PostgreSQL

Upcomming

Example 3: Development vs Production

Upcomming

Best Practices

1. Use Environment Variables for Secrets

❌ Don’t do this:

src/settings.ts

password: 'my_secret_password',  // NEVER commit passwords!

✅ Do this:

src/settings.ts

password: process.env.DB_PASSWORD || '',

2. Set Defaults for Development

Upcomming

3. Keep Settings Simple

Don’t overcomplicate your settings file:

src/settings.ts

// Good - clear and simple
const PORT = 2000;

// Overkill - too complex
const PORT = parseInt(
  process.env.PORT ||
  process.env.APP_PORT ||
  process.env.SERVER_PORT ||
  '2000'
);

4. Document Custom Configuration

Add comments for non-obvious settings:

src/settings.ts

// Using custom port because 2000 conflicts with another service
const PORT = 3500;

// Only loading public-facing apps, admin is separate deployment
const APPS = ['users', 'blog', 'api'];

5. Validate Configuration

Upcomming

Testing Your Configuration

Check Current Settings

Add a debug script to see your configuration:

src/settings.ts

const SETTINGS = {
  PORT,
  APPS,
  DATABASE,
  TEMPLATE_DIR,
} satisfies SettingsType;

// In development, log settings
if (process.env.NODE_ENV !== 'production') {
  console.log('Current settings:', SETTINGS);
}

export default SETTINGS;

Verify Database Connection

Test your database configuration:

terminal

pnpm dev # or npm run dev

Look for:

terminal

database connected successfully
server running on port : 2000

If you see connection errors, review your database settings.

Next Steps

Now that you understand configuration:

• Creating Apps - Master app architecture