A modern, TypeScript-first framework for building scalable Node.js applications
Clean architecture • Dependency Injection • Decorator-driven • Express-powered
📚 Documentation
·
🚀 Live Demo
·
🐛 Report Bug
·
💡 Request Feature
Important
Expressive Tea has a new home on npm! Starting with v2.0.0, install using:
npm install @expressive-tea/coreLegacy package @zerooneit/expressive-tea will be maintained until April 30, 2026 for security patches only. Please migrate to @expressive-tea/core as soon as possible.
Why the change?
- ✨ Better namespace organization (
@expressive-tea/*) - 🌍 Community-focused ownership
- 🚀 Clearer project identity
Migration is simple: Just update your package.json and imports remain the same!
- "dependencies": { "@zerooneit/expressive-tea": "^1.2.0" }
+ "dependencies": { "@expressive-tea/core": "^2.0.0" }Caution
All versions 1.x are DEPRECATED and UNSUPPORTED as of January 27, 2026.
v1.3.x Beta - 🔴 CRITICAL SECURITY VULNERABILITY - DO NOT USE
Contains critical cryptography flaws in Teapot/Teacup gateway. If you're using this, STOP IMMEDIATELY and upgrade to v2.0.0.
v1.2.x Production - 🟡 No crypto issues, but deprecated (InversifyJS v6 EOL)
👉 Upgrade to v2.0.0 NOW - See Migration Guide
# Install the new package
npm install @expressive-tea/core
# Or with yarn
yarn add @expressive-tea/coreimport { ServerSettings, Route, Get, Boot } from '@expressive-tea/core';
@ServerSettings({ port: 3000 })
class App extends Boot {}
@Route('/hello')
class HelloController {
@Get('/')
sayHello() {
return { message: 'Hello, World! 🍵' };
}
}
new App().start();
// 🎉 Server running on http://localhost:3000Building Node.js applications is powerful, but messy. You get a blank canvas with Express—no structure, no conventions, just middleware chaos. Sound familiar?
Expressive Tea brings the elegance of modern frameworks to Node.js, without the bloat. Think NestJS simplicity meets Express flexibility.
| Feature | What You Get |
|---|---|
| 🎨 Clean Architecture | Decorators organize your code beautifully—no more spaghetti routes |
| 🔌 Plugin Everything | Share database configs, auth, websockets across projects |
| 💉 Smart DI | Singleton, Transient, Scoped services—InversifyJS under the hood |
| 🛡️ Type-Safe | Full TypeScript strict mode—catch bugs before they ship |
| 🔒 Secure by Default | AES-256-GCM + HKDF crypto, built-in security best practices |
| ⚡ Production Ready | 92%+ test coverage, battle-tested in real applications |
| 🎯 Express Compatible | Use ANY Express middleware—gradual migration friendly |
| 📦 Zero Lock-in | BYOA (Bring Your Own Architecture)—we don't force opinions |
Major security and architecture improvements!
+ ✅ Security: Fixed critical crypto vulnerabilities (AES-256-GCM + HKDF)
+ ✅ Type Safety: Full TypeScript strict mode support
+ ✅ DI: Scoped dependency injection (Singleton/Transient/Scoped)
+ ✅ Health Checks: Built-in health endpoints for Kubernetes/monitoring
+ ✅ Environment: .env file support with @Env decorator
+ ✅ Performance: Native utilities, removed lodash dependencies
+ ✅ ESLint: Migrated to ESLint v9 flat config
+ ✅ Quality: 95%+ coverage, all tests passing- Cryptography format changed (must re-encrypt data)
- TypeScript strict mode enabled
- Node.js 20+ required (Node.js 18 reached EOL April 2025)
- Express 5.x required
- ESLint v9 (flat config)
📖 Full Changelog • 🔄 Migration Guide
@Route('/api/users')
class UserController {
@Get('/:id')
async getUser(@Param('id') id: string) {
return this.userService.findById(id);
}
@Post('/')
async createUser(@Body() data: CreateUserDto) {
return this.userService.create(data);
}
}import { AuthPlugin } from '@my-org/auth-plugin';
import { DatabasePlugin } from '@my-org/db-plugin';
@ServerSettings({
port: 3000,
plugins: [AuthPlugin, DatabasePlugin]
})
class App extends Boot {}@injectable()
class UserService {
constructor(
@inject(TYPES.Database) private db: Database,
@inject(TYPES.Logger) private logger: Logger
) {}
}// Generics everywhere
class ApiResponse<T> {
constructor(
public data: T,
public status: number
) {}
}
@Get('/users')
getUsers(): ApiResponse<User[]> {
return new ApiResponse(users, 200);
}@HealthCheck({
checks: [
{
name: 'database',
check: async () => {
const isConnected = await db.ping();
return { status: isConnected ? 'pass' : 'fail' };
},
critical: true, // Blocks readiness probe if fails
timeout: 5000
}
]
})
class App extends Boot {}
// Endpoints:
// GET /health - Detailed health status
// GET /health/live - Liveness probe (K8s)
// GET /health/ready - Readiness probe (K8s)// Load from .env files
@Env({ path: '.env', required: ['DATABASE_URL', 'API_KEY'] })
@Env({ path: '.env.local', override: true, silent: true })
class App extends Boot {}
// In your .env:
// DATABASE_URL=postgres://localhost:5432/mydb
// API_KEY="secret-key"import { z } from 'zod';
const EnvSchema = z.object({
PORT: z.string().transform(Number),
DATABASE_URL: z.string().url(),
API_KEY: z.string().min(32)
});
type Env = z.infer<typeof EnvSchema>;
@Env<Env>({
transform: (env) => EnvSchema.parse(env),
onTransformError: 'throw' // Fail fast on invalid env
})
class App extends Boot {
constructor() {
super();
const env = Settings.getInstance().getEnv<Env>();
console.log(env.PORT); // Type: number (validated!)
}
}# .expressive-tea.yaml (YAML support!)
port: 3000
securePort: 4443
database:
host: localhost
port: 5432
# Comments supported!
cache:
enabled: true
ttl: 3600File Priority: .expressive-tea.yaml > .expressive-tea.yml > .expressive-tea (JSON)
- Node.js ≥ 20.0.0
- TypeScript ≥ 5.0.0
- Express ≥ 5.0.0
Note: Node.js 18 support was dropped in v2.0.0 as it reached End-of-Life in April 2025. We recommend using Node.js 20 LTS or Node.js 22 for the best experience and security updates.
{
"compilerOptions": {
"target": "ES2017",
"module": "commonjs",
"experimentalDecorators": true,
"emitDecoratorMetadata": true,
// Recommended for maximum safety
"strict": true,
"strictNullChecks": true,
"noImplicitAny": true
}
}# npm
npm install @expressive-tea/core reflect-metadata
# yarn
yarn add @expressive-tea/core reflect-metadataIf you want to test publishing locally before pushing to the public registry, use a local Verdaccio instance as a staging registry.
Quick steps:
- Start Verdaccio (Docker):
docker run -d --rm --name verdaccio-expressive-tea -p 4873:4873 verdaccio/verdaccio:latest- Point npm to local registry and publish:
# point npm to local registry
npm set registry http://localhost:4873
# publish (from package root)
npm publish --registry http://localhost:4873
# restore default registry
npm set registry https://registry.npmjs.org/- Optional: Use the repo-provided Verdaccio config for deterministic behavior:
docker run -d --rm --name verdaccio-expressive-tea -p 4873:4873 \
-v $(pwd)/.docs/verdaccio/config.yaml:/verdaccio/conf/config.yaml \
verdaccio/verdaccio:latestNotes:
- Default URL: http://localhost:4873
- Container name: verdaccio-expressive-tea (the agent checks for this name before starting a new container)
- Anonymous publishing is enabled in the example config (local only). Do not expose to public networks.
- The config permits overwriting the same package version for easy iterative testing.
1. Create your server:
// server.ts
import 'reflect-metadata';
import { ServerSettings, Boot } from '@expressive-tea/core';
@ServerSettings({
port: 3000,
controllers: [HelloController]
})
class MyApp extends Boot {}
export default MyApp;2. Add a controller:
// controllers/hello.controller.ts
import { Route, Get } from '@expressive-tea/core';
@Route('/hello')
export class HelloController {
@Get('/')
sayHello() {
return { message: 'Hello, Expressive Tea! 🍵' };
}
}3. Start it up:
// main.ts
import MyApp from './server';
const app = new MyApp();
app.start().then(() => {
console.log('🚀 Server is running!');
});- Complete Guide - Full documentation
- API Reference - Complete API docs
- Examples - Sample projects
- Configuration Files Guide - YAML/JSON config support
- Environment Variables Guide - Type-safe env with Zod
- Migration Guide v1 → v2 - Step-by-step upgrade
- Release Notes v2.0 - What's new
- Deprecation Notice - v1.x timeline
- Security Policy - Vulnerability reporting
- Changelog - Version history
We love contributions! Whether it's bug fixes, features, or docs.
Quick links:
- Contributing Guide - How to contribute
- Code of Conduct - Community guidelines
- Issues - Report bugs or request features
# Get started
git clone https://github.com/Expressive-Tea/expresive-tea.git
cd expresive-tea
yarn install
yarn testWe welcome AI-assisted contributions! Whether you're using GitHub Copilot, Cursor, Claude, or other AI coding assistants, we embrace the future of collaborative development.
If you're using AI tools for code generation, you MUST:
-
📖 Follow Repository Guidelines
-
👨💻 Human Review is MANDATORY
- ✅ All AI-generated code MUST be reviewed by a human developer before creating a pull request
- ✅ Understand the code completely—don't submit code you can't explain
- ✅ Test thoroughly (aim for 95%+ coverage)
- ✅ Verify the code follows our architectural patterns and best practices
-
✅ Quality Standards
- ✅ All tests must pass (
yarn test) - ✅ Linting must pass (
yarn linter:ci) - ✅ TypeScript must compile without errors (
yarn build) - ✅ Code must match our existing patterns and conventions
- ✅ Documentation must be updated (JSDoc, README, CHANGELOG)
- ✅ All tests must pass (
-
📝 PR Transparency
- ✅ Disclose AI assistance in your pull request description
- ✅ Example: "This PR was developed with assistance from Claude/Copilot/Cursor"
- ✅ Highlight any sections that were fully AI-generated for extra review
Why These Rules?
- 🛡️ Quality Assurance - AI can make subtle mistakes humans catch
- 🎯 Consistency - Ensures code matches our architectural vision
- 📚 Knowledge Transfer - Reviewers understand your contribution
- 🔒 Security - Prevents AI from introducing vulnerabilities
- 🤝 Collaboration - Maintains clear communication in the codebase
Vibe Coding Best Practices:
// ✅ GOOD: AI-generated, reviewed, and refined by human
@Route('/api/users')
class UserController {
@Get('/:id')
async getUser(@Param('id') id: string): Promise<User> {
// Human: Added validation per AGENTS.md security guidelines
if (!id || !validator.isUUID(id)) {
throw new BadRequestException('Invalid user ID');
}
return this.userService.findById(id);
}
}
// ❌ BAD: AI-generated, unreviewed, missing error handling
@Route('/api/users')
class UserController {
@Get('/:id')
async getUser(@Param('id') id: string) {
return this.userService.findById(id); // What if id is invalid?
}
}📚 Required Reading for AI-Assisted Development:
AGENTS.md- Repository-specific rules for AI agentsCLAUDE.md- Claude AI coding guidelinesCONTRIBUTING.md- General contribution guide.prettierrc- Code formatting ruleseslint.config.js- Linting configuration
Questions? Ask in GitHub Discussions before submitting AI-generated code.
- 📖 Documentation
- 💬 Gitter Chat
- 📧 Email Support
- 🐛 GitHub Issues
- 🔖 Stack Overflow - Use tag
expressive-tea
- 🐦 Twitter: @expressive_tea
- 📧 Email: support@expressive-tea.io
- 👨💻 Author: Diego Resendez
| Technology | Purpose |
|---|---|
| Express | Fast, unopinionated web framework |
| TypeScript | Type-safe JavaScript |
| InversifyJS | Powerful dependency injection |
| Reflect Metadata | Decorator metadata support |
Building Expressive Tea takes time and dedication. If this project helps you, consider sponsoring!
Principal Sponsor:
Interested in sponsoring? Contact projects@zero-oneit.com
Apache-2.0 License - see LICENSE file for details
We use Semantic Versioning (SemVer). See tags for available versions.
Lead Developer: Diego Resendez
See all contributors who've helped shape Expressive Tea.
Logo and banner designed by Freepik
Made with ☕ and 🍵 by the Expressive Tea Team
Start brewing better Node.js apps today!