tsprepare

CLI tool to scaffold, validate, and fix TypeScript package configurations for proper module setup with dual ESM/CJS support.

Installation

npm install -g tsprepare

Or use with npx:

npx tsprepare <command>

Commands

tsprepare init

Initialize a new TypeScript package with best practices.

tsprepare init                    # Interactive mode
tsprepare init -n my-package      # Specify package name
tsprepare init -d                 # Setup dual ESM/CJS build
tsprepare init -y                 # Skip prompts, use defaults

Options:

• -n, --name <name> - Package name
• -d, --dual - Setup dual ESM/CJS build from the start
• -y, --yes - Skip prompts and use defaults

tsprepare check

Validate current TypeScript package configuration for publishing.

tsprepare check                   # Check current directory
tsprepare check -p ./my-package   # Check specific path
tsprepare check --strict          # Enable strict validation

Options:

• -p, --path <path> - Path to project directory (default: ".")
• --strict - Enable strict validation mode

What it checks:

• ✅ package.json required fields (name, version)
• ✅ Types/typings field for TypeScript consumers
• ✅ Exports field for modern Node.js
• ✅ Files field for publish optimization
• ✅ Build scripts
• ✅ tsconfig.json settings (declaration, outDir, strict mode)

tsprepare fix

Auto-fix common TypeScript package configuration issues.

tsprepare fix                     # Fix current directory
tsprepare fix -p ./my-package     # Fix specific path
tsprepare fix --dry-run           # Preview changes without applying

Options:

• -p, --path <path> - Path to project directory (default: ".")
• --dry-run - Show what would be fixed without making changes

What it fixes:

• 🔧 Missing "types" field in package.json
• 🔧 Missing "exports" field
• 🔧 Missing "files" field
• 🔧 Missing build scripts
• 🔧 TypeScript declaration generation
• 🔧 Source maps and declaration maps
• 🔧 Output directory configuration

tsprepare dual

Add dual ESM/CJS build configuration to existing TypeScript project.

tsprepare dual                    # Setup with tsup (default)
tsprepare dual --bundler unbuild  # Use unbuild instead
tsprepare dual --bundler rollup   # Use rollup instead

Options:

• -p, --path <path> - Path to project directory (default: ".")
• --bundler <bundler> - Bundler to use: tsup, unbuild, rollup (default: "tsup")

What it does:

1. Installs the chosen bundler as a dev dependency
2. Creates bundler configuration file
3. Updates package.json with dual entry points
4. Updates tsconfig.json for bundler usage
5. Sets up build and dev scripts

Programmatic API

import { 
  validatePackage, 
  getValidationReport,
  scaffoldPackage,
  fixIssues,
  setupDualBuild,
  analyzeProject 
} from 'tsprepare';

// Analyze a project
const analysis = analyzeProject('./my-package');

// Validate a package
const result = validatePackage('./my-package', { strict: true });
console.log(result.valid, result.issues, result.score);

// Get detailed report
const report = getValidationReport('./my-package');
console.log(report.categorized.errors);

// Scaffold a new package
const scaffold = scaffoldPackage('./new-package', {
  name: 'my-awesome-lib',
  dual: true
});

// Fix issues
const fixes = fixIssues('./my-package', { dryRun: false });

// Setup dual build
const dual = setupDualBuild('./my-package', { bundler: 'tsup' });

Validation Scores

tsprepare check provides a validation score (0-100):

| Score | Status | |-------|--------| | 80-100 | 🟢 Ready for publishing | | 50-79 | 🟡 Publishable with warnings | | 0-49 | 🔴 Critical issues to fix |

Scoring:

• Errors: -20 points each
• Warnings: -10 points each
• Info: -2 points each

Why tsprepare?

Setting up TypeScript packages correctly can be tricky:

• Should I use ESM or CommonJS?
• How do I configure exports for both formats?
• What tsconfig settings do I need?
• Why aren't my types working?
• How do I set up a proper build pipeline?

tsprepare solves these problems by:

1. Scaffolding - Creates packages with best practices from the start
2. Validation - Checks your configuration is correct
3. Auto-fixing - Automatically fixes common issues
4. Dual builds - Easy setup for ESM + CJS support

Example Workflow

# Create a new TypeScript package with proper config
mkdir my-lib && cd my-lib
npx tsprepare init -n my-lib -d

# Install dependencies
npm install

# Write your code in src/index.ts
# ...

# Check your configuration before building
npx tsprepare check

# If issues are found, auto-fix them
npx tsprepare fix

# Build your package
npm run build

Best Practices Included

When you run tsprepare init, you get:

my-package/
├── src/
│   └── index.ts        # Entry point
├── package.json        # Properly configured
├── tsconfig.json       # Optimal settings
├── .gitignore
├── .npmignore          # Excludes source from npm
└── README.md

package.json includes:

• Proper main, module, and types fields
• Modern exports field with conditions
• files array for clean publishes
• Build and prepublishOnly scripts

tsconfig.json includes:

• Declaration generation enabled
• Declaration maps for "Go to Definition"
• Source maps for debugging
• Strict mode for type safety
• Modern module resolution

License

MIT © Harshit