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

npm install @expressive-tea/core

- "dependencies": { "@zerooneit/expressive-tea": "^1.2.0" }
+ "dependencies": { "@expressive-tea/core": "^2.0.0" }

# Install the new package
npm install @expressive-tea/core

# Or with yarn
yarn add @expressive-tea/core

import { 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:3000

Try it live on CodeSandbox →

Building 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.

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

⚠️ Breaking Changes:

• 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: 3600

File 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-metadata

If you want to test publishing locally before pushing to the public registry, use a local Verdaccio instance as a staging registry.

Quick steps:

1. Start Verdaccio (Docker):

docker run -d --rm --name verdaccio-expressive-tea -p 4873:4873 verdaccio/verdaccio:latest

2. 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/

3. 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:latest

Notes:

• 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!');
});

📚 Full Tutorial →

• 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 test

We welcome AI-assisted contributions! Whether you're using GitHub Copilot, Cursor, Claude, or other AI coding assistants, we embrace the future of collaborative development.

⚠️ IMPORTANT: AI-Generated Code Requirements

If you're using AI tools for code generation, you MUST:

1. 📖 Follow Repository Guidelines

   • ✅ Read and strictly adhere to AGENTS.md - Agent-specific coding rules
   • ✅ Read and strictly adhere to CLAUDE.md - Claude AI guidelines
   • ✅ These files contain critical project conventions, style guides, and quality standards

2. 👨‍💻 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

3. ✅ 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)

4. 📝 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 agents
• CLAUDE.md - Claude AI coding guidelines
• CONTRIBUTING.md - General contribution guide
• .prettierrc - Code formatting rules
• eslint.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: [email protected]
• 👨‍💻 Author: Diego Resendez

Building Expressive Tea takes time and dedication. If this project helps you, consider sponsoring!

Principal Sponsor:

Interested in sponsoring? Contact [email protected]

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!}