Include Modules Guide

As your configurations grow, keeping everything in one file becomes messy. JSSON’s include statement lets you split your configs into logical, reusable modules. Let’s learn how! 🧩

Why Use Includes?

Without includes:

// One massive 500-line config file 😰
app {
  // 50 lines of app config...
}

database {
  // 100 lines of database config...
}

api {
  // 150 lines of API config...
}

// ... and so on

With includes:

// main.jsson - Clean and organized! 😎
include "app.jsson"
include "database.jsson"
include "api.jsson"

Much better, right?

Basic Usage

The include statement is simple:

include "path/to/file.jsson"

That’s it! The contents of the included file are merged into your main file.

Example: Database Config

database.jsson:

database {
host = "localhost"
port = 5432
name = myapp_db

pool {
  min = 2
  max = 10
}
}

main.jsson:

app {
name = "My Application"
version = "1.0.0"
}

include "database.jsson"

Result (JSON):

{
"app": {
  "name": "My Application",
  "version": "1.0.0"
},
"database": {
  "host": "localhost",
  "port": 5432,
  "name": "myapp_db",
  "pool": {
    "min": 2,
    "max": 10
  }
}
}

File Paths

JSSON resolves include paths relative to the file containing the include statement.

Relative Paths

// Same directory
include "database.jsson"

// Subdirectory
include "config/database.jsson"

// Parent directory
include "../shared/common.jsson"

Organizing Your Project

Here’s a recommended structure for large projects:

project/
├── config/
│   ├── main.jsson          # Main entry point
│   ├── app.jsson           # Application settings
│   ├── database.jsson      # Database config
│   ├── api.jsson           # API settings
│   └── environments/
│       ├── dev.jsson       # Development overrides
│       ├── staging.jsson   # Staging overrides
│       └── prod.jsson      # Production overrides

main.jsson:

// Core configuration
include "app.jsson"
include "database.jsson"
include "api.jsson"

// Environment-specific (choose one)
include "environments/dev.jsson"

Real-World Example

Let’s build a complete application configuration using modules.

app.jsson

app {
name = "E-Commerce Platform"
version = "2.1.0"
debug = false

features {
  newCheckout = true
  recommendations = true
  analytics = true
}
}

database.jsson

database {
primary {
  host = "db.example.com"
  port = 5432
  name = ecommerce_db
  ssl = true
}

replica {
  host = "db-replica.example.com"
  port = 5432
  readonly = true
}

pool {
  min = 5
  max = 20
  timeout = 30000
}
}

api.jsson

api {
baseUrl = "https://api.example.com"
version = "v2"
timeout = 5000

endpoints {
  products = "/products"
  users = "/users"
  orders = "/orders"
  payments = "/payments"
}

rateLimit {
  requests = 100
  window = 60
}
}

cache.jsson

cache {
redis {
  host = "cache.example.com"
  port = 6379
  ttl = 3600
}

strategies {
  products = aggressive
  users = moderate
  orders = minimal
}
}

main.jsson

// Main configuration file
include "app.jsson"
include "database.jsson"
include "api.jsson"
include "cache.jsson"

// Additional settings
monitoring {
enabled = true
service = datadog
apiKey = "your-api-key"
}

Now you have a clean, modular configuration that’s easy to maintain!

Multiple Includes

You can include as many files as you need:

include "app.jsson"
include "database.jsson"
include "api.jsson"
include "cache.jsson"
include "monitoring.jsson"
include "logging.jsson"

Files are processed in order, top to bottom.

Environment-Specific Configs

Use includes to handle different environments:

base.jsson (shared settings)

app {
name = "My App"
version = "1.0.0"
}

features {
analytics = true
logging = true
}

dev.jsson

include "base.jsson"

app {
debug = true
}

database {
host = localhost
port = 5432
}

prod.jsson

include "base.jsson"

app {
debug = false
}

database {
host = "prod-db.example.com"
port = 5432
ssl = true
}

Then use the appropriate file for each environment!

Best Practices

1. Organize by Concern

Group related settings together:

config/
├── app.jsson          # Application settings
├── database.jsson     # All database config
├── api.jsson          # API configuration
├── auth.jsson         # Authentication
└── monitoring.jsson   # Monitoring & logging

2. Use Descriptive Names

// Good ✅
include "database-config.jsson"
include "api-endpoints.jsson"

// Bad ❌
include "config1.jsson"
include "stuff.jsson"

3. Keep Includes at the Top

// Good ✅
include "database.jsson"
include "api.jsson"

app {
name = "My App"
}

// Bad ❌
app {
name = "My App"
}
include "database.jsson"  // Harder to see what's included

4. Don’t Nest Too Deeply

// Avoid this:
// main.jsson includes config.jsson
// config.jsson includes database.jsson
// database.jsson includes pool.jsson
// pool.jsson includes limits.jsson

// Keep it simple - 1-2 levels max

5. Document Your Includes

// Main configuration
// Includes: app, database, API, and cache settings

include "app.jsson"       // Application configuration
include "database.jsson"  // Database connection and pool
include "api.jsson"       // External API settings
include "cache.jsson"     // Redis cache configuration

Common Patterns

Pattern 1: Shared + Environment

config/
├── shared.jsson       # Common settings
├── dev.jsson          # Development (includes shared)
├── staging.jsson      # Staging (includes shared)
└── prod.jsson         # Production (includes shared)

Pattern 2: Feature Modules

config/
├── main.jsson
└── features/
    ├── auth.jsson
    ├── payments.jsson
    ├── notifications.jsson
    └── analytics.jsson

Pattern 3: Service-Based

config/
├── main.jsson
└── services/
    ├── database.jsson
    ├── cache.jsson
    ├── queue.jsson
    └── storage.jsson

Troubleshooting

File Not Found

Error: include file not found: database.jsson

Solution: Check that:

1. The file exists
2. The path is correct (relative to the including file)
3. The file extension is .jsson

Circular Dependencies

Error: circular include detected

Solution: Don’t have files include each other:

// ❌ Bad
// a.jsson includes b.jsson
// b.jsson includes a.jsson

// ✅ Good
// main.jsson includes both a.jsson and b.jsson

What’s Next?

Now that you can organize your configs with includes, explore more advanced features:

• Templates Guide — Structure tabular data efficiently
• Syntax Reference — Learn about ranges, expressions, and map clauses
• CLI Guide — Master the command-line tool

Happy modularizing! 🎯