🧪 Monomer

Monomer is a lightweight package manager with essential commands only. It's a stripped-down version of Gel designed for minimal use cases where you only need basic package management functionality.

Features

✨ 4 Essential Commands

• bond - Install dependencies
• dissolve - Remove packages
• run - Execute npm scripts
• @ - Execute packages without installing (like npx)

🪶 Lightweight

• Minimal dependencies
• Simple cache system (no symlinks)
• Straightforward implementation
• Fast operations

📦 Compatible

• Works with npm registry
• Uses standard package.json
• Creates monomer-lock.json for deterministic installs

Installation

npm install -g @polymer-labs/monomer

Or use it directly with npx:

npx @polymer-labs/monomer bond express

Quick Start

# Install all dependencies from package.json
mono bond

# Add specific packages
mono bond express lodash chalk

# Remove packages
mono dissolve express

# Run npm scripts
mono run dev
mono run test

# Execute packages without installing (like npx)
mono @ cowsay "Hello from Monomer!"
mono @ create-react-app my-app

Commands

mono bond [packages...]

Install dependencies from package.json or add specific packages.

# Install all dependencies
mono bond

# Add packages
mono bond express body-parser
mono bond [email protected]

# With options
mono bond --save-dev jest
mono bond --prod  # Install only production deps

Options:

• -D, --save-dev - Save as dev dependency
• --prod - Install only production dependencies
• --force - Force reinstall packages

mono dissolve <packages...>

Remove packages from your project.

# Remove single package
mono dissolve express

# Remove multiple packages
mono dissolve lodash axios moment

This will:

• Remove from node_modules/
• Remove from package.json
• Update monomer-lock.json

mono run <script> [args...]

Execute scripts defined in package.json.

# Run scripts
mono run dev
mono run build
mono run test

# Pass arguments
mono run test -- --coverage
mono run build -- --production

mono @ <package> [args...]

Execute a package without installing it globally (like npx).

# Execute packages
mono @ cowsay "Hello World"
mono @ create-react-app my-app
mono @ typescript --version

# With specific versions
mono @ [email protected] --version
mono @ @babel/[email protected] --help

How It Works

Simple Cache System

Monomer uses a straightforward cache at ~/.monomer/cache/:

~/.monomer/cache/
├── express/
│   └── 4.18.2/
├── lodash/
│   └── 4.17.21/
└── chalk/
    └── 4.1.2/

Unlike Gel's crystal-cache with symlinks, Monomer just copies files directly. It's simpler but uses more disk space.

Package Resolution

Monomer fetches packages directly from the npm registry:

1. Resolves version (latest, tags, semver ranges)
2. Downloads tarball
3. Extracts to cache
4. Copies to node_modules

Lockfile

Monomer creates monomer-lock.json to ensure deterministic installs:

{
  "express": {
    "version": "4.18.2",
    "resolved": "https://registry.npmjs.org/express/-/express-4.18.2.tgz",
    "dependencies": {
      "accepts": "~1.3.8",
      "body-parser": "1.20.1"
    }
  }
}

When to Use Monomer vs Gel

Use Monomer when:

• ✅ You only need basic package management
• ✅ You want a minimal, straightforward tool
• ✅ You're working on simple projects
• ✅ You don't need advanced features

Use Gel when:

• ✅ You need advanced features (workspaces, parallel installs)
• ✅ You want crystal-cache deduplication
• ✅ You need heal, verify, snapshot, etc.
• ✅ You're working on complex monorepos

Comparison with Gel

| Feature | Monomer | Gel | |---------|---------|-----| | Commands | 4 essential | 22+ comprehensive | | Cache | Simple copy | Crystal-cache (symlinks) | | Dependencies | Minimal | Full-featured | | Install size | ~5 MB | ~15 MB | | Speed | Fast | Very fast (parallel) | | Lockfile | monomer-lock.json | gel.lock | | Workspaces | ❌ | ✅ | | Parallel installs | ❌ | ✅ | | Auto-heal | ❌ | ✅ | | Verification | ❌ | ✅ (SHA-256) | | Snapshots | ❌ | ✅ | | Plugin system | ❌ | ✅ |

Configuration

Monomer respects these environment variables:

• NPM_REGISTRY - Custom npm registry URL (default: https://registry.npmjs.org)
• MONOMER_CACHE - Custom cache directory (default: ~/.monomer/cache)

Example:

export NPM_REGISTRY="https://my-registry.com"
mono bond express

Examples

Creating a New Project

mkdir my-project
cd my-project

# Initialize package.json
echo '{"name":"my-project","version":"1.0.0"}' > package.json

# Install dependencies
mono bond express body-parser

# Add a start script
echo '{"scripts":{"start":"node index.js"}}' >> package.json

# Run it
mono run start

Using with Docker

FROM node:18-alpine

WORKDIR /app

# Install monomer globally
RUN npm install -g @polymer-labs/monomer

# Copy package files
COPY package.json monomer-lock.json ./

# Install dependencies
RUN mono bond --prod

# Copy app
COPY . .

CMD ["mono", "run", "start"]

Execute One-Off Commands

# Quick scaffolding
mono @ create-react-app my-app
mono @ create-next-app my-next-app

# One-off utilities
mono @ json -f package.json dependencies
mono @ prettier --write "**/*.js"
mono @ typescript index.ts

# Fun stuff
mono @ cowsay "Monomer is awesome!"
mono @ figlet "Hello World"

Troubleshooting

Clear Cache

If you encounter issues, try clearing the cache:

rm -rf ~/.monomer/cache
mono bond

Network Issues

Set a custom registry:

export NPM_REGISTRY="https://registry.npmmirror.com"
mono bond

Permission Errors

On Linux/Mac, you may need to fix permissions:

sudo chown -R $(whoami) ~/.monomer

API

Monomer can also be used programmatically:

const bond = require('@polymer-labs/monomer/src/commands/bond');
const dissolve = require('@polymer-labs/monomer/src/commands/dissolve');
const run = require('@polymer-labs/monomer/src/commands/run');
const instant = require('@polymer-labs/monomer/src/commands/instant');

// Install packages
await bond(['express', 'lodash']);

// Remove packages
await dissolve(['express']);

// Run script
await run('test');

// Execute package
await instant('cowsay', ['Hello!']);

Contributing

Monomer is part of the Polymer Labs ecosystem. See the main repository for contribution guidelines.

License

MIT

Related

• Gel - Full-featured package manager
• Crystal Cache - Advanced deduplication system
• Gel Molds - Package templates

Monomer - Essential package management, nothing more, nothing less. 🧪