PXL Node.js Framework

A comprehensive Node.js framework for building modern applications with support for web servers, databases, queues, caching, and more.

Installation

Install the framework from NPM:

npm install @scpxl/nodejs-framework

Quick Start

import { WebApplication } from '@scpxl/nodejs-framework/application';

const app = new WebApplication({
  webServer: {
    port: 3000,
    host: '0.0.0.0'
  },
  database: {
    host: 'localhost',
    port: 5432,
    dbName: 'myapp',
    user: 'user',
    password: 'password'
  }
});

await app.start();

Features

• 🚀 FastAPI-powered Web Server with auto-routing
• 🗄️ Database Integration with MikroORM and PostgreSQL
• 📦 Queue System using BullMQ and Redis
• 🔄 WebSocket Support for real-time communication
• 🗄️ Caching Layer with Redis integration
• ☁️ AWS S3 Integration for file storage
• 🔐 Authentication System with JWT
• 📊 Structured Logging with Winston
• 🧪 Built-in Testing Utils
• ⚡ Performance Monitoring

Development (Framework Contributors)

Local Development

Clone this repository and switch to the project specific Node.js version:

git clone https://github.com/PXLbros/pxl-nodejs-framework.git
cd pxl-nodejs-framework
nvm use
npm install

Build

npm run build

Testing with Yalc (Local Development)

For local testing before publishing to NPM:

# Build and publish locally
npm run build:local

# In your project
yalc add @pxl/nodejs-framework

Development

Local Development

For local development with automatic publishing through Yalc:

npm run dev

For building locally with Yalc publishing:

npm run build:local

For building without Yalc (CI/production build):

npm run build

CI/CD Pipeline

This project uses GitHub Actions for continuous integration and deployment:

Build and Test (CI)

• Runs on all pull requests
• Installs dependencies, runs linting, builds the project, and runs tests

Build and Publish

• Runs on pushes to main/master branches and version tags
• Builds the project and publishes to npm
• Beta releases are published on pushes to main/master branches
• Stable releases are published when version tags are created

Setup for Publishing

To enable automatic publishing, configure the following repository secret:

• NPM_TOKEN: Your npm authentication token

Note: The dist/ folder is gitignored and automatically generated during the CI/CD process. Do not commit built files to the repository.

Releasing

Use the built-in release script to create new versions:

Quick Release Commands

# Patch release (1.0.0 → 1.0.1)
npm run release -- --patch

# Minor release (1.0.0 → 1.1.0)
npm run release -- --minor

# Major release (1.0.0 → 2.0.0)
npm run release -- --major

# Specific version
npm run release -- --version 2.1.3

Release Process

The release script will:

1. Check that your working directory is clean
2. Verify you're on the main/master branch
3. Update the version in package.json
4. Create a git commit and tag
5. Push to origin, triggering GitHub Actions

Dry Run

Preview what the release script will do without making changes:

npm run release -- --patch --dry-run

Help

For more information about the release script:

npm run release -- --help

Documentation

The API documentation is automatically generated using TypeDoc and deployed via GitHub Actions to GitHub Pages.

Local Documentation Development

To generate and view documentation locally:

npm run docs

This will generate the documentation in the docs/ folder. You can then open docs/index.html in your browser.

Automated Documentation Deployment

Documentation is automatically built and deployed to GitHub Pages when:

• Code is pushed to the main or master branch
• Pull requests are opened against main or master branch
• Manual workflow dispatch is triggered

The documentation will be available at: https://[your-username].github.io/[repository-name]/

Note: The docs/ folder is gitignored and should not be committed to the repository as it's automatically generated by the CI/CD pipeline.