@uisap/create

@uisap/create

A scaffolding tool for quickly setting up a new project using @uisap/core, a lightweight and modular framework inspired by Laravel and built on top of Fastify.

With @uisap/create, you can bootstrap a fully functional batteries-included project in seconds, complete with configuration files, models, controllers, routes, events, listeners, and more.

Installation

You don’t need to install @uisap/create globally. Use npx to run it directly:

npx @uisap/create my-app

Prerequisites:

• Node.js (version 16.x or higher)
• Redis (default: localhost:6379, required for queue and broadcasting)
• Database (MSSQL is configured by default; adjust settings in config/database.js as needed)

Ensure Redis and your database are running before starting the application.

Directory Structure

my-app/
├── app/
│   ├── controllers/
│   │   └── ExampleController.js
│   ├── events/
│   │   └── OrderShipped.js  (optional, created with make:event)
│   ├── listeners/
│   │   └── SendShipmentNotification.js  (optional, created with make:listener)
│   ├── models/
│   │   └── ExampleModel.js
│   ├── providers/
│   │   └── AppServiceProvider.js  (optional, updated with event-listener bindings)
│   ├── console/
│   │   └── commands/
│   │       └── ExampleCommand.js  (optional, created with make:command)
│   └── jobs/
│       └── ExampleJob.js  (optional, created with make:job)
├── config/
│   ├── app.js
│   ├── cors.js
│   ├── database.js
│   ├── events.js
│   ├── queue.js
│   └── schedule.js
├── index.js
├── routes.js
├── .env.example
└── package.json

Starting the Application

Navigate to your project directory, copy the environment file, and start the app:

cd my-app
cp .env.example .env
npm run dev

For queue and broadcasting, start the worker in a separate terminal (not needed if the app running with npm run dev):

npm run worker

The application runs on http://localhost:4115 by default (configurable in config/app.js or .env).

Features

• Routing: Define routes in api.js using @uisap/core’s routing system.
• Controllers: Extend BaseController for handling requests.
• Models: Use Model for database interactions.
• Dependency Injection: Automatic injection of models and services.
• Events & Broadcasting: Handle real-time updates using Socket.IO with custom events and listeners
• Queue Processing: Asynchronous job handling with bull.
• Scheduling: Cron-like tasks using toad-scheduler.

CLI Commands

@uisap/create provides a CLI tool (uisap.js) for generating various components. Run these commands from your project root:

• Create a Controller:

  node uisap make:controller Example
  

• Create a Model:

  node uisap make:model Example
  

• Create a Job:

  node uisap make:job Example
  

• Create an Event:

  node uisap make:event OrderShipped
  

  • With a listener binding:

    node uisap make:event OrderShipped --listener SendShipmentNotification
    

    • Creates app/events/OrderShipped.js and updates app/providers/AppServiceProvider.js with the listener.

• Create a Listener:

  node uisap make:listener SendShipmentNotification
  

  • With an event binding:

    node uisap make:listener SendShipmentNotification --event OrderShipped
    

    • Creates app/listeners/SendShipmentNotification.js and updates app/providers/AppServiceProvider.js with the event.
  • With queue support:

    node uisap make:listener SendShipmentNotification --queue
    

    • Adds the listener to config/queue.js as a handler.

• Create a Command:

  node uisap make:command Example
  

  • With scheduling:

    node uisap make:command Example --schedule
    

    • Adds the command to config/schedule.js.

• Run Scheduled Tasks:

  node uisap schedule:run
  

• List Scheduled Tasks:

  node uisap schedule:list
  

• Process Queue Jobs:

  node uisap queue:work
  

• Test Broadcasting:

  node uisap broadcast:test --channel my-channel --event my-event --data "Test message"
  

Event and Listener Integration

Events and listeners are tightly integrated with the framework. Use the --listener or --event options to automatically bind them in AppServiceProvider.js. For example:

node uisap make:event OrderShipped --listener SendShipmentNotification

This generates an OrderShipped event and updates AppServiceProvider.js:

import { ServiceProvider, EventFacade as Event } from '@uisap/core';
import SendShipmentNotification from '../listeners/SendShipmentNotification.js';

export class AppServiceProvider extends ServiceProvider {
  register() {
    // You can register your services here
  }

  async boot() {
    // You can boot your services here
    Event.listen('OrderShipped', new SendShipmentNotification(), 10);
  }
}

This ensures that when the OrderShipped event is fired, the SendShipmentNotification listener is triggered.