penframe/docs/npm-publishing-guide.md

A lightweight DSL-based wireframe and UI structure visualization tool.

# NPM Publishing Guide for PenFrame

This document outlines the complete process for publishing PenFrame to npm.

## Prerequisites

1. **NPM Account**: Create an account at [npmjs.com](https://www.npmjs.com)
2. **CLI Access**: Ensure you have npm CLI installed
3. **Git Repository**: Project should be in a git repository
4. **Node.js**: Version 14.0.0 or higher

## Pre-Publishing Checklist

### 1. Code Quality Check
```bash
# Build the parser
npm run build

# Run all tests
npm test

# Verify package contents
npm pack --dry-run
```

### 2. Version Management
```bash
# Check current version
npm version

# Bump version (choose one)
npm version patch    # 0.1.0 -> 0.1.1 (bug fixes)
npm version minor    # 0.1.0 -> 0.2.0 (new features)
npm version major    # 0.1.0 -> 1.0.0 (breaking changes)
```

### 3. Documentation Update
- [ ] Update README.md with latest features
- [ ] Verify all examples work correctly
- [ ] Update CHANGELOG.md (if exists)
- [ ] Check LICENSE file

### 4. Package Configuration

Verify `package.json` contains:
- [x] Correct name and version
- [x] Description and keywords
- [x] Author and license information
- [x] Repository and homepage URLs
- [x] Main entry point (`dist/parser.js`)
- [x] Binary command (`penframe`)
- [x] Files to include in package
- [x] Dependencies (puppeteer)
- [x] Engine requirements (Node >= 14)

### 5. Files Structure Check

Package should include:
```
penframe/
├── dist/parser.js      # Built parser (main entry)
├── src/                # Source code
│   ├── cli.js         # Binary entry point
│   ├── ast2png.js     # PNG conversion CLI
│   └── svg/           # Conversion modules
├── examples/          # Sample files
│   ├── sample.pf      # Main example
│   └── ast_*.json     # AST examples
├── docs/              # Documentation
├── README.md          # Main documentation
├── LICENSE            # MIT license
└── package.json       # Package metadata
```

## Publishing Process

### Step 1: Login to NPM
```bash
npm login
# Enter your npm username, password, and email
```

### Step 2: Final Verification
```bash
# Test the package locally
npm pack
tar -tzf penframe-*.tgz | head -20

# Install locally to test
npm install -g ./penframe-*.tgz
penframe --help
```

### Step 3: Publish
```bash
# First time publishing
npm publish

# For scoped packages (if using @username/penframe)
npm publish --access public
```

### Step 4: Verify Publication
```bash
# Check on npm registry
npm view penframe

# Install from npm to test
npm install -g penframe
penframe examples/sample.pf --png test.png
```

## Post-Publishing Steps

### 1. Create Git Tag
```bash
git tag v0.1.0
git push origin v0.1.0
```

### 2. Update Repository
- Create a GitHub release
- Update repository description
- Add npm badge to README

### 3. Announce
- Share on social media
- Update project documentation
- Consider blog post or article

## Version Management Strategy

### Semantic Versioning (SemVer)
- **MAJOR** (1.0.0): Breaking changes
  - Grammar syntax changes
  - API breaking changes
  - Minimum Node.js version updates

- **MINOR** (0.2.0): New features
  - New UI elements (@table, @tabs, @badge, etc.)
  - New CLI options
  - New export formats

- **PATCH** (0.1.1): Bug fixes
  - SVG rendering fixes
  - Parser error fixes
  - Documentation updates

### Release Process
1. Create feature branch: `git checkout -b feature/new-element`
2. Implement and test changes
3. Update documentation
4. Create pull request
5. Merge to main
6. Bump version: `npm version minor`
7. Publish: `npm publish`
8. Create GitHub release

## Troubleshooting

### Common Issues

#### 1. Package name already exists
```bash
# Check if name is available
npm view penframe

# Options:
# 1. Choose different name
# 2. Use scoped package: @username/penframe
```

#### 2. Authentication errors
```bash
# Re-login
npm logout
npm login

# Check authentication
npm whoami
```

#### 3. Build failures
```bash
# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build
npm test
```

#### 4. Large package size
```bash
# Check package size
npm pack --dry-run

# Common exclusions in .npmignore:
# - tests/
# - output files
# - development configs
```

### Best Practices

1. **Test thoroughly**: Always test in clean environment
2. **Document changes**: Keep detailed changelog
3. **Version consistently**: Follow semantic versioning
4. **Monitor size**: Keep package size reasonable
5. **Respond to issues**: Monitor npm and GitHub for user feedback

## Automation (Optional)

### GitHub Actions for Auto-Publishing
Create `.github/workflows/npm-publish.yml`:

```yaml
name: Publish Package
on:
  release:
    types: [published]
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '16'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install
      - run: npm run build
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

## Resources

- [npm Documentation](https://docs.npmjs.com/)
- [Semantic Versioning](https://semver.org/)
- [npm CLI Reference](https://docs.npmjs.com/cli/)
- [Package.json Reference](https://docs.npmjs.com/cli/v7/configuring-npm/package-json)