Neoma Package Template

Template for creating new Neoma packages with consistent structure, configuration, and testing setup.

Creating a New Package

1. Copy this template

cd /path/to/wulfstack/packages
cp -r neoma-package-template neoma-<your-package-name>
cd neoma-<your-package-name>

2. Replace placeholders

Search and replace throughout the project:

• {{PACKAGE_NAME}} → Your package name (e.g., "garmr", "validation")
• {{PACKAGE_DESCRIPTION}} → Short description
• {{REPO_URL}} → GitHub repository URL (e.g., "https://github.com/shipdventures/neoma-garmr")

Quick find/replace:

# macOS/Linux
find . -type f -name "*.json" -o -name "*.md" -o -name "*.ts" | xargs sed -i '' 's/{{PACKAGE_NAME}}/your-package-name/g'
find . -type f -name "*.json" -o -name "*.md" -o -name "*.ts" | xargs sed -i '' 's/{{PACKAGE_DESCRIPTION}}/Your description/g'
find . -type f -name "*.json" -o -name "*.md" -o -name "*.ts" | xargs sed -i '' 's|{{REPO_URL}}|https://github.com/your-org/your-repo|g'

3. Rename directories

mv libs/package-template libs/your-package-name

4. Install dependencies

npm install

5. Start building!

npm test        # Unit tests (TDD)
npm run test:e2e # E2E tests
npm run build   # Build library
npm run lint    # Lint code

Package Structure

neoma-<package-name>/
├── libs/
│   └── <package-name>/           # The npm package
│       ├── src/
│       │   ├── modules/          # NestJS modules
│       │   ├── decorators/       # Custom decorators
│       │   ├── middlewares/      # Middleware
│       │   ├── guards/           # Guards
│       │   ├── services/         # Services
│       │   ├── interfaces/       # TypeScript interfaces
│       │   ├── constants/        # Constants
│       │   └── index.ts          # Public API exports
│       ├── package.json          # Published package.json
│       └── tsconfig.lib.json     # Library TypeScript config
├── src/                          # Example/test application
│   ├── app.module.ts
│   └── ...
├── specs/                        # E2E tests
│   ├── jest-e2e.json
│   └── *.e2e-spec.ts
├── fixtures/                     # Test fixtures and utilities
│   ├── app/                      # Test app lifecycle management
│   ├── database/                 # In-memory database setup
│   ├── models/                   # Model factory patterns
│   ├── matchers/                 # Custom Jest matchers
│   └── e2e-setup.js              # E2E build hook
├── package.json                  # Development package.json
├── tsconfig.json                 # Root TypeScript config
├── eslint.config.mjs             # ESLint config
├── .prettierrc                   # Prettier config
├── .gitignore
├── .nvmrc
├── LICENSE
└── README.md                     # Package documentation

Testing Strategy

E2E Tests (specs/)

• One file per major feature or configuration
• Tests full install experience and integration
• Uses real NestJS app, real database
• Proves README instructions work

Example: The template includes specs/app.e2e-spec.ts demonstrating how to test endpoints using managedAppInstance() and supertest.

Unit Tests (libs/<package>/src/**/*.spec.ts)

• TDD: Drive implementation
• Test individual classes/functions
• Fast feedback loop
• Test edge cases and error handling

Example: The template includes libs/package-template/src/modules/example.module.spec.ts showing how to test NestJS modules.

Complete Testing Flow

1. Write library code in libs/package-template/src/
2. Write unit tests alongside your code (*.spec.ts)
3. Export from libs/package-template/src/index.ts
4. Import in src/app.module.ts for E2E testing
5. Write E2E tests in specs/ to validate integration

The template includes working examples of all these steps with ExampleModule.

Don't test the same config twice - E2E covers integration, unit tests cover logic.

Testing Infrastructure

The template includes ready-to-use testing utilities in the fixtures/ directory:

App Lifecycle (fixtures/app)

import { managedAppInstance } from "fixtures/app"

describe("My E2E Test", () => {
  it("should work", async () => {
    const app = managedAppInstance()
    // App is automatically initialized before each test
    // and cleaned up after each test
  })
})

Database Setup (fixtures/database)

import { managedDatasourceInstance } from "fixtures/database"

describe("My Database Test", () => {
  it("should query database", async () => {
    const datasource = managedDatasourceInstance()
    // Fresh in-memory SQLite database for each test
    // Automatically destroyed after each test
  })
})

Model Factories (fixtures/models)

See fixtures/models/README.md for the pattern and examples.

Custom Matchers (fixtures/matchers)

• toThrowEquals(error) - Assert errors match exactly
• toEqualError(error) - Assert errors are equal

E2E Build Hook (fixtures/e2e-setup.js)

Automatically builds the library before E2E tests run.

Scripts

• npm run build - Build the library
• npm run lint - Lint all code
• npm test - Run unit tests in watch mode
• npm run test:e2e - Run E2E tests in watch mode

Configuration Highlights

TypeScript

• Target: ES2022
• Strict null checks enabled
• Decorators enabled
• No semicolons (enforced)

ESLint

• Explicit return types required
• Explicit member accessibility required
• No floating promises
• Prettier integration

Jest

• ts-jest for TypeScript
• jest-extended for additional matchers
• In-memory SQLite for tests
• Module path mapping for clean imports

Example README Structure

When you publish, your README should include:

1. Motivation - Why this package exists
2. Problem/Solution - Before/after code examples
3. Installation - Step-by-step setup
4. Basic Usage - Simple examples
5. Advanced Usage - Custom configurations
6. API Reference - All public APIs
7. Links - npm, GitHub, docs

See @neoma/route-model-binding README for a good example.

Publishing Checklist

Before publishing to npm:

• [ ] All tests passing
• [ ] README is complete
• [ ] LICENSE file included
• [ ] Version bumped in both package.json files
• [ ] Built with npm run build
• [ ] Verify exports in libs/<package>/src/index.ts
• [ ] Test installation in separate project
• [ ] Verify peer dependencies are correct

cd libs/<your-package-name>
npm publish --access public

Neoma Package Standards

All Neoma packages should:

• ✅ Be Laravel-inspired but NestJS-native
• ✅ Have minimal boilerplate
• ✅ Include comprehensive tests
• ✅ Have excellent documentation
• ✅ Use TypeScript strictly
• ✅ Follow consistent code style
• ✅ Be production-ready

Template Improvements (TODO)

Future enhancements to this template:

• [ ] GitHub Issue & PR Templates - Add .github/ISSUE_TEMPLATE/ for bug reports and feature requests, plus .github/pull_request_template.md
• [ ] CONTRIBUTING.md - Document contribution guidelines, coding standards, and development workflow
• [ ] CHANGELOG.md Template - Add template following Keep a Changelog format
• [ ] README Badges - Add placeholders for CI status, npm version, and license badges
• [ ] VSCode Extensions - Add .vscode/extensions.json with recommended extensions for NestJS development
• [ ] CODE_OF_CONDUCT.md - Add community standards if accepting external contributions