nanoweb-mono

📖 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

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

🔧 Setting Up the Monorepo

🔢 Work within the monorepo.

• Clone the repository:

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

• 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.

• Prepare packages for the usage in the workspace:

  pnpm ws:pull
  pnpm build
  

• 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.

• Ensure all changes are committed and pushed.
• 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

• Create a new branch:

  git checkout -b feature/my-update
  

• Make changes and commit:

  git commit -m "Add new feature"
  

• Push your branch and open a merge request.

⚙️ Useful Utility Scripts

Command	Description
pnpm ws:init	Initialize workspace & install packages
pnpm ws:check	Validate package.json & pre-commit hooks
pnpm ws:latest	Replace workspace:* with actual versions
pnpm ws:workspace	Convert all versions to workspace:*
pnpm ws:optimize	Clean, install, update, lint, build, test
pnpm ws:status	Check uncommitted changes in all packages
pnpm release	Build, test, tag, and publish package
pnpm clone	Cloning missing packages into the monorepo

🛠️ 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! 🛸