https://github.com/rayonstudios/rayon_gcp_express_psql_starter

Starter kit on steroids for modern NodeJS projects
https://github.com/rayonstudios/rayon_gcp_express_psql_starter

developer-experience dx eslint express gcp infisical morgan nodejs postgresql prettier rapid-development scaffold starter-template swagger tsoa typescript zod

Last synced: 10 months ago
JSON representation

Starter kit on steroids for modern NodeJS projects

• Host: GitHub
• URL: https://github.com/rayonstudios/rayon_gcp_express_psql_starter
• Owner: rayonstudios
• Created: 2024-10-11T21:08:40.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2025-05-30T11:07:47.000Z (about 1 year ago)
• Last Synced: 2025-09-07T06:37:53.444Z (10 months ago)
• Topics: developer-experience, dx, eslint, express, gcp, infisical, morgan, nodejs, postgresql, prettier, rapid-development, scaffold, starter-template, swagger, tsoa, typescript, zod
• Language: TypeScript
• Homepage: https://be.starters.rayonstudios.com/
• Size: 4.26 MB
• Stars: 4
• Watchers: 1
• Forks: 2
• Open Issues: 4
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
# Rayon GCP Express PSQL Starter

Rayon GCP Express PSQL Starter is an opinionated starter kit designed to scaffold backend projects quickly with a wide range of pre-configured features, built-in best practices, and "batteries included." It leverages Google Cloud Platform for deployment and Prisma for database management, allowing you to focus on building functionality.

[Live Demo](https://be.starters.rayonstudios.com/)

## Tech Stack

- **TypeScript** (NodeJS)

- **PostgreSQL** (via Prisma ORM)

- **Express.js**

- **Google App Engine**

- **Google Cloud Storage**

- **Infisical**

- **tsoa**

- **zod**

- **Morgan**

- **Brevo**

## Features

- 🔄 **Shared Types for Models & Request Validation**: Ensure consistent data types across the entire stack by sharing types between models and request validation.

- 📚 **Automatic Swagger Docs**: Generate comprehensive and up-to-date OpenAPI documentation straight from your codebase with tsoa.

- 🌐 **OpenAPI Specification**: Auto-generated OpenAPI JSON specification for seamless integration with API development tools and client SDKs.

- 🔐 **Flexible Authentication**: Secure authentication and authorization using both JWT for user sessions and API keys for service-to-service communication.

- 📜 **Request Validation with zod & tsoa**: Validate request data effortlessly using advanced schema validation with zod and TypeScript-based tsoa.

- 📝 **Data Logging with Morgan**: Log incoming requests and responses for enhanced observability and debugging.

- 🛡️ **Role-Based Access Control (RBAC)**: Manage user permissions and access levels through a robust role-based access control system.

- 🧬 **Database Introspection with Prisma**: Seamlessly interact with PostgreSQL using Prisma's intuitive ORM and database introspection.

- 🔄 **Automatic Schema Migration**: Automatically migrate database schemas using Xata CLI and GitHub Actions on PR merge.

- 📧 **Pre-configured Email Client**: Easily send emails through Brevo with the built-in, ready-to-use email client.

- 📂 **File Upload & Retrieval**: Handle file uploads and retrievals with multer and store them securely in Google Cloud Storage.

- 🖼️ **Config-based Auto Image Resizing**: Automatically resize uploaded images in the background based on configurable presets and dimensions.

- 🔄 **Live Code Reloading & Spec Generation**: Enjoy fast development cycles with live code reloading and on-the-fly API spec updates.

- 🚀 **CI/CD for GCP App Engine Deployments**: Automated deployment pipelines using GitHub Actions for continuous integration and deployment to GCP.

- 🔑 **Automatic Environment Variables with Infisical**: Simplify secret management and environment configuration using Infisical for secure variable injection.

- 🔔 **Multi-channel Notifications**: Send notifications across in-app, push, and email channels with a unified API for user engagement.

- 📊 **One-liner Pagination for Models**: Easily implement pagination for any database model with a single line of code.

- 🔍 **One-liner Multi-Column Search**: Add multi-column search functionality to your modules with a single line of code using the `withSearch` higher-order function, mimicking full-text search capabilities.

- 🛑 **Global Error Handling**: Catch and manage errors gracefully across your entire application with centralized error handling.

- 🛡️ **hCaptcha Protection**: Secure sensitive public routes with hCaptcha to prevent automated abuse and spam.

- ✅ **ESLint Integration**: Keep your codebase clean and consistent with linting rules enforced by ESLint.

- 🌍 **Development & Production Environment Separation**: Seamlessly switch between dev and prod configurations with environment-specific settings.

- 📁 **Feature-based Folder Structure**: Organize your project with a clear, scalable folder structure separating core logic by feature.

## Deployment

Deployment is managed through GitHub Actions, with automatic deployments to Google App Engine:

- **main branch**: Deploys to production.

- **dev branch**: Deploys to the development environment.

## Installation and Setup

1. Clone the repository:

    ```bash

    git clone 

    cd 

    ```

2. Create a .env.infisical file with the following variables:

    ```bash

    INFISICAL_CLIENT_ID=

    INFISICAL_CLIENT_SECRET=

    INFISICAL_PROJECT_ID=

    ```

2. Install dependencies:

    ```bash

    npm i

    ```

3. Start the development server:

    ```bash

    npm run dev

    ```

## Best Practices

- Use **kebab-case** for file and folder names.

- Reusable, feature-independent code should be placed in the `lib` folder.

- Feature-dependent code goes under the `modules` folder, while middlewares are under the `middlewares` folder.

- **Snake case** should be used for database field names.

- Foreign key names should strictly be in the format `_id` (ex: user_id) to allow schema transform scripts to work correctly.

- Use `statusConst` to define HTTP status codes and messages, rather than hardcoding them.

- Basic request validation can be handled by tsoa through TypeScript, but use zod for advanced validation (e.g., email format, min/max constraints).

- Exported module types that are mean to be used as input/output types of a controller method, should be wrapped inside the `Expand` utility type as a workaround for tsoa's inability to handle complex nested types.

- Files in **scripts folder should not have any external dependencies**, as they are meant to run prior to dependencies installation.

## Roadmap

- [ ] Add unit tests