PNinja

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
  ├── 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 (use @softDelete annotation in JDL)

  @softDelete
  entity MyEntity {
      name String required
      description String
  }

• 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

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.

Test Sandbox

# Dockerfile
FROM php:8.2-fpm

RUN apt-get update && apt-get install -y \
    vim \
    curl \
    unzip \
    git \
    libonig-dev \
    && rm -rf /var/lib/apt/lists/*

RUN docker-php-ext-install mbstring
RUN curl -sS https://getcomposer.org/installer | php && \
    mv composer.phar /usr/local/bin/composer

RUN useradd -ms /bin/bash developer

USER developer
WORKDIR /home/developer

RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash && \
    bash -c "source ~/.nvm/nvm.sh && \
    nvm install node && \
    npm install -g yo pninja"