generator-pninja

Generate a full Laravel + React + Vite application from a single JDL model. Backend + Frontend + Docker + Database – ready in seconds ⚡

License

This project is licensed under the Apache License 2.0 – see the LICENSE.txt file for details.

What is PNinja?

PNinja is a Yeoman generator that allows you to build an entire stack application:

• Backend: Laravel (API)
• Frontend: React + Vite (SPA)
• Database: SQL (SQLite/MySQL/PostgreSQL/MariaDB)
• Search engine: Database, Algolia, Elasticsearch, Meilisearch, Typesense, Solr
• Docker Compose

All based on JDL files describing your domain!

Installation

Install Yeoman and PNinja:

npm install -g yo generator-pninja

Usage

1. Create the Application

Generate the base application structure (server + client without entities):

yo pninja

Answer a few prompts ... and you're ready ⚡

2. Generate Entities from JDL

Create your entity definition file using JDL:

touch entities.jdl # or any other name of your choice

and edit it using this guide: https://www.jhipster.tech/jdl/intro/

Run the entities generator:

yo pninja:entities entities.jdl

You can run this command multiple times with different JDL files:

yo pninja:entities core-entities.jdl
yo pninja:entities additional-entities.jdl

3. Interactive Entity Creation (Alternative)

For incremental development or to modify entities individually, use the entity sub-generator:

yo pninja:entity [EntityName]

This interactive command allows you to:

• Create new entities step by step
• Add or remove fields and relationships
• Update existing entities (regenerate, add, or remove)

All entity configurations are stored in .pninja/<EntityName>.json files.

What you get

my-app/
├── client/         # React + Vite app
├── docker/         # Docker compose
├── server/         # Laravel project
├── .pninja/        # Entity configurations
├── package.json    # With commands
└── README.md

Fully wired together: auth, routing, forms, CRUD, migrations.

Core Features

Authentication & Authorization

• Keycloak Integration - Enterprise-grade authentication
• ACL System (Casbin) - Fine-grained access control with policies and roles
• Role-based Permissions - Manage user permissions across entities

Data Management

• Soft Delete Support - Logical deletion with deleted_at timestamps; includes a web interface to view, restore, or permanently delete soft-deleted records. Unique constraints are enforced at the application level. Use @softDelete annotation in JDL.

  @softDelete
  entity MyEntity {
    name String required
    description String
  }

⚠️ When @softDelete is used, unique constraints are enforced at the application level only — no unique index is generated in the migration.

• Pessimistic Record Locking - Records are locked when opened for editing, preventing concurrent modifications. Locks expire automatically after 15 minutes, are renewed every 2 minutes via heartbeat, and can be force-released from the lock administration interface. Use @pessimisticLock annotation in JDL.

  @pessimisticLock
  entity MyEntity {
    name String required
    description String
  }

• Blob Fields - Binary attachments (Blob, AnyBlob, ImageBlob) are stored as a single JSON column {data, type, name, size} per field. In list responses data (base64) is omitted for performance; it is included in single-record responses. The serveBlob endpoint serves the raw binary directly. Validation uses blob_min_size / blob_max_size rules; ImageBlob enforces MIME type via image_mimetype. Supported databases: SQLite (json), MySQL/MariaDB (json), PostgreSQL (jsonb).
• CSV Database Seeding - Populate your database from CSV files
• Seeding Administration - Web interface to run seeders individually or in bulk, with direct CSV upload from the browser
• Migration Administration - Web interface to run migrate, rollback, migrate:fresh and check migrate:status without the command line
• Audit Logging - Complete change tracking for all entity modifications
• Interactive Entity Generator - Create and modify entities through CLI prompts
• Incremental Migrations - Automatic database migrations for entity changes

Search & Indexing

• Multiple Search Engines - Choose from Database, Algolia, Elasticsearch, Meilisearch, Typesense, or Solr
• Laravel Scout Integration - Seamless search engine configuration
• Search Index Management - Web interface to reindex, flush, and delete indexes per entity, with engine-specific actions for Elasticsearch (elastic:migrate, migrate:reset, migrate:refresh) and Meilisearch (scout:sync-index-settings)

Accessibility & UX

• WCAG 2.1 Level AA Compliance - Built-in accessibility standards
• React Aria Components - Accessible form components out-of-the-box
• Keyboard Navigation - Full keyboard support for all interactions
• Screen Reader Support - Optimized for assistive technologies

Internationalization

• i18next Integration - Multi-language support ready to use
• RTL Support - Right-to-left language compatibility

Modern UI/UX

• Responsive Design - Mobile-first approach
• Tailwind CSS - Utility-first styling
• Material Symbols Icons - Associate icons to entities using @icon annotation in JDL

  @icon("star")
  entity MyEntity {
    name String required
    description String
  }

• Component Library - Pre-built accessible components

DevOps Ready

• Docker Compose - Full containerization support
• Environment Configuration - Easy setup for different environments
• Database Migrations - Version-controlled schema changes

Supported Technologies and Limitations

Server Framework (PHP)

• Laravel

Client Frameworks

• React + Vite

Databases

• SQLite, MySQL, MariaDB, PostgreSQL

Authentication

• Keycloak

Authorization

• Casbin - Policy-based access control

Search Engines

• Algolia, Elasticsearch, Meilisearch, Typesense, Solr, Database

Frontend Libraries

• Tailwind CSS
• React Aria - Accessible component primitives
• Material Symbols - Icon library

Internationalization

• i18next

API Documentation

PNinja generates an interactive API documentation interface powered by Swagger UI and an OpenAPI 3.0 specification built automatically from your JDL model.

In the generated application

The API docs are accessible at /support/api-docs in the generated React client.

Features:

• Interactive console — execute API calls directly from the browser
• Authentication — supports both Bearer token and OAuth2 (Keycloak) login via the Authorize button
• Full endpoint coverage — all generated entities, auth, user, and locks endpoints are documented
• Schema reference — read and write schemas for every entity, including blob fields (stored as JSON objects {data, type, name, size}; data is omitted in list responses and included only in single-record responses)

Authenticating via Swagger UI:

• Bearer token (machine-to-machine): paste a valid JWT in the Authorize dialog
• OAuth2 (interactive login): click Authorize → select OAuth2 → log in via Keycloak

For machine-to-machine integrations, use the Client Credentials flow:

curl -X POST 'https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET'

Then use the returned access_token as Bearer header in all API calls.

How it works

The OpenAPI specification is:

• Generated by generators/entities/utils/openapi-generator.js from your JDL entities
• Stored as server/resources/openapi.json with Keycloak URL placeholders
• Served dynamically at GET /api/openapi.json by OpenApiController, which resolves the Keycloak URLs from server/.env at runtime
• Rendered by swagger-ui-react in the React client at /support/api-docs

Roadmap

Frontend Frameworks

• Vue support
• Angular support

Database Support

• SQL Server support
• Oracle support

DevOps

• GitHub Actions CI/CD - Automated testing and deployment
• Kubernetes Support - Container orchestration configs

Authentication Enhancements

• Laravel Sanctum - SPA authentication option
• Social Login (Google, GitHub, Facebook)

GitHub Repository

The source code for generator-pninja is hosted on GitHub. You can access the official repository at the following link:

Generator PNinja GitHub Repository

Contributing

Contributions are welcome! Feel free to open issues or pull requests on the GitHub repository.

Support

For issues, questions, or feature requests, please use the GitHub Issues page.