@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/node-starter-kit@2.0.0

• 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/node-starter-kit@1.4.6

• 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/node-starter-kit@2.0.0

2. Create Config

Create armcorc.json (recommended) or armco.config.ts.

{
  "appName": "my-app",
  "plugins": {
    "logger": { "enabled": true, "level": "info" }
  },
  "middlewares": {
    "bodyParser": {
      "json": { "enabled": true },
      "urlencoded": { "enabled": true, "options": { "extended": true } }
    },
    "cookieParser": { "enabled": true },
    "helmet": {
      "enabled": true,
      "arOptions": { "whitelist": ["armco.dev"] },
      "libOptions": { "crossOriginResourcePolicy": { "policy": "cross-origin" } }
    },
    "cors": {
      "enabled": true,
      "arOptions": {
        "whitelist": ["http://localhost:3000", "https://armco.dev"],
        "supportedDomains": ["armco.dev"],
        "credentials": true
      }
    },
    "rateLimit": {
      "enabled": true,
      "arOptions": { "skipPaths": ["/health"] },
      "libOptions": { "windowMs": 900000, "max": 100 }
    }
  },
  "health": { "enabled": true, "endpoint": "/health" }
}

3. Initialize App

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

async function main() {
  const app = express()

  // You can register routes before build(); NSK will ensure configured middlewares
  // run before existing routes.
  app.get('/', (_req, res) => res.json({ ok: true }))

  const nsk = await Application.create(app)
    .build() // loads armcorc.json + starts plugins + injects configured middlewares

  const logger = nsk.getContainer().resolve('logger')
  logger.info('NSK initialized')

  app.listen(3000, () => logger.info('Server started on :3000'))
}

main().catch(console.error)

Notes

• Config is the source of truth: middlewares are injected only if configured in armcorc.json.
• arOptions vs libOptions: arOptions controls Armco behavior (like whitelists / url patterns), libOptions are passed to third-party libs.
• Lazy-loaded middleware libs: third-party middleware libraries are loaded only when that middleware is configured.

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/Prisma with circuit breaker
• Scheduler - Cron jobs with node-cron, timezone support, task management
• Socket.IO - Real-time communication with Redis adapter, JWT auth, namespaces
• Telemetry - OpenTelemetry with auto-instrumentation, multiple exporters
• Health - Kubernetes-ready health checks

Community Plugins (Coming Soon)

• Redis Cache - Distributed caching layer
• Metrics - Prometheus integration
• GraphQL - GraphQL server support

---

🔒 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 security@armco.tech

---

🤝 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: mohit.nagar@armco.tech
• 🐛 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)

• Redis cache plugin
• GraphQL support

📋 Planned (v2.2+)

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

---

Get Started → | Examples → | Migrate →

Made with 💙 in India