wiki/prds/npm-package-maintenance.md

NPM Package Maintenance Guide

This document explains how to keep the create-markdown-sync npm package updated with the main markdown-sync app.

Overview

The CLI package lives in packages/create-markdown-sync/ and clones from github:waynesutton/markdown-site. When the main app changes, the CLI may need updates to stay compatible.

Package Location

packages/
  create-markdown-sync/
    package.json          # Version and dependencies
    tsconfig.json         # TypeScript config
    src/
      index.ts           # CLI entry point
      wizard.ts          # Interactive prompts
      clone.ts           # Template cloning
      configure.ts       # Site configuration
      install.ts         # Dependency installation
      convex-setup.ts    # Convex setup
      utils.ts           # Helper utilities
    dist/                # Built JavaScript (gitignored)

When to Update the CLI

Update the CLI package when:

1. New configuration options - Added to fork-config.json.example or siteConfig.ts
2. New wizard prompts needed - New features require user input during setup
3. Template structure changes - Files moved, renamed, or removed
4. Convex setup changes - Auth config, environment variables, or setup flow
5. Bug fixes - Issues discovered during user testing

Commands

Development

cd packages/create-markdown-sync

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

# Test locally via npm link
npm link
npx create-markdown-sync test-project

Publishing

cd packages/create-markdown-sync

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

# Publish to npm
npm publish --access public

# Verify publication
npm view create-markdown-sync

Checklist: Before Publishing

1. Push main app changes to GitHub first

   • The CLI clones from github:waynesutton/markdown-site
   • Template fixes must be in the remote repo

2. Test the full flow

   rm -rf test-project
   npx create-markdown-sync test-project
   cd test-project
   npx convex dev
   npm run sync
   npm run dev
   

3. Verify wizard prompts match fork-config.json.example

   • New options should have corresponding prompts
   • Defaults should match the example file

4. Update version number

   • Use semantic versioning
   • Update VERSION constant in src/index.ts if displayed

5. Build successfully

   npm run build
   # Should complete with no TypeScript errors
   

Sync Points

These files in the CLI should stay in sync with the main app:

CLI File	Syncs With	Purpose
wizard.ts	fork-config.json.example	All config options have prompts
configure.ts	scripts/configure-fork.ts	Same transformation logic
configure.ts	siteConfig.ts	Template fixes for known issues
convex-setup.ts	convex/auth.config.ts	Auth setup flow
utils.ts	Success message links	Docs URLs are current

Adding New Configuration Options

When a new option is added to fork-config.json.example:

1. Add prompt to wizard.ts

   // In the appropriate section
   const newOption = await prompts({
     type: 'confirm',
     name: 'newOption',
     message: 'Enable new feature?',
     initial: false,
   });
   

2. Add to WizardAnswers type

   export interface WizardAnswers {
     // ... existing fields
     newOption: boolean;
   }
   

3. Add to buildForkConfig in configure.ts

   function buildForkConfig(answers: WizardAnswers) {
     return {
       // ... existing fields
       newOption: answers.newOption,
     };
   }
   

4. Test the flow

   npm run build
   npm link
   npx create-markdown-sync test-project
   

Handling Breaking Changes

When the main app has breaking changes:

1. Update CLI to handle both old and new

   • Check for file existence before modifying
   • Use try/catch for optional operations

2. Bump major version if CLI behavior changes

   npm version major
   

3. Update README with migration notes

4. Consider backward compatibility period

   • Keep old logic for 1-2 releases
   • Add deprecation warnings

Troubleshooting

"Template cloned but configuration failed"

The template likely has syntax errors or missing files. Check:

• siteConfig.ts for embedded quotes or syntax issues
• fork-config.json.example for valid JSON

"Convex setup blocked by WorkOS"

The CLI should disable auth by default. Check:

• configure.ts disableAuthConfig() function
• convex/auth.config.ts in the template

"TypeScript build errors"

Usually caused by:

• Missing type definitions
• Spread operator ordering (put spread first, then defaults)
• Import path issues (.js extensions required for ESM)

Version History

Version	Changes
0.1.0	Initial release with 13-section wizard

Resources

• npm package: https://www.npmjs.com/package/create-markdown-sync
• Template repo: https://github.com/waynesutton/markdown-site
• Docs: https://www.markdown.fast/docs
• Deployment: https://www.markdown.fast/docs-deployment
• WorkOS setup: https://www.markdown.fast/how-to-setup-workos