Enterprise-grade TypeScript libraries for web applications, database operations, and code generation
BlendSDK v5 is a modern TypeScript monorepo providing production-ready libraries for building enterprise web applications. With a focus on type safety, developer experience, and fluent APIs, BlendSDK offers everything from web frameworks to database abstraction and code generation tools.
- 🎯 Type Safety First - Strict TypeScript with full type coverage
- 🔄 Fluent APIs - Chainable, intuitive interfaces
- 📦 Modular Design - Use only what you need
- ⚡ Performance - Optimized for production workloads
- 🧪 Fully Tested - Comprehensive test coverage with Vitest
- 🚀 ESM Native - Modern ECMAScript modules
Production-ready Express.js framework with dependency injection, plugin system, and fluent routing.
import { WebApplication, BaseController } from '@blendsdk/webafx';
const app = new WebApplication({ PORT: 3000 });
class UserController extends BaseController {
routes() {
return [
this.route().get('/').handle(this.list),
this.authenticated().post('/').handle(this.create),
];
}
}
app.registerController('/api/users', UserController);
await app.start();Features:
- Dependency injection container
- Plugin-based architecture
- Fluent route builder with authentication/authorization
- Built-in middleware (CORS, compression, request ID)
- Graceful shutdown support
- Health checks
PostgreSQL client with connection pooling and graceful shutdown.
import { PostgreSQLDatabase } from '@blendsdk/postgresql';
const db = new PostgreSQLDatabase({
host: 'localhost',
database: 'myapp',
user: 'postgres',
password: 'secret',
});
await db.connect();
const users = await db.query('SELECT * FROM users WHERE active = $1', [true]);
await db.shutdown();Features:
- Connection pooling with
pgdriver - Graceful connection management
- Transaction support
- Prepared statements
- Health checks
Database abstraction layer with CRUD statement builders.
import { SelectStatement } from '@blendsdk/dbcore';
const query = new SelectStatement()
.from('users')
.select('id', 'email', 'name')
.where('active = $1', true)
.orderBy('created_at DESC')
.limit(10);
const { sql, params } = query.compile();Features:
- Fluent query builders (SELECT, INSERT, UPDATE, DELETE)
- Expression builder integration
- Parameter binding
- Type-safe compilation
Immutable AST-based SQL WHERE clause builder.
import { query } from '@blendsdk/expression';
const result = query()
.where('status')
.equals('active')
.and(q => q.where('age').greaterThan(21).or('verified').equals(true))
.compile();
// Output: { sql: "status = $1 AND (age > $2 OR verified = $3)", params: {...} }Features:
- Immutable query objects
- Nested conditions
- Type-safe operators
- SQL injection protection
TypeScript/Zod/SQL generator with PostgreSQL introspection.
import { SchemaContainer, TypeGenerator } from '@blendsdk/codegen';
const schema = new SchemaContainer();
const s = schema.scope('api');
const User = s
.object({
id: s.number(),
email: s.string(),
role: s.string().enum(['admin', 'user']),
})
.named('User');
const typeGen = new TypeGenerator();
const tsCode = await typeGen.generate(schema);Features:
- Database schema builder (DDL generation)
- TypeScript type generation
- Zod schema generation
- PostgreSQL introspection (reverse engineering)
- Supports enums, arrays, nullable types
Safe, deterministic expression evaluation for business-authored rules.
import { compileExpression, evaluateExpression } from '@blendsdk/blendscript';
const compiled = compileExpression('Country == "NL" AND Enabled == TRUE', {
schema: {
Country: { type: 'string' },
Enabled: { type: 'boolean' },
},
expectedResult: 'boolean',
});
if (compiled.ok) {
const result = evaluateExpression(compiled.expression, {
Country: 'NL',
Enabled: true,
});
}Features:
- Formula-friendly comparisons, logic, membership, and text functions
- Validation, reusable compilation, and deterministic evaluation
- No dynamic code, host functions, I/O, or runtime dependencies
Standard library with type guards and utility functions.
import { isString, isNumber, isDefined } from '@blendsdk/stdlib';
if (isString(value)) {
console.log(value.toUpperCase()); // TypeScript knows value is string
}Features:
- Type guards for runtime checking
- Common utility functions
- No external dependencies
Fluent command-line argument parser with validation.
import { CommandLineParser } from '@blendsdk/cmdline';
const parser = new CommandLineParser()
.option('--port', { type: 'number', default: 3000 })
.option('--env', { type: 'string', choices: ['dev', 'prod'] })
.flag('--verbose');
const args = parser.parse(process.argv);
console.log(`Starting on port ${args.port}`);Features:
- Type-safe argument parsing
- Validation and default values
- Help text generation
- Boolean flags
React component and hook library for BlendSDK applications. Provides reusable UI components with full TypeScript support.
import { GlobalLoaderProvider, useGlobalLoader } from '@blendsdk/react';
// Wrap your app with the provider
<GlobalLoaderProvider config={{ spinnerColor: '#25b09b' }}>
<App />
</GlobalLoaderProvider>;
// Use the hook anywhere inside the provider
const { showLoader, setText } = useGlobalLoader();
setText('Loading data…');
showLoader(true);Features:
- Full-screen GlobalLoader with CSS-only spinner animation
- Context + Provider + Hook pattern for app-wide loader control
- Configurable appearance (colors, size, z-index, custom text component)
- Body scroll lock, nesting detection, auto-text-clearing
- Zero dependencies beyond React 19+
# Web framework
npm install @blendsdk/webafx
# Database
npm install @blendsdk/postgresql @blendsdk/dbcore @blendsdk/expression
# Code generation
npm install @blendsdk/codegen
# Utilities
npm install @blendsdk/stdlib @blendsdk/cmdline- Node.js: >= 22.0.0
- Package Manager: npm, yarn, or pnpm
Every blendsdk install ships an Agent Skill for coding agents
(OpenCode, Codex, Claude Code, Cursor, and others). It teaches the agent the public subpath
imports and the real APIs, so generated code compiles.
Copy it into the project's shared skill directory:
npm install blendsdk
mkdir -p .agents/skills
cp -R node_modules/blendsdk/skills/blendsdk .agents/skills/blendsdkOr install and update it with one command:
npx -y blendsdk@latest skill installThe installer finds the agent skill directories on your machine and asks which to install into.
For non-interactive use pass --all, --target <dir>, or --project:
npx -y blendsdk@latest skill install --all # every detected client
npx -y blendsdk@latest skill install --target ~/.config/opencode/skills
npx -y blendsdk@latest skill install --project # the current projectOr via curl:
curl -fsSL https://cdn.jsdelivr.net/npm/blendsdk@latest/install-skill.sh | bashblendsdk skill status shows the installed version and blendsdk skill uninstall removes it. Pin
a version with npx -y blendsdk@5.55.0 skill install.
Claude Code also discovers .claude/skills/blendsdk. See the
docs for the full list of
discovery paths.
import { WebApplication, BaseController } from '@blendsdk/webafx';
import { PostgreSQLDatabase } from '@blendsdk/postgresql';
const app = new WebApplication({ PORT: 3000 });
// Register database service
app.registerService({
name: 'db',
type: 'singleton',
factory: async () => {
const db = new PostgreSQLDatabase({/* config */});
await db.connect();
return db;
},
});
// Create controller
class UserController extends BaseController {
routes() {
return [this.route().get('/').handle(this.list)];
}
async list(req, res) {
const db = await req.services.get('db');
const users = await db.query('SELECT * FROM users');
res.json(users);
}
}
app.registerController('/api/users', UserController);
const shutdown = await app.start();
console.log('Server running on http://localhost:3000');
process.on('SIGTERM', shutdown);import { PostgreSQLDatabase } from '@blendsdk/postgresql';
import { SelectStatement } from '@blendsdk/dbcore';
import { query } from '@blendsdk/expression';
const db = new PostgreSQLDatabase({/* config */});
await db.connect();
// Using raw queries
const result = await db.query('SELECT * FROM users WHERE id = $1', [123]);
// Using statement builders
const stmt = new SelectStatement()
.from('users')
.select('*')
.where(query().where('active').equals(true).and('role').in(['admin', 'user']).compile());
const { sql, params } = stmt.compile();
const users = await db.query(sql, Object.values(params));import { SchemaContainer, TypeGenerator, ZodGenerator } from '@blendsdk/codegen';
const schema = new SchemaContainer();
const s = schema.scope('api');
// Define schema
const User = s
.object({
id: s.number(),
email: s.string(),
name: s.string().optional(),
roles: s.string().arrayed(),
})
.named('User');
// Generate TypeScript types
const typeGen = new TypeGenerator();
const types = await typeGen.generate(schema);
console.log(types);
// export interface User {
// id: number;
// email: string;
// name?: string;
// roles: string[];
// }
// Generate Zod schemas
const zodGen = new ZodGenerator();
const schemas = await zodGen.generate(schema);
console.log(schemas);
// export const UserSchema = z.object({
// id: z.number(),
// email: z.string(),
// name: z.string().optional(),
// roles: z.array(z.string())
// });BlendSDK is a monorepo managed with Turbo and uses lockstep versioning (all packages share the same version).
# Clone repository
git clone https://github.com/TrueSoftwareNL/blendsdk.git
cd blendsdk
# Install dependencies (requires Yarn)
yarn install
# Build all packages
yarn build
# Run tests
yarn test# Build all packages
yarn build
# Test all packages
yarn test
# Test with coverage
yarn test --coverage
# Watch mode
yarn test:watch
# Type check
yarn type-check
# Clean build artifacts
yarn clean# Navigate to package
cd packages/webafx
# Build specific package
yarn build
# Test specific package
yarn test
# Watch mode
yarn devBlendSDK uses lockstep versioning - all packages are versioned together:
# Auto-detect version bump from conventional commits
yarn lockstep:version:auto --ci
# Explicit version bumps
yarn lockstep:version:patch --ci
yarn lockstep:version:minor --ci
yarn lockstep:version:major --ci
# Publish to npm
yarn lockstep:publish:latest
yarn lockstep:publish:nextpackages/
├── stdlib/ # Foundation (no dependencies)
├── expression/ # SQL expression builder (depends on stdlib)
├── dbcore/ # Database abstraction (depends on expression)
├── postgresql/ # PostgreSQL client (depends on dbcore)
├── cmdline/ # CLI parser (depends on stdlib)
├── codegen/ # Code generators (depends on dbcore, postgresql)
└── webafx/ # Web framework (depends on stdlib)
stdlib ──→ cmdline
expression ──→ dbcore ──→ postgresql ──→ codegen
webafx (standalone, depends on express)
- TypeScript 5.9 - Strict mode, ESM modules
- Vitest - Fast, modern test framework
- Turbo - High-performance build system
- Express 5 - Web server (webafx)
- pg - PostgreSQL driver (postgresql)
- Zod - Schema validation (codegen)
# All packages
yarn test
# With coverage
yarn test --coverage
# Watch mode
yarn test:watch
# Specific package
cd packages/webafx && yarn testSome packages (postgresql, codegen) use Docker Compose for integration testing:
# Start test database
cd packages/postgresql
yarn db:up
# Run tests
yarn test
# Stop test database
yarn db:down- Package Documentation - Individual package READMEs
- API Reference - JSDoc comments in source code
- Implementation Plans - Architecture documents
- AI Agent Instructions - Development guidelines
We welcome contributions! Please follow these guidelines:
- Follow existing patterns - Review code in similar packages
- Write tests - All new features must have test coverage
- Use conventional commits - For automatic versioning
- Update documentation - Keep READMEs and JSDoc current
- Run tests before committing - Ensure all tests pass
feat: add new feature (minor version bump)
fix: bug fix (patch version bump)
docs: documentation only
refactor: code change without feature/fix
test: adding/updating tests
chore: maintenance tasks
BREAKING CHANGE: triggers major version bump
MIT © True Software
- Issues: GitHub Issues
- Discussions: GitHub Discussions
BlendSDK follows Semantic Versioning:
- Major (x.0.0): Breaking changes
- Minor (0.x.0): New features (backward compatible)
- Patch (0.0.x): Bug fixes (backward compatible)
Current version: 5.32.0 (lockstep across all packages)
Built with ❤️ by TrueSoftware




