@struktos/cli

CLI tool for creating and managing Struktos.js projects with HTTP and gRPC support

🚀 Quick Start

# Install globally
npm install -g @struktos/cli

# Create a new project
struktos new my-app

# Or use npx
npx @struktos/cli new my-app

📋 Commands

struktos new [name]

Create a new Struktos.js project with interactive prompts.

struktos new my-api

Options:

• Framework: Express, Fastify, NestJS, or gRPC (new!)
• Persistence: PostgreSQL, MongoDB, or None
• Authentication: Optional @struktos/auth integration
• Docker: Optional Docker configuration

Creating a gRPC Microservice

struktos new my-service
# Select "gRPC - Microservices with Protocol Buffers" when prompted

This generates a complete gRPC server setup:

my-service/
├── src/
│   ├── main.ts              # gRPC server entry point
│   ├── domain/
│   ├── application/
│   └── infrastructure/
│       └── adapters/
│           └── grpc/        # gRPC service handlers
├── protos/                  # Protocol Buffer definitions
│   └── health.proto
├── package.json
└── README.md

struktos generate entity <name>

Generate a complete entity with Hexagonal Architecture:

struktos generate entity Product --fields="name:string,price:number"
# or short form
struktos g entity Product -f "name:string,price:number"

Generated files:

• src/domain/entities/Product.entity.ts
• src/domain/repositories/IProductRepository.ts
• src/infrastructure/adapters/persistence/Product.repository.ts

struktos generate service <name> (New!)

Generate a service with handlers for HTTP or gRPC.

gRPC Service

struktos generate service user --type=grpc
# or with specific methods
struktos g service user -t grpc -m "get,list,create,update,delete"

Generated files:

• protos/user.proto - Protocol Buffer definition
• src/infrastructure/adapters/grpc/user.service.grpc.ts - Service handler
• src/infrastructure/adapters/grpc/user.registration.ts - Registration example

Generated proto file:

syntax = "proto3";
package user;

service UserService {
  rpc GetUser (GetUserRequest) returns (User);
  rpc ListUsers (ListUsersRequest) returns (stream User);
  rpc CreateUser (CreateUserRequest) returns (User);
  rpc UpdateUser (UpdateUserRequest) returns (User);
  rpc DeleteUser (DeleteUserRequest) returns (DeleteUserResponse);
}

message User {
  string id = 1;
  string name = 2;
  string description = 3;
  int64 created_at = 4;
  int64 updated_at = 5;
}
// ... request/response messages

Generated handler:

import { RequestContext } from '@struktos/core';
import { GrpcContextData } from '@struktos/adapter-grpc';

export const userService = {
  GetUser: (call, callback) => {
    const ctx = RequestContext.current<GrpcContextData>();
    const traceId = ctx?.get('traceId');
    // Implementation...
  },
  // ... other methods
};

HTTP Service

struktos generate service product --type=http

Generated files:

• src/infrastructure/adapters/http/product.controller.ts

struktos generate middleware <n> (New in v0.3.0!)

Generate middleware/interceptor classes with pure TypeScript.

# Custom middleware
struktos generate middleware auth
struktos g mw requestValidator

# Logging template
struktos g mw logging --logging

# Timing/performance template
struktos g mw timing --timing

Generated files:

• src/infrastructure/middleware/<n>.interceptor.ts

Example generated interceptor:

import { RequestContext, IInterceptor, NextFn } from '@struktos/core';
import { Observable, tap, catchError } from 'rxjs';

export class AuthInterceptor implements IInterceptor {
  intercept(context: RequestContext, next: NextFn): Observable<any> {
    const traceId = context.get('traceId');
    console.log(`[AuthInterceptor] Processing request ${traceId}`);
    
    return next().pipe(
      tap(() => console.log(`[AuthInterceptor] Request completed`)),
      catchError((error) => { throw error; })
    );
  }
}

struktos generate use-case <action> (New in v0.3.0!)

Generate use case classes following Clean Architecture patterns.

# Create use case
struktos generate use-case create --entity=user
struktos g uc create -e user

# Get use case
struktos g uc get -e product

# List use case
struktos g uc list -e order

# With options
struktos g uc delete -e item --no-logger --no-validation

Options:

• -e, --entity <entity>: Entity name (required)
• --no-repository: Skip repository injection
• --no-logger: Skip logger injection
• --no-validation: Skip validation logic

Generated files:

• src/application/use-cases/<entity>/<action>-<entity>.use-case.ts

Example generated use case:

import { RequestContext, ILogger } from '@struktos/core';
import { IUserRepository } from '../../domain/repositories/IUserRepository';

export class CreateUserUseCase {
  constructor(
    private readonly userRepository: IUserRepository,
    private readonly logger: ILogger,
  ) {}

  async execute(context: RequestContext, input: CreateUserInput): Promise<CreateUserOutput> {
    this.logger.info(`Starting user creation`, { traceId: context.get('traceId') });
    
    this.validate(input);
    const user = await this.userRepository.create(input);
    
    return { user };
  }
}

struktos generate client <service> (New in v0.3.0!)

Generate gRPC client adapters for microservice communication.

# Generate client adapter
struktos generate client user-service

# Also generate port interface
struktos g client order-service --with-port

Options:

• --with-port: Also generate the port interface

Generated files:

• src/infrastructure/adapters/grpc/<service>.client.adapter.ts
• src/application/ports/grpc/<service>.client.port.ts (with --with-port)

Example generated client adapter:

import { RequestContext } from '@struktos/core';
import { Metadata } from '@grpc/grpc-js';

export class UserServiceClientAdapter implements IUserServiceClientPort {
  constructor(private readonly grpcClientFactory: IGrpcClientFactory) {
    this.userService = this.grpcClientFactory.getService('UserService');
  }

  async get(context: RequestContext, id: string): Promise<UserResponse> {
    const metadata = this.createMetadata(context); // Propagates trace ID
    return this.userService.GetUser({ id }, metadata);
  }

  private createMetadata(context: RequestContext): Metadata {
    const metadata = new Metadata();
    metadata.set('x-trace-id', context.get('traceId'));
    metadata.set('x-user-id', context.get('userId'));
    return metadata;
  }
}

🏗️ Project Structure

Generated projects follow Hexagonal Architecture:

project/
├── src/
│   ├── domain/              # Business logic
│   │   ├── entities/        # Domain entities
│   │   ├── repositories/    # Repository interfaces
│   │   └── services/        # Domain services
│   ├── application/         # Application logic
│   │   ├── use-cases/       # Use cases
│   │   └── ports/           # Port interfaces
│   ├── infrastructure/      # External adapters
│   │   └── adapters/
│   │       ├── http/        # HTTP controllers
│   │       ├── grpc/        # gRPC handlers
│   │       └── persistence/ # Repository implementations
│   └── main.ts              # Entry point
├── protos/                  # Protocol Buffers (gRPC only)
├── tests/
└── config/

📡 gRPC Support

main.ts (gRPC Project)

import { StruktosApp } from '@struktos/core';
import {
  createGrpcAdapter,
  createLoggingInterceptor,
  GrpcContextData,
} from '@struktos/adapter-grpc';

async function main() {
  const app = StruktosApp.create<GrpcContextData>({
    name: 'my-service',
  });

  app.use(createLoggingInterceptor());

  const adapter = createGrpcAdapter({
    enableCancellation: true,
  });

  // Register services
  await registerServices(adapter);

  await app.listen(adapter, 50051);
  console.log('gRPC server running on port 50051');
}

Registering a Service

import { registerUserService } from './infrastructure/adapters/grpc/user.service.grpc';

async function registerServices(adapter) {
  await registerUserService(adapter, './protos/user.proto');
}

🔧 Supported Types

For entity field definitions:

| Type | Example | |------|---------| | string | name:string | | number | price:number | | boolean | isActive:boolean | | Date | createdAt:Date | | any | metadata:any | | unknown | data:unknown |

Optional fields use ? suffix: description:string?

📦 Framework Support

| Framework | Type | Command | |-----------|------|---------| | Express | HTTP | struktos new app → Select Express | | Fastify | HTTP | struktos new app → Select Fastify | | NestJS | HTTP | struktos new app → Select NestJS | | gRPC | RPC | struktos new app → Select gRPC |

🐳 Docker Support

Generated projects include Docker configuration:

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f app

📖 Examples

Create a gRPC Microservice with User Service

# 1. Create project
struktos new user-service
# Select: gRPC, PostgreSQL, Yes for Auth, Yes for Docker

# 2. Navigate to project
cd user-service

# 3. Generate user service
struktos generate service user --type=grpc

# 4. Install dependencies
npm install

# 5. Start development server
npm run dev

Create an Express API with Product Entity

# 1. Create project
struktos new product-api
# Select: Express, MongoDB, Yes for Auth, Yes for Docker

# 2. Navigate to project
cd product-api

# 3. Generate product entity
struktos generate entity Product --fields="name:string,price:number,description:string?"

# 4. Install dependencies
npm install

# 5. Start development server
npm run dev

🤝 Related Packages

• @struktos/core - Core framework
• @struktos/adapter-express - Express adapter
• @struktos/adapter-fastify - Fastify adapter
• @struktos/adapter-grpc - gRPC adapter
• @struktos/auth - Authentication

📄 License

MIT © Struktos.js Team