Today marks a significant milestone in the evolution of type-safe API development. What began as @platformatic/client in our v0.19.0 release has grown into something much bigger—a production-proven, enterprise-grade solution now powering companies like Spendesk, who are not only using Massimo in production but actively contributing to its development.
We're thrilled to introduce Massimo (formerly @platformatic/client)—not just a new name, but the next evolution of type-safe API client generation. This relaunch also marks Massimo's independence as standalone packages without the @platformatic scope.
Why "Massimo"?
The name is inspired by Massimo Troisi, the beloved Italian actor from the film "Il Postino" (The Postman). Just as the postman in the movie delivered messages and connected people, Massimo delivers API connections and bridges the gap between services, making communication between applications as effortless and poetic as Troisi's unforgettable performance.
From Prototype to Production
Since its initial release, what started as a developer tool has evolved into an enterprise-grade solution. Massimo has been battle-tested in production environments, with companies like Spendesk relying on it to enhance their frontend and backend development efficiency. This real-world usage has driven continuous improvements, community contributions, and the robust feature set you see today.
Complete Feature Overview
Massimo is a powerful API SDK client and CLI tool for creating fully-typed clients for remote OpenAPI or GraphQL APIs. Here's everything you need to know about its comprehensive, production-proven feature set:
🏗️ Dual Architecture: Library + Generator
Massimo provides two complementary approaches to API client development:
1. Code Generator (massimo-cli)
- Generates standalone, dependency-free client code at build time
- Creates TypeScript/JavaScript files you can commit to your repository
- Perfect for teams who want full control and transparency over their API client code
- Ideal for frontend applications where bundle size matters
2. Runtime Library (massimo)
- Dynamic client creation from schemas at runtime
- Uses the same TypeScript generation engine internally for type safety
- Perfect for server-side applications and rapid prototyping
- Handles schema updates automatically without manual regeneration
The Key Connection:
The generator doesn't just create standalone files - it's also the type-safety engine that powers the runtime library. When you use the runtime library, it uses the same code generation logic internally to ensure your API calls are fully typed, even when created dynamically.
This dual approach means you can choose the right strategy for your use case:
- Frontend apps: Use the generator for zero-dependency, optimized bundles
- Backend services: Use the library for dynamic, runtime client creation with generated type safety
- Hybrid projects: Mix both approaches as needed
Both approaches use the same underlying type generation system, ensuring consistency and type safety across your entire application stack.
🚀 Core Features
OpenAPI & GraphQL Support
- Generate typed clients from OpenAPI 3.x specifications with full TypeScript support
- Create GraphQL clients from schemas with automatic type generation
- Support for any backend that exposes OpenAPI or GraphQL endpoints
Type-Safe Development
- Full TypeScript-first development experience
- Automatically generated TypeScript types for complete type safety
- Request and response type validation with detailed error messages
- Support for complex OpenAPI schemas including nested objects and arrays
Framework Integration
- Works seamlessly with any JavaScript framework (Node.js, React, Vue, Angular)
- First-class Fastify plugin for server-side integration
- Browser-compatible clients using native
fetch API
- Support for both server and client environments
The massimo-cli provides extensive command-line functionality:
Client Generation Options
npm install -g massimo-cli
massimo http://api.example.com/openapi.json --name myclient
massimo http://api.example.com/graphql --name myclient --type graphql
massimo http://api.example.com/openapi.json --frontend --language ts --name myclient
massimo http://api.example.com/openapi.json --types-only --name myclient
Advanced CLI Options
--frontend - Generate browser-compatible clients using fetch--language js|ts - Choose JavaScript or TypeScript output--full-response - Return complete response objects instead of just body--full-request - Wrap parameters in body, headers, query structure--validate-response - Enable response validation against schema--optional-headers - Mark specific headers as optional--typescript - Generate TypeScript plugin files--with-credentials - Frontend client only: adds credentials: 'include' to fetch calls (learn more about credentials)
📦 Client Library Features
The massimo core library offers programmatic API access:
OpenAPI Client Builder
import { buildOpenAPIClient } from "massimo";
const client = await buildOpenAPIClient({
url: 'https://api.example.com/openapi.json',
headers: { Authorization: 'Bearer token' },
validateResponse: true,
fullResponse: false,
throwOnError: true
});
GraphQL Client Builder
import { buildGraphQLClient } from "massimo";
const client = await buildGraphQLClient({
url: 'https://api.example.com/graphql',
headers: { Authorization: 'Bearer token' }
});
const result = await client.graphql({
query: 'mutation { createUser(input: { name: "John" }) { id } }',
variables: { name: "John" }
});
🔧 Authentication & Security Features
Dynamic Headers
- Support for dynamic header generation via
getHeaders function
- Request-specific authentication token handling
- Context-aware header modification
Fastify Plugin Authentication
app.configureMyClient({
async getHeaders(req, reply) {
return {
Authorization: `Bearer ${req.user.token}`,
'X-User-ID': req.user.id
};
}
});
Security Options
- Custom header configuration for protected endpoints
- Support for various authentication schemes (Bearer, API Key, etc.)
- CORS credentials handling for browser clients
🌐 Two Client Types: Server vs Frontend
Massimo generates two fundamentally different types of clients depending on your target environment:
Built on Undici for maximum performance and Node.js compatibility:
massimo http://api.example.com/openapi.json --name myclient
Key Features:
- Uses Undici HTTP client for optimal Node.js performance
- Built-in connection pooling and HTTP/2 support
- Advanced timeout controls (body timeout, headers timeout)
- Custom dispatchers and agents for fine-tuned control
- Full telemetry and tracing integration
- Designed for high-throughput server applications
import myClient from './myclient/myclient.js';
const client = await myClient({
url: 'https://api.example.com',
bodyTimeout: 30000,
headersTimeout: 10000,
dispatcher: customAgent
});
app.get('/users', async (request) => {
return request.myclient.getUsers();
});
Frontend Clients (Browser/Fetch)
Zero dependencies - uses native browser fetch():
massimo http://api.example.com/openapi.json --frontend --name myclient
Key Features:
- No external dependencies - pure JavaScript/TypeScript
- Uses native browser
fetch() API
- Optimized bundle size for frontend applications
- Support for CORS credentials and browser security policies
- Works in any JavaScript environment with fetch support
import { setBaseUrl, getMovies, setDefaultHeaders } from './api.js';
setBaseUrl('https://api.example.com');
setDefaultHeaders({ Authorization: 'Bearer token' });
const movies = await getMovies({});
import build from './api.js';
const client = build('https://api.example.com', {
headers: { Authorization: 'Bearer token' }
});
const movies = await client.getMovies({});
Bundle Impact:
- Server client: Includes Undici (~200KB) for performance
- Frontend client: Zero dependencies - only your generated code (~5-10KB)
This architectural difference means you can use the same OpenAPI spec to generate both a high-performance server client for your backend services AND a lightweight, dependency-free client for your frontend applications!
🏗️ Advanced Features
Operation Mapping
- Access to OpenAPI operation ID mappings via symbol properties
- Method and path inspection for debugging and tooling
Request/Response Customization
- Custom query parameter parsing
- Request body and header modification
- Full response object access when needed
- Response validation against OpenAPI schemas
Telemetry & Monitoring
- Automatic telemetry propagation in Fastify environments
- Request tracing and performance monitoring
- Built-in error handling with detailed error codes
Error Handling
Comprehensive error system with specific error codes:
PLT_MASSIMO_OPTIONS_URL_REQUIRED - Missing URL in client optionsPLT_MASSIMO_FORM_DATA_REQUIRED - FormData required for multipart requestsPLT_MASSIMO_MISSING_PARAMS_REQUIRED - Missing required path parametersPLT_MASSIMO_INVALID_RESPONSE_SCHEMA - Response validation failure- And more detailed error scenarios for robust error handling
Production Usage
Companies like Spendesk are using Massimo to power their production applications, demonstrating its reliability and enterprise readiness. The feedback and contributions from these production deployments have been instrumental in shaping Massimo's evolution.
Community Contributions
Massimo benefits from active community involvement, with enterprise users contributing back improvements, bug fixes, and feature requests based on real-world usage patterns.
Package Names
@platformatic/client → massimo@platformatic/client-cli → massimo-cli
CLI Command
npx @platformatic/client-cli → npx massimo-cli or massimo
Import Statements
import { buildOpenAPIClient } from '@platformatic/client';
import pltClient from '@platformatic/client/fastify-plugin';
import { buildOpenAPIClient } from 'massimo';
import pltClient from 'massimo/fastify-plugin';
All existing APIs remain the same - this evolution maintains full backward compatibility!
🚀 Production Ready
Battle-Tested Features
- Used in production environments with proven reliability
- Built-in retry logic and error recovery mechanisms
- Performance optimized for high-throughput applications
- Comprehensive test coverage with end-to-end testing
Development Experience
- Hot-reload support in development environments
- Detailed debugging information and logging
- Integration with popular development tools
- Extensive documentation and examples
Get Started Today
Install Massimo and start generating typed API clients:
npm install -g massimo-cli
massimo http://api.example.com/openapi.json --name myclient
npm install massimo
The same powerful features you loved in @platformatic/client are now available as standalone Massimo packages, with continued development and new features coming soon!
Documentation & Resources
Join our Discord community for support and to connect with other developers using Massimo!
