lonestone-boilerplate

KO | EN

gitlite — search

#javascript #react #ai #typescript #llm #rust #deep-learning #linux #docker #nodejs #windows #awesome #cli #open-source

lonestone-boilerplate

(★ 11)

Starter kit for full-stack webapps, SaaS and websites with React and NestJS

lonestone-boilerplate Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Boilerplate project

This repository represents the typical project structure at Lonestone, consisting of an API and one to several frontends.

Start new projects with the versioned installer described below. It resolves the latest published boilerplate release by default, so projects never start from unreleased changes on `main`.

For more details, see the [documentation](https://lonestone.github.io/lonestone-boilerplate/) or check out the local documentation in the `apps/documentation` folder.

[![CI ✨](https://github.com/lonestone/lonestone-boilerplate/actions/workflows/ci.yml/badge.svg)](https://github.com/lonestone/lonestone-boilerplate/actions/workflows/ci.yml)
[![Deploy documentation to GitHub Pages](https://github.com/lonestone/lonestone-boilerplate/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/lonestone/lonestone-boilerplate/actions/workflows/deploy-docs.yml)

## 📋 Table of Contents

- [Overview](#-overview)
- [Tech Stack](#️-tech-stack)
- [Project Structure](#-project-structure)
- [Prerequisites](#-prerequisites)
- [Installation](#-installation)
- [Docker Services](#-docker-services)
- [Useful Commands](#️-useful-commands)
- [Development](#-development)
- [Continuous Integration (CI)](#-continuous-integration-ci)
- [Documentation](#-documentation)
- [Deployment](#-deployment)

## 🔍 Overview

This project uses a "monorepo" architecture. The advantages are numerous, but primarily:

- Ability to develop full-stack features without context switching, making a single PR for a complete feature;
- Easier deployment: no need to synchronize multiple separate deployments;
- Strong end-to-end typing, easier refactoring;
- Simplified and unified tooling (linter, build, etc.)

## 🛠️ Tech Stack

See the [Architecture](apps/documentation/src/content/docs/explanations/1_architecture.mdx) page for more details.

## 📁 Project Structure

See the [Project Structure](apps/documentation/src/content/docs/explanations/1_architecture.mdx) page for more details.

## 📋 Prerequisites

- [Node.js](https://nodejs.org/) (version 24.13.0)
- [PNPM](https://pnpm.io/) (version 10.28.2)
- [Docker](https://www.docker.com/) and [Docker Compose](https://docs.docker.com/compose/)

## 🚀 Installation

### Create a new project

Run the installer from the directory that should contain the new project:

```bash
curl -fsSL https://raw.githubusercontent.com/lonestone/lonestone-boilerplate/main/install.sh \
  | sh -s -- init my-project
```

The installer resolves the latest stable `vX.Y.Z` tag, creates the project, installs dependencies, and runs the interactive `pnpm rock` setup. Pin a specific release when reproducibility requires it:

```bash
curl -fsSL https://raw.githubusercontent.com/lonestone/lonestone-boilerplate/main/install.sh \
  | sh -s -- init my-project --ref v1.0.0
```

`--ref` accepts only `latest` (the default) or an explicit release tag such as `v1.0.0`. Branches such as `main` are intentionally rejected.

### Onboard an existing project

Run this once at the root of a project originally generated from the boilerplate but not yet tracked by Boilerstone:

```bash
curl -fsSL https://raw.githubusercontent.com/lonestone/lonestone-boilerplate/main/install.sh \
  | sh -s -- onboard
```

Then inspect and prepare the latest applicable upgrade:

```bash
pnpm boilerplate upgrade status
pnpm boilerplate upgrade
```

The upgrade command stages release intentions and references on a dedicated branch; it does not overwrite application code automatically. See the [Boilerstone overview](.boilerstone/README.md), [how it works](.boilerstone/docs/how-it-works.md), and the [upgrade runbook](.boilerstone/docs/upgrade-runbook.md) for the complete lifecycle.

### Prerequisites and manual setup

Ensure you have the correct Node.js and pnpm versions (see the root `package.json` file's `engines` property).

You can use [fnm](https://github.com/Schniz/fnm) for managing your node version

```bash
fnm use 24.13.0
npm i -g pnpm@10.28.2
```

When working from an existing checkout rather than the installer, install dependencies manually:

```bash
pnpm install
```

Then run the setup script:

The project includes an automated setup script that will:
- Detect available applications (API, Web SPA, Web SSR, OpenAPI Generator)
- Prompt you for database configuration (user, password, name, host, port)
- Prompt you for application ports
- Configure SMTP settings (MailDev)
- Copy and configure all `.env` files automatically
- Optionally start Docker services (database, MailDev)
- Optionally run database migrations

```bash
pnpm rock
```

The script will guide you through the configuration process interactively. It will:
- Ask for your project name
- Update package.json files for detected applications with the project name
- Check for existing `.env` files and only prompt for missing variables
- Automatically update all `.env` files with your configuration
- Set up proper API URLs and trusted origins across all applications

Start applications in development mode:

```bash
pnpm dev
```

### Manual Setup (Alternative)

If you prefer to configure everything manually:

1. Copy environment files:

```bash
cp .env.example .env
cp apps/api/.env.example apps/api/.env
cp apps/web-spa/.env.example apps/web-spa/.env
cp apps/web-ssr/.env.example apps/web-ssr/.env
cp packages/openapi-generator/.env.example packages/openapi-generator/.env
```

⚠️ In most of those `.env` files, the API url and port are used. Remember to update all the files to match your API url and port.

2. Start Docker services:

```bash
pnpm docker:up
```

3. Run migrations or set up your schema by following the instructions in the [API README](apps/api/README.md).

## 🐳 Docker Services

The project uses Docker Compose to provide the following services:

- PostgreSQL - Database server
- MailDev - SMTP server for development (not to be used in production!)
- MinIO - S3 compatible storage solution (not to be used in production!)

## ⌨️ Useful Commands

### Docker

- **Start Docker services**: `pnpm docker:up`
- **Stop Docker services**: `pnpm docker:down`
- **View Docker logs**: `pnpm docker:logs`

### Development

- **Start development**: `pnpm dev`
- **Build applications**: `pnpm build`
- **Lint applications**: `pnpm lint`
- **Format code**: `pnpm fmt`
- **Generate OpenAPI clients**: `pnpm generate`

### Database (API)

- **Create migration**: `pnpm db:migrate:create`
- **Run migrations**: `pnpm db:migrate:up`
- **Rollback last migration**: `pnpm db:migrate:down`
- **Initialize data**: `pnpm db:seed`

### Tests

- **Run tests**: `pnpm test`

## 💻 Development

### Applications

- The API is built with NestJS and provides a REST API. See the [API README](apps/api/README.md) for more information.
- The web-spa is built with React and provides a single-page application. See the [Web SPA README](apps/web-spa/README.md) for more information.
- The web-ssr is built with React and provides a server-side rendered application. See the [Web SSR README](apps/web-ssr/README.md) for more information.

You can start each application in development mode with the following commands:

```bash
# Start API in development mode from root folder
pnpm --filter=api dev
```

```bash
# Start API from its own folder
cd apps/api && pnpm dev
```

### Shared Packages

- UI -> Reusable UI components built with shadcn/ui.
- OpenAPI Generator -> contains the generator plus the generated types, validators and sdk for frontend-backend communication. Imported by the frontend apps.

## 🔄 Continuous Integration (CI)

The project uses GitHub Actions for continuous integration. Workflows are defined in the `.github/workflows/` folder.

### CI Workflow

The CI workflow (`ci.yml`) runs on every push to the `main` and `master` branches, as well as on pull requests to these branches.

It includes the following jobs:

- **Lint & Format**: Checks code with oxlint and oxfmt
- **Type Check**: Checks TypeScript types for all packages and applications
- **Build**: Builds all packages and applications

For more information, see the [GitHub Actions documentation](.github/ACTIONS.md).

### CD Workflow

This workflow generates a Docker image into the Github Registry (GHCR) for the api
web-spa and web-ssr should not use this pattern and prefer a build-on-deploy instead

This is a recommended workflow for production apps instead of building directly from your deployment server (Dokploy, Render) as it allows you to tag each release, deploy staging and prod on the same artifact, and decrease load on your deployment server

To enable the CD workflow go to `.github/workflows/push-to-ghcr.yml` and uncomment the top block

### AI Agents good practice
When working with an AI Agent (such as Copilot, Cursor or Claude), please follow these guidelines:

- Do not add rules to the repo. You are encouraged to create your own so that it benefits several projects.
- Exception: the `.claude/skills/boilerstone-*/` and `.cursor/skills/boilerstone-*/` directories are committed product shims for the boilerplate upgrade system; they must stay thin and point to the runbooks in `.boilerstone/docs/`.
- If the agent needs markdown documents (like specifications or TODO task), write them in a dedicated folder in docs/features

## 📚 Documentation

The stack technical documentation is available in the `apps/documentation/` folder. It contains information about architecture, coding conventions, and development guides. A index listing all the avaible documentation can be found at `apps/documentation/INDEX.md`.

After cloning this repo, we advise putting your project specific documentation in the `docs/` folder and in app `README`s. This contains information about your the "business" side of the project. But you can also use `apps/documentation` as the center of all docs, it's up to you.

This documentation is also used by our custom cursor rules.

- [General Guidelines](apps/documentation/src/content/docs/references/general.mdx)
- [Frontend Guidelines](apps/documentation/src/content/docs/references/frontend.mdx)
- [Backend Guidelines](apps/documentation/src/content/docs/references/backend.mdx)
- [API Readme](apps/api/README.md)
- [Frontend Readme](apps/web-spa/README.md)
- [Boilerplate upgrade system](.boilerstone/README.md) — keep a project in sync with this template (human or AI executed, removable)

The `docs/features` directory should contain a list of folder for each new features. In those you can write specification document and TODO tasks for a feature you are implementing. Feature specifications can can also point toward README.md files inside the packages' features, that should provide more details about the implementation within the scope of the package.

## 🔍 Tracing Architecture

The project uses a unified OpenTelemetry tracing architecture that integrates both Sentry and Langfuse:

- **Shared TracerProvider**: A single OpenTelemetry TracerProvider manages traces for both Sentry (application monitoring) and Langfuse (AI/LLM tracing)
- **Distributed Tracing**: Traces are automatically propagated across services, allowing you to see the full request flow
- **AI Tracing**: All AI/LLM calls are automatically traced in Langfuse with full prompt visibility, token usage, and latency metrics
- **Application Tracing**: All application spans (controllers, services, database queries) are traced in Sentry for performance monitoring and error tracking

The tracing system is initialized in `apps/api/src/instrument.ts` and automatically started when the API server boots. See the [AI module documentation](apps/api/src/modules/ai/README.md) and [tracing documentation](apps/documentation/src/content/docs/core-features/2_monitoring.mdx) for more details.

## 🚀 Deployment

It's your choice to decide how you want to deploy the applications, your main options being:

- Use a PaaS cloud service like Render or Dokploy which will build and host your services
- Build the applications, via Docker, and publish their image on a registry to be used by Render or other PaaS
- Use docker-compose (not recommended).

### Building with Docker

#### Prerequisites

- Docker installed on your machine
- Node.js and pnpm for local development

See the dedicated README files for more details on how to build and run Docker images.

### Deployment with Docker Compose

An example Docker Compose configuration is available in the `docker-compose.yml` file at the project root.

lonestone-boilerplate

lonestone-boilerplate Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

lonestone-boilerplate

lonestone-boilerplate Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README