Bloomneo AppKit 🚀

Minimal, framework-agnostic Node.js toolkit designed for AI agentic backend development. Previously published as @voilajsx/appkit. Same code, new home, new namespace. See migration below.

12 integrated modules. One pattern. Zero config to start, enterprise scaling on demand.

import { authClass, databaseClass, errorClass, loggerClass } from '@bloomneo/appkit';

const auth = authClass.get();
const database = await databaseClass.get();
const error = errorClass.get();
const logger = loggerClass.get('api');

app.post(
  '/api/users',
  auth.requireLoginToken(),                    // 1. authenticate the user
  auth.requireUserRoles(['admin.tenant']),     // 2. check the role (always chained)
  error.asyncRoute(async (req, res) => {
    if (!req.body?.email) throw error.badRequest('Email required');
    const user = await database.user.create({ data: req.body });
    logger.info('User created', { userId: user.id });
    res.json({ user });
  })
);

app.use(error.handleErrors());  // last middleware

Production-ready API with auth, database, error handling, logging. Zero config files.

---

🤖 For AI coding agents — read these first

Three files at the package root tell agents everything they need to know:

File	Purpose
AGENTS.md	Rules: always-do, never-do, canonical patterns. Read first.
llms.txt	Reference: every export, every method, signatures + examples.
examples/	12 minimal .ts files, one per module. Copy and modify.
cookbook/	Composed recipes for whole patterns (CRUD, multi-tenant, file upload, real-time).

All four ship inside the npm tarball. AI agents installing @bloomneo/appkit can read them directly from node_modules/@bloomneo/appkit/.

---

🚀 Quick start

As a library (in any Node.js project)

npm install @bloomneo/appkit

import { authClass } from '@bloomneo/appkit/auth';
import { databaseClass } from '@bloomneo/appkit/database';

const auth = authClass.get();
const database = await databaseClass.get();

As a complete scaffold (CLI)

npm install -g @bloomneo/appkit
appkit generate app myproject
cd myproject && npm run dev:api

→ Production-ready Express API at http://localhost:3000 with auth, database, logging, error handling all wired.

For full-stack scaffolding (frontend + backend), use @bloomneo/bloom which assembles AppKit + UIKit + FBCA convention into one CLI.

---

✨ The one rule that matters most

const auth = authClass.get();   // ALWAYS .get(), NEVER `new AuthClass()`

Every module follows this exact pattern. There are no exceptions, no constructors, no factories with custom names.

const auth     = authClass.get();
const database = await databaseClass.get();
const error    = errorClass.get();
const cache    = cacheClass.get();           // default 'app' namespace
const userCache = cacheClass.get('users');   // custom namespace
const logger   = loggerClass.get('api');     // component-tagged

One function per module. Predictable. Non-ambiguous. AI-agent friendly.

---

🎭 The 12 modules

#	Module	Purpose	Auto-scales
1	Auth	JWT tokens, role.level permissions, middleware	—
2	Database	Prisma/Mongoose with multi-tenant filtering	per-org databases
3	Security	CSRF, rate limiting, AES-256-GCM, input sanitization	—
4	Error	HTTP errors with semantic types + middleware	—
5	Cache	Memory → Redis	REDIS_URL
6	Storage	Local → S3/R2	AWS_S3_BUCKET
7	Queue	Memory → Redis → DB	REDIS_URL / BLOOM_QUEUE_DB
8	Email	Console → SMTP → Resend	RESEND_API_KEY
9	Event	Memory → Redis pub/sub	REDIS_URL
10	Logger	Console → File → HTTP	BLOOM_LOGGER_*
11	Config	Type-safe env var access	—
12	Util	Safe property access, debounce, chunk, uuid, slugify	—

For full method signatures and per-module examples, read llms.txt.

---

🌍 Environment-driven progressive scaling

Same code. Different .env. Enterprise features automatically enabled.

# Day 1 — local development (zero config)
BLOOM_AUTH_SECRET=<min 32 chars>
DATABASE_URL=postgresql://localhost/myapp
# → Memory cache, local file storage, console logs, console email

# Month 6 — production (just add env vars, no code changes)
REDIS_URL=redis://prod-cache:6379         # → distributed cache + queue
AWS_S3_BUCKET=prod-assets                 # → cloud storage + CDN
RESEND_API_KEY=re_production_key          # → professional email
BLOOM_DB_TENANT=auto                      # → multi-tenant filtering
BLOOM_LOGGER_HTTP_URL=https://logs.example.com  # → centralized logging

See examples/.env.example for the full canonical template.

---

🛠️ AppKit CLI

Project generation:

appkit generate app myproject       # full backend scaffold (Express + auth + db + error + logger)

Feature generation:

appkit generate feature product     # basic feature (route + service + types)
appkit generate feature order --db  # database-enabled feature (+ model + HTTP tests)
appkit generate feature user        # complete authentication system (9-role hierarchy)

Generated project structure:

myproject/
├── AGENTS.md                       # ← copied from @bloomneo/appkit at scaffold time
├── llms.txt                        # ← copied from @bloomneo/appkit at scaffold time
├── .env                            # ← contains generated BLOOM_AUTH_SECRET
├── src/api/
│   ├── server.ts                   # Express bootstrap
│   ├── lib/api-router.ts           # auto-discovery routing
│   └── features/
│       ├── welcome/
│       └── [your-features]/
└── package.json

---

🏗️ Migration

From @voilajsx/appkit

Two breaking changes between @voilajsx/appkit@1.2.8 and @bloomneo/appkit@1.5.2:

1. The npm scope changed. Project-wide find-and-replace:

- import { authClass } from '@voilajsx/appkit/auth';
+ import { authClass } from '@bloomneo/appkit/auth';

2. The env var prefix changed. This is a hard cutover with no fallback:

- VOILA_AUTH_SECRET=...
+ BLOOM_AUTH_SECRET=...

- VOILA_SECURITY_CSRF_SECRET=...
+ BLOOM_SECURITY_CSRF_SECRET=...

- VOILA_DB_TENANT=auto
+ BLOOM_DB_TENANT=auto

Every VOILA_* in your .env files needs to become BLOOM_*. There is no deprecation period — the legacy prefix is gone.

Rationale: the rebrand was a clean break, the env var prefix was the last remaining piece of legacy branding, and shipping a backwards-compat shim just kept the old name visible in error messages and docs forever.

From @bloomneo/appkit@1.5.1 → 1.5.2

Same env var rename as above. Source code (imports + module API) is unchanged. The breaking change is only the env var prefix.

---

📚 Resources

• AGENTS.md — agent-facing rules and conventions
• llms.txt — full machine-readable API reference
• examples/ — one minimal example per module
• cookbook/ — composed recipes (auth + crud, multi-tenant, file upload, real-time)
• CHANGELOG.md — release history
• Per-module READMEs on GitHub — long-form human docs (not shipped in tarball)
• Issues: https://github.com/bloomneo/appkit/issues

---

📄 License

MIT © Krishna Teja GS

---

🚀 Built for the AI-first future of backend development
Where enterprise applications are generated, not written

⭐ Star on GitHub