Documentation

Use this index as the entrypoint for setup guides, architecture references, runtime libraries, examples, and repository maintenance notes.

Start here

Getting started: install the workspace, run the skeleton app, and inspect the copyable resource definition.
Backend blueprint: the opinionated playbook for new NestJS-YALC backends.
CrudGen-first composition: how to keep generated CRUD surfaces while customizing the right layer.
Modular platform guide: how to build a modular platform with NestJS-YALC.

What the framework gives you

CrudGen filters for GraphQL endpoints.
Runtime generation of CRUD endpoints through NestJS dependency factories.
Parameterized generation of resolvers, services, dataloaders, and TypeORM repositories from entities and DTOs.
JSON support for TypeORM entities through decorators.
MySQL view-read/table-write patterns through the same repository boundary.
GraphQL extensions for field middleware, TypeORM field mapping, nested field resolving, dataloaders, and joins.
Jest helpers for monorepo testing.
Utility classes and helpers for common NestJS platform work.

Architecture guides

CrudGen

Runtime libraries

Examples

Examples overview
Skeleton app: the minimal all-in-one CrudGenResourceFactory path with a small module API-client example.
OmniKernel app: generated REST and GraphQL over a backend-only OmniKernel substrate.
Task app: the advanced OmniKernel-backed composition with module API-client workflows and CI/e2e validation.

Publication and maintenance

Planning notes

NPM workspace

The root package.json manages scripts and dependencies for the whole library collection. It contains the devDependencies needed for tests and builds, and the dependencies used by the packages themselves.

Prefer the npm workspace approach. It lets each package declare its own scripts and dependencies while still allowing root-level orchestration.

Unit tests

The root package.json contains scripts for running unit tests across the library collection. The repository uses Jest projects, configured by jest.config.ts, with helpers from @nestjs-yalc/jest.

When Jest errors with messages like “Cannot assign to read only property …” while mocking ESM modules, load the module through importMockedEsm from @nestjs-yalc/jest/esm.helper before importing the system under test. importMockedEsm wraps functions with jest.fn and registers them using jest.unstable_mockModule, which avoids read-only export issues. Use mockNestJSGraphql(import.meta) for @nestjs/graphql convenience.

Run coverage with:

npm run test:cov

Then serve coverage with:

npm run test:cov:serve

The coverage report is available at:

http://127.0.0.1:8080/lcov-report/

Pipeline

The GitHub pipeline checks linting, builds, and tests with the configured coverage thresholds.

Directory conventions

The nestjs-yalc directory structure is intentionally flat so the packages can be integrated into other projects easily.

tsconfig.json: compiler and IDE configuration.
tsconfig.test.json: Jest configuration.
tsconfig.dev.json: development tooling configuration.
test.js: test helper entrypoint.
examples/: runnable example applications and modules.
docs/: GitHub Pages documentation.
[package]/: one top-level directory per workspace package.

Repo-specific utilities

var/asl-test.cjs: manual AsyncLocalStorage sanity check for Fastify and ALS. It is not used by builds or tests.
build-dist.mjs: local pack script that writes dist/package.json for each package with exports pointing at compiled output. Source package.json files stay untouched; the dist files are generated after npm run build.