Skip to content

README.md

Latest commit

 

History

History
228 lines (169 loc) · 7.53 KB

README.md

File metadata and controls

228 lines (169 loc) · 7.53 KB

PackDev Documentation

Welcome to the comprehensive documentation for packdev - the TypeScript-based CLI tool for managing package dependencies during development using local paths or git repositories.

📚 Documentation Index

🚀 Getting Started

  • Main README - Project overview, installation, and quick start guide
  • Workflow Guide - Complete workflow patterns and best practices

📦 Package Management

🛡️ Safety & Security

  • GitHub Hooks - Pre-commit safety hooks to prevent accidental commits

📖 Quick Navigation

By Use Case

I want to... Read this guide
Get started quickly Main README
Understand the workflow Workflow Guide
Package for distribution Packaging Guide
Use with Yarn Yarn Support
Prevent commit mistakes GitHub Hooks
Learn best practices Workflow Guide
Troubleshoot issues Packaging Guide + Yarn Support

By Experience Level

🆕 New Users

  1. Start with Main README
  2. Follow Workflow Guide examples
  3. Set up GitHub Hooks for safety

🔧 Experienced Users

👥 Team Leads

📋 Document Details

Main README (500+ lines)

  • Purpose: Project overview and quick start
  • Contains: Installation, basic usage, examples
  • Audience: All users
  • Updated: Latest

Workflow Guide (388 lines)

  • Purpose: Complete workflow patterns and best practices
  • Contains: Init/finish cycles, configuration persistence, team collaboration
  • Audience: All users, especially teams
  • Key Topics: Configuration persistence, safety features, advanced workflows

Packaging Guide (316+ lines)

  • Purpose: Building and distributing packages
  • Contains: npm/Yarn packaging, local installation, troubleshooting
  • Audience: Package maintainers, CI/CD setup
  • Key Topics: Cross-platform packaging, testing, distribution methods

Yarn Support (370 lines)

  • Purpose: Comprehensive Yarn package manager support
  • Contains: Yarn-specific commands, migration guides, performance tips
  • Audience: Yarn users, teams migrating from npm
  • Key Topics: Auto-detection, command equivalents, workspaces

GitHub Hooks (373 lines)

  • Purpose: Pre-commit safety hooks to prevent accidental commits
  • Contains: Hook setup, usage patterns, team integration
  • Audience: All users, especially teams
  • Key Topics: Safety checks, WIP commits, troubleshooting

🎯 Common Workflows

Daily Development

# Morning
packdev init  # Automatically installs dependencies

# Evening  
packdev finish  # Automatically restores and reinstalls
git commit -m "implement feature X"

📖 Read: Workflow Guide - Daily Development Cycle

Team Collaboration

# Setup hooks for team safety
packdev setup-hooks
# Hooks are automatically installed in .git/hooks/

# Share configuration
git add .packdev.json
git commit -m "add local development config"

📖 Read: GitHub Hooks - Team Setup

Package Distribution

# Build and test package
npm run pack
npm run test-install

# Distribute
npm publish  # or share .tgz file

📖 Read: Packaging Guide - Distribution Methods

Yarn Migration

# Migrate from npm to Yarn
rm package-lock.json
yarn install

# Use Yarn-specific commands
yarn pack
yarn add file:./package.tgz

📖 Read: Yarn Support - Migration Guide

🔍 Finding Information

Search by Topic

Configuration Management

Package Managers

Safety & Security

Troubleshooting

Command Reference

Command Primary Guide Additional Info
packdev init Main README Workflow Guide
packdev finish Main README Workflow Guide
packdev add Main README Workflow Guide
packdev remove Main README Workflow Guide
packdev setup-hooks GitHub Hooks Main README
packdev status Main README Workflow Guide

Quick References

Need Guide Alternative
5-minute start Quick Start Main README
Common commands Quick Start Workflow Guide

🚀 Demo Scripts

Interactive demonstrations are available:

# Complete workflow demonstration
npm run demo-workflow

# Interactive workflow walkthrough
npm run demo-workflow --interactive

# GitHub hooks demonstration  
npm run demo-hooks

# Interactive hook testing
npm run demo-hooks --interactive

# Package installation testing
npm run test-install

# Comprehensive package information
npm run package-info

📝 Contributing to Documentation

When updating documentation:

  1. Keep guides focused - Each document has a specific purpose
  2. Cross-reference liberally - Link to related information
  3. Update this index - When adding new documents
  4. Test examples - Ensure all code examples work
  5. Consider audience - Write for the intended user level

Documentation Standards

  • Headers: Use emoji + descriptive titles
  • Code blocks: Include language specification
  • Examples: Provide working, testable examples
  • Links: Use relative paths for internal links
  • Structure: Follow established patterns

📊 Documentation Stats

  • Total Documents: 5 comprehensive guides
  • Total Lines: 1,900+ lines of documentation
  • Coverage: Complete workflow, packaging, safety, and package manager support
  • Maintenance: Actively maintained and tested

🎉 Quick Links

This documentation index is maintained as part of PackDev. For the most up-to-date information, always refer to the latest version of each guide.