npm package: @shellapps/config
Description: Configuration management for ShellApps ecosystem
Author: Alex Hewitt-Procter
Latest version: 1.15.2

# @shellapps/config

Configuration management for the ShellApps ecosystem. This package provides environment-specific configuration for all ShellApps and ShellLabs services.

## Installation

```bash
npm install @shellapps/config
```

## Usage

### Basic Usage

```typescript
import { getConfig } from '@shellapps/config';

const config = getConfig();
console.log(config.serviceUrls.apps); // https://apps.shellapps.com (in production)
```

### Environment Configuration

The package reads the `SHELLAPPS_ENV` environment variable to determine which configuration to load:

- `development` (default) - Local development with localhost URLs
- `staging` - Staging environment with *.shellapps.net / *.shelllabs.net domains  
- `production` - Production environment with *.shellapps.com / *.shelllabs.net domains

```bash
# Set environment
export SHELLAPPS_ENV=production

# Or inline
SHELLAPPS_ENV=staging node app.js
```

### Specific Configuration Getters

```typescript
import { 
  getServiceUrls, 
  getS3Config, 
  getMongoConfig, 
  getFeatureFlags,
  getEnvironment 
} from '@shellapps/config';

// Get current environment
const env = getEnvironment(); // 'development' | 'staging' | 'production'

// Get service URLs
const urls = getServiceUrls();
console.log(urls.auth);    // Auth service URL
console.log(urls.apps);    // Main apps URL
console.log(urls.blog);    // Blog URL
console.log(urls.admin);   // ShellLabs admin URL

// Get S3 configuration
const s3 = getS3Config();
console.log(s3.buckets.assets);  // Asset bucket name
console.log(s3.buckets.uploads); // Upload bucket name

// Get MongoDB configuration
const mongo = getMongoConfig();
console.log(mongo.database);     // Database name
console.log(mongo.authDatabase); // Auth database name

// Get feature flags
const flags = getFeatureFlags();
console.log(flags.someFeature); // boolean value
```

### Default Export

```typescript
import config from '@shellapps/config';

const appConfig = config.getConfig();
const serviceUrls = config.getServiceUrls();
const s3Config = config.getS3Config();
```

### TypeScript Types

All configuration objects are fully typed:

```typescript
import type { 
  Config, 
  Environment, 
  ServiceUrls, 
  S3Config, 
  MongoConfig, 
  FeatureFlags 
} from '@shellapps/config';

function setupApp(config: Config) {
  // TypeScript will provide full intellisense and type checking
  const authUrl = config.serviceUrls.auth;
  const assetBucket = config.s3.buckets.assets;
}
```

## Configuration Structure

### Service URLs

- **Development**: All services run on localhost with different ports
- **Staging**: Uses *.shellapps.net and *.shelllabs.net domains
- **Production**: Uses *.shellapps.com and *.shelllabs.net domains

### S3 Buckets

Environment-specific bucket names:
- Assets bucket: `shellapps-{env}-assets`
- Uploads bucket: `shellapps-{env}-uploads`  
- Backups bucket: `shellapps-{env}-backups`

### MongoDB

Environment-specific database names:
- Development: `shellapps_dev`
- Staging: `shellapps_staging` 
- Production: `shellapps_production`

### Feature Flags

Object structure for enabling/disabling features per environment. Add flags as needed:

```typescript
// In your app code
const flags = getFeatureFlags();
if (flags.newDashboard) {
  // Show new dashboard
}
```

## Error Handling

The package throws descriptive errors for invalid configurations:

```typescript
// If SHELLAPPS_ENV=invalid
try {
  const config = getConfig();
} catch (error) {
  console.error(error.message); 
  // "Invalid environment: invalid. Must be one of: development, staging, production"
}
```

## Development

```bash
# Install dependencies
npm install

# Build the package
npm run build

# Watch for changes during development
npm run dev

# Clean build artifacts
npm run clean
```

## License

MIT