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

### main.jsson
<Code lang="javascript" code={`// 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:

<Code lang="javascript" code={`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)
<Code lang="javascript" code={`app {
  name = "My App"
  version = "1.0.0"
}

features {
  analytics = true
  logging = true
}`} />

### dev.jsson
<Code lang="javascript" code={`include "base.jsson"

app {
  debug = true
}

database {
  host = localhost
  port = 5432
}`} />

### prod.jsson
<Code lang="javascript" code={`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

<Code lang="javascript" code={`// Good ✅
include "database-config.jsson"
include "api-endpoints.jsson"

// Bad ❌
include "config1.jsson"
include "stuff.jsson"`} />

### 3. Keep Includes at the Top

<Code lang="javascript" code={`// 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

<Code lang="javascript" code={`// 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

<Code lang="javascript" code={`// 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

## Includes and Multi-Format

Includes work seamlessly with **all** output formats. The merging happens *before* transpilation, so you can use includes to organize your config and then output to whatever format you need:

```bash
# Merge includes and output YAML
jsson -i main.jsson -f yaml > config.yaml

# Merge includes and output TypeScript
jsson -i main.jsson -f ts > config.ts

This makes JSSON a powerful way to manage complex configurations for any tool!

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! 🎯