@gozenc/packer

A CLI tool with essential package builder scripts for React library projects. Streamline your React library development workflow with version management, documentation syncing, and package testing utilities.

Features

• 🔢 Version Bumping: Interactive or automated version updates across package files
• 📚 Documentation Sync: Automatically sync built documentation to GitHub Pages
• 🧪 Package Testing: Verify package structure and test locally before publishing
• 🌐 Browser Testing: Local development server for testing built packages
• ⚡ Zero Config: Works out of the box with standard React library setups

Installation

Install globally to use across all your projects:

npm install -g @gozenc/packer

Or install as a dev dependency in your project:

npm install --save-dev @gozenc/packer

Usage

Global Installation

If installed globally, use the packer command directly:

packer <command> [options]

Local Installation

If installed locally, add scripts to your package.json:

{
  "scripts": {
    "bump": "packer bump",
    "docs": "packer docs",
    "verify": "packer verify",
    "preview": "packer preview"
  }
}

Then run with npm:

npm run bump

Commands

packer bump [version]

Bump the package version across all relevant files.

Interactive mode (prompts for version):

packer bump

Direct version (specify version):

packer bump 1.2.3

Updates:

• package.json
• package-lock.json
• docs.html (softwareVersion in JSON-LD, if exists)
• docs/index.html (softwareVersion in JSON-LD, if exists)

packer docs

Sync documentation from docs.html to docs/ directory for GitHub Pages or Cloudflare Pages.

packer docs

This command:

• Copies docs.html → docs/index.html
• Copies dist/ → docs/dist/

Configuration Options:

packer docs --dist=build --docs-dir=public --docs-file=index.html

Available parameters:

• --dist - Build directory (default: dist)
• --docs-dir - Documentation output directory (default: docs)
• --docs-file - Source HTML file (default: docs.html)

Note: The docs/ folder should be added to .gitignore to avoid committing generated files. Only docs.html (the source file) should be committed to your repository.

packer verify

Comprehensive package verification before publishing. This command builds, packs, and thoroughly tests your package to ensure it's ready for npm.

packer verify

This command:

1. Builds the package (npm run build)
2. Packs it (npm pack)
3. Extracts and verifies the tarball structure
4. Checks for required files (package.json, README.md, LICENSE, dist files)
5. Analyzes bundle size
6. Verifies no react-jsx-runtime is bundled (critical for React libraries)
7. Cleans up temporary files

Configuration Options:

packer verify --dist=build

Available parameters:

• --dist - Build directory to verify (default: dist)

This is the most thorough test and should be run before publishing to npm.

packer preview

Start a local HTTP server to preview your documentation in a browser.

packer preview

Configuration Options:

packer preview --host=localhost --port=3000 --docs-dir=public

Available parameters:

• --host - Server host (default: 127.0.0.1)
• --port - Server port (default: 8080)
• --docs-dir - Documentation directory to serve (default: docs)

Default behavior:

• Serves files from project root
• Default URL: http://127.0.0.1:8080/
• Serves docs/index.html at root path
• Press Ctrl+C to stop the server

Project Structure

This tool expects your React library project to follow this structure:

your-project/
├── dist/              # Built package output (gitignored)
├── docs/              # Generated docs for Pages hosting (gitignored)
├── docs.html          # Source HTML file for documentation
├── src/               # Source files
├── package.json
└── package-lock.json

Important: Add the following to your .gitignore:

# Build outputs
dist/

# Docs folder (generated from docs.html)
docs/

This keeps your repository clean by only tracking the source docs.html file, not the generated docs/ folder.

Typical Workflow

Here's a typical release workflow using packer:

# 1. Verify package (builds, packs, and tests)
packer verify

# 2. Preview docs in browser (optional)
packer preview

# 3. Sync documentation
packer docs

# 4. Bump version
packer bump

# 5. Publish to npm
npm publish

Or combine steps in a release script:

{
  "scripts": {
    "release": "packer verify && packer docs && packer bump && npm publish"
  }
}

Requirements

• Node.js >= 18.0.0
• npm or yarn
• Standard React library build setup (TypeScript + Vite recommended)

Examples

See these projects using @gozenc/packer:

• @gozenc/react-tooltip
• @gozenc/react-dark-mode-toggle

License

MIT © Fatih Gözenç

Contributing

Issues and pull requests are welcome! Please visit the GitHub repository.