Monorepo for foundational Expressive Tea framework packages
📅 Versioning: All packages use Calendar Versioning (CalVer) in the format
YYYY.MM.MICRO. Current version:2026.1.0
Important
These packages (v2026.1.0) are designed for @expressive-tea/core >= 2.0.0
- ✅ Compatible with: @expressive-tea/core v2.x.x and above
- ❌ Not compatible with: @expressive-tea/core v1.x.x or below
For Core v1.x users:
- Use
@expressive-tea/commons@1.0.1(last SemVer version for Core v1.x) - Use
@expressive-tea/plugin@1.0.3(last SemVer version for Core v1.x) - Note:
@expressive-tea/metadatadid not exist for Core v1.x
📖 Versioning: See VERSIONING.md for complete CalVer policy details.
This monorepo contains the foundational packages for the Expressive Tea framework ecosystem. These packages provide core utilities, metadata management, and plugin architecture capabilities used by @expressive-tea/core and other Expressive Tea projects.
Current Version: 2026.1.0 (CalVer format: YYYY.MM.MICRO)
Versioning Scheme: Calendar Versioning (CalVer) - independent from Core's SemVer
Framework-agnostic TypeScript metadata management utilities for decorators.
Features:
- ✨ Comprehensive metadata management API
- 🎨 5 pre-built decorator utilities (@SetMetadata, @Meta, @InheritMetadata, @CacheInMetadata, @Deprecated)
- 🔒 Type-safe with full TypeScript support
- 🪶 Lightweight with minimal dependencies
- 🌐 Framework-agnostic (works with any TypeScript project)
Install:
npm install @expressive-tea/metadata reflect-metadata
Core utilities and shared types for the Expressive Tea framework.
Features:
- ✨ Re-exports all metadata functionality from @expressive-tea/metadata
- 🎯 TypeScript-first with full type definitions
- 🔒 Strict mode enabled for maximum type safety
- 📦 Lightweight (re-export layer for backward compatibility)
Install:
npm install @expressive-tea/commons reflect-metadata
Plugin architecture system for building modular, reusable application components.
Features:
- 🔌 Plugin system with lifecycle hooks (boot stages)
- 🔗 Dependency management between plugins
- ⚡ Priority-based execution order
- 🎨 Decorator-driven API with
@Stage
Install:
npm install @expressive-tea/plugin reflect-metadata# Install both packages
npm install @expressive-tea/commons @expressive-tea/plugin reflect-metadata
# Or with yarn
yarn add @expressive-tea/commons @expressive-tea/plugin reflect-metadataUsing Commons:
import 'reflect-metadata';
import { Metadata } from '@expressive-tea/commons';
class UserController {
@Route('/users')
getUsers() {
return [];
}
}
function Route(path: string) {
return function (target: any, propertyKey: string) {
Metadata.set('route:path', path, target, propertyKey);
};
}
const routePath = Metadata.get('route:path', UserController.prototype, 'getUsers');
console.log(routePath); // '/users'Using Plugin:
import { Plugin, BOOT_STAGES, Stage } from '@expressive-tea/plugin';
import { Express } from 'express';
export class LoggerPlugin extends Plugin {
protected name = 'LoggerPlugin';
protected priority = 100;
@Stage(BOOT_STAGES.APPLICATION)
setupLogger(server: Express): void {
server.use((req, res, next) => {
console.log(`${req.method} ${req.path}`);
next();
});
}
}- Node.js ≥ 18.0.0
- TypeScript ≥ 5.0.0 (if using TypeScript)
- reflect-metadata 0.2.x
Major modernization release!
- ✅ Comprehensive test coverage (94%+) with Jest 30
- ✅ Full JSDoc documentation on all public APIs
- ✅ ESLint v9 with flat config and type-aware linting
- ✅ Prettier code formatting
- ✅ TypeScript strict mode enabled
- ✅ Native utility functions (removed lodash)
- ✅ GitHub issue/PR templates and community files
- ⬆️ Upgraded to TypeScript 5.9.3
- ⬆️ Upgraded to Yarn 4.11.0 workspaces
- 📁 Build output moved to
dist/directories - 🚀 Replaced Gulp with native TypeScript compilation
- 📚 Enhanced IDE support with comprehensive JSDoc
- ❌ TSLint (replaced with ESLint v9)
- ❌ Lodash dependency (replaced with native JS)
- ❌ Gulp build system
- Node.js 18+ required (was: no minimum)
- TypeScript 5+ required (was: 3.6+)
- Build output moved to
dist/(was: co-located)
This is a Yarn 4 workspaces monorepo. Here's how to work with it:
# Clone the repository
git clone https://github.com/Expressive-Tea/packages.git
cd expresive-tea/packages
# Install dependencies (requires Yarn 4)
yarn install# Build all packages
yarn build
# Clean build artifacts
yarn clean
# Clean then build
yarn clean && yarn build# Run all tests
yarn test
# Run tests in watch mode
yarn test:watch
# Clear Jest cache
yarn test:clear
# Run tests for a specific package
cd packages/commons && yarn test
cd packages/plugin && yarn test# Lint all packages
yarn lint
# Lint and auto-fix
yarn lint:fix
# Format code
yarn format
# Check formatting
yarn format:check# Type check commons package
npx tsc --noEmit -p packages/commons
# Type check plugin package
npx tsc --noEmit -p packages/plugin@expressive-tea/packages/
├── .github/ # GitHub templates and workflows
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.yml
│ │ ├── feature_request.yml
│ │ └── config.yml
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── SECURITY.md
│ ├── SUPPORT.md
│ └── FUNDING.yml
├── packages/
│ ├── commons/ # @expressive-tea/commons package
│ │ ├── src/
│ │ │ ├── classes/ # Metadata management
│ │ │ ├── helpers/ # Utility functions
│ │ │ ├── types/ # TypeScript types
│ │ │ ├── __test__/ # Unit tests
│ │ │ └── index.ts # Public API
│ │ ├── dist/ # Compiled output
│ │ ├── package.json
│ │ ├── tsconfig.json
│ │ └── README.md
│ └── plugin/ # @expressive-tea/plugin package
│ ├── src/
│ │ ├── classes/ # Plugin base class
│ │ ├── decorators/ # @Stage decorator
│ │ ├── helpers/ # Storage and utilities
│ │ ├── libs/ # Native utilities
│ │ ├── exceptions/ # Error classes
│ │ ├── constants.ts # BOOT_STAGES enum
│ │ ├── __test__/ # Unit tests
│ │ └── index.ts # Public API
│ ├── dist/ # Compiled output
│ ├── package.json
│ ├── tsconfig.json
│ └── README.md
├── AGENTS.md # AI agent coding guidelines
├── CONTRIBUTING.md # Contribution guidelines
├── MIGRATION.md # Migration guide v0.0.x → v2.0.0
├── README.md # This file
├── package.json # Workspace root package.json
├── tsconfig.json # Base TypeScript config
├── tsconfig.linter.json # TypeScript config for ESLint
├── eslint.config.js # ESLint v9 flat config
├── .prettierrc # Prettier configuration
├── jest.config.js # Jest root configuration
└── yarn.lock # Yarn 4 lockfile
We welcome contributions! Whether it's bug fixes, features, or documentation improvements.
Before contributing, please:
- Read the Contributing Guide
- Check the AI Agent Guidelines if using AI coding tools
- Review existing Issues and Pull Requests
Development Workflow:
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes and add tests
- Run tests:
yarn test - Lint your code:
yarn lint - Format your code:
yarn format - Commit using Conventional Commits:
feat: add new featurefix: resolve bugdocs: update documentationtest: add tests
- Push and create a pull request
Quality Standards:
- ✅ All tests must pass (
yarn test) - ✅ Linting must pass (
yarn lint) - ✅ Code must be formatted (
yarn format) - ✅ Type checking must pass (
npx tsc --noEmit -p packages/*) - ✅ Test coverage must be maintained (>90%)
- ✅ JSDoc documentation required for public APIs
- @expressive-tea/core - Main framework package
- Expressive Tea Documentation - Official docs
- 📖 Documentation
- 💬 Gitter Chat - Real-time chat
- 🐛 GitHub Issues - Report bugs
- 📧 Email Support - Direct help
- 🔖 Stack Overflow - Tag:
expressive-tea
Found a bug? Please open an issue with:
- Package name and version
- Node.js and TypeScript versions
- Clear description of the problem
- Minimal reproduction code
- Expected vs actual behavior
Do not report security vulnerabilities through public GitHub issues.
Please email: security@expressive-tea.io
See Security Policy for details.
We use Semantic Versioning (SemVer). For available versions, see the tags on this repository.
Current Versions:
@expressive-tea/commons@2.0.0@expressive-tea/plugin@2.0.0
Apache-2.0 License - see LICENSE file for details.
Original Author:
- Diego Resendez - @chrnx-dev
Maintained by:
- Zero One IT - https://zerooneit.com
See all contributors who've helped shape this project.
- Logo and banner designed by Freepik
- Built with TypeScript
- Powered by Express
- Testing with Jest
- Linting with ESLint
- Formatting with Prettier
Made with ☕ and 🍵 by the Expressive Tea Team
Start brewing better Node.js apps today!