nanoweb-mono v1.7.0

📖 Monorepo Usage Guide

This guide covers how to set up, manage, and maintain the nanoweb monorepo, including package dependencies, scripts, and automated workflows.

📌 Project Structure

The monorepo follows a pnpm workspace setup with multiple packages:

root/
├── apps/           # Your apps
├── bin/            # Utility scripts
│   ├── clean.js
│   ├── create-app.js
│   ├── create-package.js
│   ├── lint.js
│   ├── llm.js
│   ├── optimize.js
│   ├── release.js
│   ├── workspace.js
│   ├── write-docs.js
├── packages/       # All packages in the workspace
│   ├── nano-db-fs
│   ├── nano-db-fetch
│   ├── nano-format
│   ├── nanoweb-cli
│   ├── nanoweb-fs
│   ├── nanoweb-llm
│   ├── nanoweb-react
│   ├── nanoweb-sync
│   ├── nanoweb-sync-ftp
│   ├── nanoweb-sync-php
│   ├── nanoweb-theme
├── pnpm-workspace.yaml # Defines workspace packages
├── package.json    # Root package.json (manages workspace commands)
└── eslint.config.js # ESLint configuration

🔗 Requirements

1. Node.js runtime environment You must have the node v22+ installed.
2. The pnpm package manager You must have the pnpm package manager installed.

🔧 Setting Up the Monorepo

🔢 Work within the monorepo.
1. Clone the repository:

git clone https://gitlab.com/nan.web/monorepo.git nanoweb && cd nanoweb

2. Initialize workspace and install dependencies:

   pnpm install
   pnpm ws:clone
   # runs the ws:optimize within the ws:init
   pnpm ws:init

   This command clones all missing package repositories, ensures correct dependencies, and installs them.

3. Prepare packages for the usage in the workspace:

   pnpm ws:pull
   pnpm build

4. Run optimization (optional, recommended after setup, if did not run within the ws:init):

   pnpm ws:optimize

   This command:

   • Cleans unnecessary cache and dependencies
   • Updates dependencies to their latest versions
   • Runs linter and tests

🚗 Running the Development Environment

1️⃣ Work only within the specific project.
Change the directory to the specific package, for instance: cd packages/nano-format.

• Start the development server:

  pnpm dev

• Run tests across all packages:

  pnpm test:all

• Run nanoweb-mono tests:

  pnpm test

• Build all packages:

  pnpm build:all

• Lint all packages:

  pnpm lint:all

🔄 Managing Dependencies & Versions

Updating Dependencies

1️⃣🔢 Work within the specific package and within the monorepo.
Before committing, ensure all workspace: dependencies are replaced with their actual versions:

pnpm ws:latest

If you plan to work on multiple interdependent packages, switch all dependencies to workspace:*:

pnpm ws:workspace

Checking for Issues Before Commit

Run the following to check for uncommitted workspace dependencies and pre-commit hooks:

pnpm ws:check

Checking Git Status Across All Packages

pnpm ws:status

🏗 Releasing Packages

1️⃣ Work within the specific package.
Change the directory to the specific package, for instance: cd packages/nano-format.
1. Ensure all changes are committed and pushed.
2. Run the release script inside the package:

pnpm release

This will:

• Run all tests and linting
• Build the package
• Tag the new version in Git
• Publish to npm
• Push all commits and tags

🛸 Contributing

1. Create a new branch:

   git checkout -b feature/my-update

2. Make changes and commit:

   git commit -m "Add new feature"

3. Push your branch and open a merge request.

⚙️ Useful Utility Scripts

🛠️ Troubleshooting

• Dependency Issues: Run pnpm ws:optimize to clean and reinstall.
• Build Errors: Ensure all dependencies are up to date with pnpm ws:latest.
• Linting Issues: Run pnpm lint and fix reported errors.
• Pre-commit Hook Failures: Check .husky/pre-commit and ensure it includes workspace checks.

With these steps, you can efficiently manage and maintain the nanoweb monorepo! 🛸