npm package: @polymer-labs/monomer
Description: Monomer - Lightweight package manager with essential commands only
Author: Polymer Labs
Latest version: 1.0.0

# 🧪 Monomer

**Monomer** is a lightweight package manager with essential commands only. It's a stripped-down version of [Gel](../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

```bash
npm install -g @polymer-labs/monomer
```

Or use it directly with npx:
```bash
npx @polymer-labs/monomer bond express
```

## Quick Start

```bash
# 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.

```bash
# Install all dependencies
mono bond

# Add packages
mono bond express body-parser
mono bond lodash@4.17.21

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

```bash
# 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.

```bash
# 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).

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

# With specific versions
mono @ typescript@4.9.5 --version
mono @ @babel/cli@7.21.0 --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:

```json
{
  "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:
```bash
export NPM_REGISTRY="https://my-registry.com"
mono bond express
```

## Examples

### Creating a New Project

```bash
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

```dockerfile
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

```bash
# 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:

```bash
rm -rf ~/.monomer/cache
mono bond
```

### Network Issues

Set a custom registry:

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

### Permission Errors

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

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

## API

Monomer can also be used programmatically:

```javascript
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](https://github.com/polymer-labs/gelpk) for contribution guidelines.

## License

MIT

## Related

- [Gel](../gel) - Full-featured package manager
- [Crystal Cache](../crystal-cache) - Advanced deduplication system
- [Gel Molds](../gel-molds) - Package templates

---

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