A lightweight, intelligent SDK for detecting Railway environment in Node.js applications and automatically configuring PostgreSQL connections for Railway compatibility.
- 🚂 Smart Railway Detection - Automatically detect if your app is running on Railway
- 🔧 PostgreSQL Magic - Auto-configure PostgreSQL connections for Railway's SSL setup
- 🪶 Zero Dependencies - No external runtime dependencies (except optional logging)
- 📦 TypeScript First - Built with TypeScript, includes comprehensive type definitions
- 🎯 Simple API - Just a few functions, easy to use and understand
- 🔍 Intelligent Logging - Professional logging with WG Tech Labs log-engine integration
- ⚡ Performance Optimized - Minimal overhead, maximum efficiency
- 🛡️ Production Ready - Battle-tested and secure
# Using pnpm (recommended)
pnpm add @wgtechlabs/is-railway
# Using npm
npm install @wgtechlabs/is-railway
# Using yarn
yarn add @wgtechlabs/is-railwayimport { isRailway, getPostgresConfig } from '@wgtechlabs/is-railway';
// Check if running on Railway
if (isRailway()) {
console.log('🚂 Running on Railway!');
// Get Railway-optimized PostgreSQL config
const config = getPostgresConfig(process.env.POSTGRES_URL);
// Use the config with your PostgreSQL client
const pool = new Pool({
connectionString: config.connectionString,
ssl: config.ssl
});
}Detects if the current environment is Railway by checking for railway.internal hostnames in common environment variables.
import { isRailway } from '@wgtechlabs/is-railway';
if (isRailway()) {
// Configure for Railway environment
}Check if a specific URL is hosted on Railway.
import { isRailwayHost } from '@wgtechlabs/is-railway';
const isRailwayDB = isRailwayHost(process.env.DATABASE_URL);Get Railway-optimized PostgreSQL configuration.
import { getPostgresConfig } from '@wgtechlabs/is-railway';
const config = getPostgresConfig(process.env.DATABASE_URL, {
rejectUnauthorized: false, // Default for Railway
forceSSL: false
});
// Use with pg
const { Pool } = require('pg');
const pool = new Pool({
connectionString: config.connectionString,
ssl: config.ssl
});Get detailed Railway detection information.
import { getRailwayDetection } from '@wgtechlabs/is-railway';
const detection = getRailwayDetection();
console.log('Railway detected:', detection.isRailway);
console.log('Detected vars:', detection.detectedVars);
console.log('Railway hosts:', detection.railwayHosts);Get comprehensive Railway environment configuration.
import { getRailwayConfig } from '@wgtechlabs/is-railway';
const config = getRailwayConfig();
console.log('Environment:', config.environment); // 'railway' or 'local'
console.log('SSL settings:', config.ssl);The package automatically detects Railway by checking these core environment variables:
POSTGRES_URL- PostgreSQL database connection (Railway's primary database service)REDIS_URL- Redis connection (Railway's caching service)
These variables are checked for railway.internal hostnames to determine Railway environment.
import { getPostgresConfig } from '@wgtechlabs/is-railway';
// Custom SSL configuration
const config = getPostgresConfig(process.env.POSTGRES_URL, {
rejectUnauthorized: false, // Railway compatibility
forceSSL: true, // Force SSL even locally
enableLogging: true // Enable smart logging
});
const pool = new Pool({
connectionString: config.connectionString,
ssl: config.ssl,
max: 20, // Railway can handle more connections
idleTimeoutMillis: 30000
});import { isRailway, getRailwayConfig } from '@wgtechlabs/is-railway';
const railwayConfig = getRailwayConfig();
const appConfig = {
port: process.env.PORT || 3000,
ssl: railwayConfig.ssl,
environment: railwayConfig.environment,
// Railway-specific optimizations
...(railwayConfig.isRailway && {
trustProxy: true,
compression: true,
logging: 'info'
}),
// Local development settings
...(!railwayConfig.isRailway && {
cors: { origin: 'http://localhost:3000' },
logging: 'debug'
})
};import { isRailway, getPostgresConfig } from '@wgtechlabs/is-railway';
import { Pool } from 'pg';
class DatabaseManager {
private pool: Pool;
constructor() {
const config = getPostgresConfig(process.env.POSTGRES_URL);
this.pool = new Pool({
...config,
max: isRailway() ? 25 : 5, // Scale pool based on environment
ssl: config.ssl
});
// Railway-specific error handling
this.pool.on('error', (err, client) => {
console.error('Database error:', err);
if (isRailway()) {
// Railway-specific error reporting
this.reportToMonitoring(err);
}
});
}
async healthCheck() {
const railwayInfo = getRailwayConfig();
const client = await this.pool.connect();
try {
await client.query('SELECT 1');
return {
status: 'healthy',
environment: railwayInfo.environment,
isRailway: railwayInfo.isRailway
};
} finally {
client.release();
}
}
}The package includes optional integration with @wgtechlabs/log-engine for professional logging:
// Automatic smart logging when Railway overrides user preferences
const config = getPostgresConfig(process.env.POSTGRES_URL, {
rejectUnauthorized: true, // This will be overridden on Railway
enableLogging: true // Enable helpful warnings
});
// Console output on Railway:
// [11:32AM][WARN]: Railway detected: Overriding rejectUnauthorized=true to false for Railway compatibility
// Console output locally:
// [11:32AM][INFO]: Local environment detected: Added sslmode=disable for optimal PostgreSQL performanceFull TypeScript support with comprehensive type definitions:
import {
isRailway,
getPostgresConfig,
type PostgresConfig,
type RailwayDetectionResult
} from '@wgtechlabs/is-railway';
const config: PostgresConfig = getPostgresConfig(connectionString);
const detection: RailwayDetectionResult = getRailwayDetection();import { Pool } from 'pg';
import { getPostgresConfig } from '@wgtechlabs/is-railway';
const config = getPostgresConfig(process.env.DATABASE_URL);
const pool = new Pool({
connectionString: config.connectionString,
ssl: config.ssl
});import { isRailway } from '@wgtechlabs/is-railway';
const config = {
port: process.env.PORT || 3000,
ssl: isRailway() ? { rejectUnauthorized: false } : false,
logging: isRailway() ? 'error' : 'debug'
};import { getRailwayConfig } from '@wgtechlabs/is-railway';
const { environment, isRailway } = getRailwayConfig();
if (isRailway) {
// Railway-specific optimizations
app.set('trust proxy', true);
app.use(compression());
}Contributions are welcome! Please feel free to submit a Pull Request.
This project uses pnpm as the package manager for development:
# Install dependencies
pnpm install
# Build the project
pnpm build
# Run tests
pnpm test
# Run tests in watch mode
pnpm test:watch
# Run linter
pnpm lint
# Development with auto-rebuild
pnpm dev# This will clean, build, test, and publish
pnpm publishMIT © Waren Gonzaga
Made with ❤️ by WG Technology Labs
