Cloud

Cloud Platform

AxilJS cloud layer for multi-tenant SaaS - tenancy, audit, feature flags, rate limits, secrets, quotas, cache, correlation IDs, health, deploy manifests.

3 min readUpdated DocumentationEdit this page
On this page6

Overview

@axiljs/cloud is the cloud-native infrastructure layer for the AxilJS ecosystem. It provides the building blocks a multi-tenant SaaS application needs, with no third-party runtime dependencies.

Capabilities

  • Multi-tenancy with header, subdomain, JWT, or custom resolution strategies
  • Event-driven audit trails emitted on the global event bus, for SOC2, HIPAA, and GDPR workflows
  • Deterministic feature flag rollouts using FNV-1a hashing
  • Deployment manifests for Docker, Docker Compose, and Kubernetes
  • Per-tenant rate limiting with fixed-window (default) or sliding-window counters
  • AES-256-GCM secrets management with authenticated encryption
  • Tenant quota tracking with daily, monthly, and lifetime periods and warning events
  • TTL cache with LRU eviction and tag-based invalidation
  • Request and correlation ID propagation for distributed tracing
  • Multi-service health aggregation for gateway services
  • Operational monitoring dashboard that reads your Prometheus and health endpoints

Installation

❯npm install @axiljs/cloud
❯pnpm add @axiljs/cloud
❯yarn add @axiljs/cloud
❯bun add @axiljs/cloud

@axiljs/common and @axiljs/events (^0.3.3) are peer dependencies.

Both module systems work:

TypeScript
TS
// ESM
import { multiTenancy, featureFlags } from '@axiljs/cloud'
JavaScript
JS
// CommonJS
const { multiTenancy, featureFlags } = require('@axiljs/cloud')

Note

Fixed in 0.3.3: ESM import of @axiljs/cloud works. Earlier releases pointed the import condition at a dist/index.mjs file that was never built, so ESM apps failed to resolve the package. The package now exposes a single CommonJS entry that Node loads for both import and require.

Quick Start

TypeScript
TS
1import { Application } from '@axiljs/core'
2import {
3  multiTenancy,
4  auditMiddleware,
5  featureFlags,
6  tenantRateLimiter,
7  correlationId,
8  createDashboard,
9  getTenant
10} from '@axiljs/cloud'
11
12const app = new Application()
13
14app.use(correlationId())
15app.use(multiTenancy({
16  strategy: 'header',
17  resolveTenant: async (id) => ({ id, name: `Tenant ${id}`, status: 'active' }),
18}))
19app.use(tenantRateLimiter({
20  defaultRule: { max: 100, windowMs: 60_000 },
21}))
22app.use(auditMiddleware())
23
24featureFlags.define({
25  name: 'new-checkout',
26  enabled: true,
27  rolloutPercentage: 25,
28})
29
30app.get('/dashboard', createDashboard({
31  title: 'My SaaS Dashboard',
32  metricsEndpoint: '/metrics',
33  healthEndpoint: '/health',
34}))
35
36app.get('/api/data', (req, res) => {
37  const tenant = getTenant(req)
38  const enabled = featureFlags.isEnabled('new-checkout', {
39    tenantId: tenant.id,
40    userId: req.locals?.user?.id,
41  })
42  res.success({ tenant, feature: enabled })
43})
44
45app.listen(3000)

Note

multiTenancy() is registered globally here, so every route, including /dashboard, needs a valid x-tenant-id header or gets a 401. For public routes, apply multiTenancy() per route or on a mounted Router instead, or pass required: false.

What Changed in 0.3.3

  • ESM import of @axiljs/cloud works alongside CommonJS require.
  • SecretsManager warns about an auto-generated key only on first use, not at construction or import. See Secrets.
  • multiTenancy() rejects unknown, suspended, and archived tenants with 401 UNAUTHORIZED. See Multi-Tenancy.
  • Feature flags: allowedTenants: [] means "no allow-list" (all tenants); use enabled: false to turn a flag off. See Feature Flags.

Documentation

Was this page helpful?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY