@armco/node-starter-kit

Modern plugin-based starter kit for Node.js applications with TypeScript, security, and observability

🎉 Version 2.0 Released!

We've completely revamped Node Starter Kit with a modern, plugin-based architecture. Check out what's new:

• ✅ Plugin Architecture - Modular, extensible design
• ✅ Dependency Injection - No more global state
• ✅ Modern Security - Fixed deprecated packages, added circuit breakers
• ✅ Health Checks - Kubernetes-ready probes
• ✅ TypeScript First - Full type safety
• ✅ Better DX - Fluent API, great documentation

👉 Read the full announcement →

📚 Choose Your Version

🚀 v2.0 (Recommended)

For new projects and those ready to modernize:

npm install @armco/[email protected]

• Quick Start Guide →
• Migration Guide →
• Examples →

import { Application } from '@armco/node-starter-kit/v2'
import { createLoggerPlugin } from '@armco/node-starter-kit/v2'

const nsk = await Application.create(app)
  .plugin(createLoggerPlugin())
  .build()

const logger = nsk.getContainer().resolve('logger')
logger.info('Hello from v2!')

📦 v1.x (Maintenance Mode)

For existing projects:

npm install @armco/[email protected]

• v1 Documentation →
• Security fixes only
• EOL: 6 months after v2.0 release

import initNodeStarterKit from '@armco/node-starter-kit'

initNodeStarterKit(app)
global.logger.info('Hello from v1')

🎯 Quick Comparison

| Feature | v1 | v2 | |---------|----|----| | Architecture | Monolithic | Plugin-based | | State Management | Global variables | DI Container | | TypeScript | Partial | Full | | CSRF Protection | ⚠️ Deprecated | ✅ Modern | | JWT Security | Basic | ⭐ Enhanced | | Health Checks | ❌ | ✅ | | Circuit Breaker | ❌ | ✅ | | Observability | Basic | Advanced | | Documentation | Limited | Comprehensive |

✨ Key Features

🔌 Plugin System

import { BasePlugin } from '@armco/node-starter-kit/v2'

class MyPlugin extends BasePlugin {
  name = 'my-plugin'
  version = '1.0.0'
  
  async install(ctx) {
    ctx.container.singleton('myService', new MyService())
  }
}

🛡️ Modern Security

import { initJwt, initCsrf } from '@armco/node-starter-kit/v2'

// JWT with algorithm allowlist
initJwt(app, {
  secretProvider: () => process.env.JWT_SECRET,
  algorithms: ['RS256', 'ES256'], // No "none" algorithm
  publicPaths: ['/health', '/auth/login']
})

// Modern CSRF (replaces deprecated csurf)
initCsrf(app, {
  secret: process.env.CSRF_SECRET,
  cookieOptions: { httpOnly: true, secure: true, sameSite: 'strict' }
})

🏥 Health Checks

import { HealthChecker } from '@armco/node-starter-kit/v2'

const healthChecker = new HealthChecker(nsk.getPluginManager(), config, logger)
app.use(healthChecker.createRouter())

// Kubernetes-ready endpoints:
// GET /health - Overall health
// GET /health/live - Liveness probe
// GET /health/ready - Readiness probe

🔄 Circuit Breaker

database: {
  uri: process.env.MONGO_URI,
  circuitBreaker: {
    enabled: true,
    threshold: 5,    // Open after 5 failures
    timeout: 60000,  // Try again after 1 minute
    onOpen: () => logger.error('Circuit opened!')
  }
}

💉 Dependency Injection

// Register services
nsk.getContainer().singleton('cache', new RedisCache())
nsk.getContainer().transient('requestId', () => uuid())

// Resolve anywhere
const cache = nsk.getContainer().resolve('cache')
const logger = nsk.getContainer().resolve('logger')

📖 Documentation

• v2 Quick Start - Complete usage guide
• Migration Guide - Upgrade from v1 to v2
• Examples - Working code samples
• v1 Overview - v1 documentation
• Issues & Spec - Design decisions
• Revamp Summary - What's changed

🚀 Quick Start

1. Install

npm install @armco/[email protected]

2. Create Config

Create armco.config.ts:

import { defineConfig } from '@armco/node-starter-kit/v2'

export default defineConfig({
  appName: 'my-app',
  
  plugins: {
    logger: { level: 'info' },
    database: { uri: process.env.MONGO_URI }
  },
  
  health: { enabled: true }
})

3. Initialize App

import express from 'express'
import { Application } from '@armco/node-starter-kit/v2'
import { createLoggerPlugin, createDatabasePlugin } from '@armco/node-starter-kit/v2'
import { initHelmet, initCors, initJwt } from '@armco/node-starter-kit/v2'

async function main() {
  const app = express()
  
  const nsk = await Application.create(app)
    .plugin(createLoggerPlugin())
    .plugin(createDatabasePlugin({ uri: process.env.MONGO_URI }))
    .build()
  
  const logger = nsk.getContainer().resolve('logger')
  
  initHelmet(app, {}, logger)
  initCors(app, { allowedOrigins: ['http://localhost:3000'] }, logger)
  
  app.get('/', (req, res) => {
    logger.info('Request received')
    res.json({ message: 'Hello World' })
  })
  
  app.listen(3000, () => logger.info('Server started on :3000'))
}

main().catch(console.error)

4. Run

export MONGO_URI="mongodb://localhost:27017/mydb"
npm start

Visit:

• http://localhost:3000 - Your app
• http://localhost:3000/health - Health check

🏢 Enterprise Features

• ✅ Production Ready - Battle-tested patterns
• ✅ Kubernetes Ready - Health probes, graceful shutdown
• ✅ Secure by Default - Modern security practices
• ✅ Observable - Structured logging, health checks
• ✅ Resilient - Circuit breakers, error handling
• ✅ Testable - DI makes testing easy
• ✅ Extensible - Plugin architecture
• ✅ Type Safe - Full TypeScript support

🛠️ Available Plugins

Official Plugins

• Logger - Winston with multiple transports
• Database - Mongoose with circuit breaker
• Health - Kubernetes-ready health checks

Community Plugins (Coming Soon)

• Socket.IO - Real-time communication
• Redis - Caching layer
• Scheduler - Cron jobs and task queues
• Metrics - Prometheus integration

🔒 Security

We take security seriously:

• ✅ No deprecated dependencies
• ✅ Algorithm allowlists for JWT
• ✅ Modern CSRF protection
• ✅ Secure secret management
• ✅ Regular security audits
• ✅ Dependency updates

Found a vulnerability? Email [email protected]

🤝 Contributing

We welcome contributions! Please see:

• CONTRIBUTING.md - Guidelines
• CODE_OF_CONDUCT.md - Community standards
• Issues - Bug reports

📜 License

ISC License - see LICENSE file for details

🙏 Acknowledgments

Built with ❤️ by the Armco team

Special thanks to:

• Node.js community
• Express.js team
• All our contributors

📞 Support

• 📧 Email: [email protected]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Docs: Documentation

🗺️ Roadmap

✅ Completed (v2.0)

• Plugin architecture
• Dependency injection
• Modern security
• Health checks
• Circuit breakers
• Full TypeScript

🚧 In Progress (v2.1)

• Metrics/Telemetry
• Socket.IO plugin
• Redis cache plugin

📋 Planned (v2.2+)

• GraphQL support
• Message queues
• CLI tool
• More database adapters

Get Started → | Examples → | Migrate →

Made with 💙 in India