Skip to content

UPSTREAM_SYNC_COMMIT_GUIDE.md

Latest commit

 

History

History
134 lines (95 loc) · 4.62 KB

UPSTREAM_SYNC_COMMIT_GUIDE.md

File metadata and controls

134 lines (95 loc) · 4.62 KB

Upstream Sync Commit Guide

This document explains what gets committed to git when syncing from upstream pie-elements.

Audience: This guide is for maintainers who sync from upstream. Regular developers don't need to run upstream:sync - synced packages are already committed to git, so just git pull to get updates.

What Gets Committed ✅

packages/elements-react/*/ and packages/lib-react/*/

For each element/library package, we commit:

  • src/ - Source files (transformed from upstream)
    • .js → .ts conversions
    • .jsx → .tsx conversions
    • Import path rewrites (lodash → lodash-es, etc.)
  • package.json - Generated ESM-compatible package.json
  • vite.config.ts - Generated build configuration
  • vite.config.iife.ts - IIFE build config (if needed)
  • tsconfig.json - TypeScript configuration
  • docs/demo/ - Demo configuration files (config.mjs, session.mjs)

What's Excluded (Already in .gitignore)

  • dist/ - Build outputs (gitignored globally)
  • node_modules/ - Dependencies (gitignored globally)
  • .turbo/ - Turbo cache (gitignored globally)

What Gets Gitignored ❌

Demo App Generated Files

These are regenerated automatically on every upstream:sync and should NOT be committed:

  • apps/element-demo/src/lib/element-imports.ts

    • Maps element names to import paths
    • Uses absolute /@fs/ paths specific to your machine
    • Regenerated by predev script

  • apps/element-demo/src/lib/elements/registry.ts

    • Element metadata registry
    • Contains timestamp that changes on every sync
    • Regenerated from scanning packages/elements-react/

  • apps/element-demo/src/lib/data/sample-configs/react/

    • Sample config/session JSON files
    • Copied from each element's docs/demo/ directory
    • Redundant since source configs are already committed in element packages

Why Not Commit Demo App Generated Files?

  1. Timestamps cause spurious diffs - registry.ts has a generation timestamp
  2. Redundant data - Sample configs are duplicated from element packages
  3. Machine-specific paths - element-imports.ts uses absolute file paths
  4. Regenerated automatically - These files are rebuilt on demand

When Are Demo App Files Regenerated?

Demo app generated files are automatically created when needed:

During upstream:sync:

bun cli upstream:sync
  • Generates registry.ts from scanning packages/elements-react/
  • Copies configs from packages/elements-react/*/docs/demo/ → sample-configs/react/

When starting the demo app:

cd apps/element-demo
bun run dev  # Runs "predev" script first
  • The predev script runs bun run generate-imports
  • This generates element-imports.ts with absolute /@fs/ paths for Vite
  • Also regenerates registry.ts and sample-configs/ if needed

Result: New developers don't need these files in git. Running the demo app generates them automatically from the committed element packages.

Verification Before Committing

Before committing an upstream sync, verify you're not committing build artifacts:

# After running upstream:sync, check what changed
git status

# Should see:
# - packages/elements-react/*/src/
# - packages/elements-react/*/package.json
# - packages/lib-react/*/src/
# - packages/lib-react/*/package.json

# Should NOT see:
# - packages/elements-react/*/dist/
# - packages/elements-react/*/node_modules/
# - apps/element-demo/src/lib/element-imports.ts
# - apps/element-demo/src/lib/elements/registry.ts
# - apps/element-demo/src/lib/data/sample-configs/

# Add only the synced packages
git add packages/elements-react packages/lib-react

# Verify what will be committed
git diff --cached --stat

# Commit
git commit -m "sync: update from upstream pie-elements"

Why Commit Generated Package.json and Vite Configs?

These files are deterministic (no timestamps) and serve important purposes:

  1. Bootstrap requirement - Workspace resolution needs package.json to exist
  2. Deterministic generation - Same upstream produces same output
  3. Review-friendly - Can see what changed in dependencies/exports
  4. Self-documenting - Shows the ESM transformation applied

File Size Impact

Committing synced packages adds approximately:

  • ~1000 source files (.ts, .tsx)
  • ~28 package.json files (one per element)
  • ~28 vite.config.ts files
  • Total: ~5-10 MB (source only, excluding build artifacts)

This is acceptable since:

  • Build artifacts (dist/, node_modules/) are gitignored
  • Files are actual source code, not generated binaries
  • Solves the bootstrap chicken-and-egg problem for new developers