Skip to content
techmefrPublic

About

The batteries-included framework for NestJS: generate secured, multi-tenant resources from a blueprint, then own every line. Auth, RBAC, Postgres RLS, jobs, real time, vector search, OpenAPI.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

367 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

HeryJs

The batteries-included framework for NestJS.
Generate secured, multi-tenant resources from a blueprint. Then own every line.

Documentation · Getting started · What's included · Security · Contributing

License: MIT Node >=22.12 NestJS PostgreSQL


NestJS gives you an excellent runtime and then stops at the plumbing. Auth, permissions, tenancy, jobs, real-time, audit, search: every project assembles them again, slightly differently, and the rules drift between the backend and the frontend.

HeryJs is the missing layer — the way Nuxt sits on Vue, or Laravel gives PHP a home. A CLI scaffolds a project, generates fully wired resources into it, and installs the pieces most backends end up building by hand. Nothing re-syncs, nothing compiles a schema at request time. What you get is a plain, readable NestJS codebase from the first commit, and it is yours.

pnpm dlx heryjs new my-app

Why HeryJs

  • Generate once, then disappear. hery generate writes real NestJS files — module, controller, service, policy, DTOs, view, factory, spec. The blueprint is never read again. There is no runtime magic to outlive, and no platform whose lifecycle you depend on.
  • Secure by construction, and proven. Every route carries a capability decision or a stated reason it cannot, and a rate-limit bucket. A route with neither fails CI. Every generated resource ships a test suite that boots the real app against a real database and proves the 403, the tenant boundary and the scope parity.
  • Tenancy is the foundation. The tenant is resolved once per request and enforced twice: in the Prisma client and by a Postgres row-level policy that fails closed.
  • Decisions, not rules, reach the client. Permissions resolve server-side into plain { allowed, scope } decisions attached to the data. The frontend renders them; the backend re-checks everything, every time.
  • Built to be read by machines too. Every domain has the same files, named after the resource, and an architecture linter fails CI on a folder that breaks the shape. A person or a coding agent knows exactly where to look.

Getting started

pnpm dlx heryjs new my-app
cd my-app
cp .env.example .env
pnpm install
pnpm hery up --start      # compose services, ports written back to .env
pnpm hery migrate --name init
pnpm start:dev

Then generate your first resource:

pnpm hery create:blueprint BlogPost
pnpm hery generate blueprints/blog-post.yaml

heryjs new scaffolds a standalone project: the kernel, the CLI and every module's package ready for pnpm hery install, none of HeryJs's own demo or docs. Only three modules come installed, because their install writes into kernel files: impersonation, two-factor and push. The CLI travels into the project, so every later command is pnpm hery from inside it. There is nothing global to install and nothing to keep in step with a release.

What a blueprint gives you

A blueprint is a short description of intent: fields, relations, permission presets.

name: BlogPost
fields:
  - name: title
    type: string
    translatable: true
  - name: body
    type: string
  - name: embedding
    type: vector
    dimensions: 1536
    source: body

One hery generate later you have ten files in functional/blog-post/ and a Prisma model, and the resource already comes with:

search One route for listing and reading, with filters, sorting, relations, cursor pagination, ETag and similarity search
mutate Create, update, soft-delete and restore, each taking an array, with an atomic mode and a per-entry report
Capabilities Permission decisions returned with the data, computed in memory, no per-row query
Isolation Tenant scoping underneath permissions, enforced by Prisma and by Postgres RLS
Concurrency Optional optimistic versioning, and Idempotency-Key on every mutating route
Real time A change feed over SSE and WebSocket, filtered per subscriber by its own permissions
Contract An OpenAPI 3.1 document and a typed client generated from the blueprint
Tests A generated suite proven for every resource, not only the example

What's included

A kernel that is always there, and modules you install only when you need them (pnpm hery module:list, pnpm hery install <name>). A new project comes with impersonation, two-factor and push already installed, since the kernel depends on them. Every other module listed below is installed when you ask for it.

In the kernel

  • Identity — sessions, API keys, passwordless sign-in (magic link, email and phone OTP, passkeys), guest sessions, login lockout and session management
  • Access — capabilities and scopes, teams, tenancy with Postgres row-level security, admin impersonation with a bounded session
  • Reliability — BullMQ jobs with a retry policy and a dashboard, a scheduler, a transactional outbox, distributed locks, idempotency, rate limiting on by default
  • Data — migrations, seeders, factories, database branches, encrypted fields with key rotation, retention and pruning, translatable content fields
  • Operations — health probes, Prometheus metrics, OpenTelemetry traces, metrics and logs, an error-reporter contract, maintenance mode, structured log shipping, a request inspector and a persisted dev dashboard
  • Delivery — OpenAPI and a typed client, feature flags, an audit trail with a canonical hash chain, hery doctor, and an architecture linter

As modules

  • Auth — two-factor (TOTP), social sign-in (OAuth), enterprise single sign-on (OIDC), SCIM provisioning
  • Communication — mail, SMS, push, and a notifier that composes them with per-user preferences, quiet hours and digests
  • Real time — WebSocket, server-sent events, WebRTC signalling, LiveKit streaming
  • Search — Prisma, Elasticsearch and Meilisearch drivers, plus vector search on pgvector with an embeddings module
  • APIs — GraphQL, an MCP gateway for agents, inbound and outbound webhooks (HMAC-signed, retried, dead-lettered), an outbound HTTP client with a fake driver for tests
  • Data in and out — file storage with presigned uploads, CSV, XLSX and PDF export, import
  • Money — billing that mirrors a provider's subscription state and guards a quota (Stripe driver)
  • Admin — a dashboard that every module contributes a section to, with no registry to maintain

Every module follows one convention: a module exposes one capability, a driver is one way of performing it, and swapping a transport is a line in hery.config.ts rather than a source edit. All of them are published as @heryjs/<name> and versioned with the kernel. See Modules and drivers and Publishing a module.

Where it stops

HeryJs covers a common backend core and says plainly what it does not.

  • Metering ships per-tenant limits and usage counts, in the database, readable in the admin. Pricing that usage, meaning usage-based billing, is not shipped.
  • API only. There is no server-rendered view layer; the admin dashboard is the one UI.

For anything outside that core, you write ordinary NestJS in a clean, conventional project. HeryJs never gets in the way, and it does not pretend to replace judgment.

Security

Every request goes through the same four steps — who is calling, which tenant, what they may do, what they sent — and the tenant boundary is enforced in the Prisma client and again by a Postgres policy. The security model, and what it deliberately leaves to you, is written out in the security guide. To report a vulnerability, see SECURITY.md.

Working on the framework

A clone of this repository is the framework itself — the demo resource, the docs site and the module workspaces — not a starting point for an application:

git clone https://github.com/techmefr/HeryJs.git
cd HeryJs
pnpm install
pnpm run db:generate
pnpm hery up --start

Contributing

HeryJs is built in the open and is still small enough that one conversation with a maintainer can shape its direction. If you generate a resource and something feels off, or you have a use case the current conventions do not cover, open an issue. Pull requests are welcome, especially ones that follow the project's own discipline: prove it end to end, then keep only what is proven. See CONTRIBUTING.md and the changelog.

License

MIT

About

The batteries-included framework for NestJS: generate secured, multi-tenant resources from a blueprint, then own every line. Auth, RBAC, Postgres RLS, jobs, real time, vector search, OpenAPI.

Topics

Resources

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages