How equalma/gitpkg works
Main High-Level Components
a. Monorepo (single codebase)
• packages/core
• packages/edge-polyfill
• api (serverless functions)
• website (Docusaurus React site)
b. Deployment Platform
• Vercel (serverless / edge runtime)
c. External Services
• GitHub (source repos, raw file/tarball URLs)
• npm / yarn client (consumes packaged subfolders)
Relationships & Data Flows
• Developer / CI (GitHub Actions, Husky hooks) pushes code → Vercel deploys “api/” functions and “website/”.
• End user (npm client) runs npm install gitpkg:owner/repo/path → resolves to GitPkg API endpoint on Vercel.
• API function (e.g. pkg.ts) invokes core logic in packages/core:
– calls GitHub APIs or raw URLs to fetch the entire repo tarball
– uses parse-url-query to interpret path, commit-ish, custom scripts plugin
– uses tar utilities to extract the subfolder and re-package it
– streams the resulting tarball back to the npm client
– edge-polyfill ensures Node-style streams work in edge runtime
• Website UI (React/Docusaurus) fetches live demos / ping endpoints from the same API to demonstrate usage.
Architectural Patterns & Key Principles
• Monorepo with shared TypeScript configurations (tsconfig.base.json)
• Code reuse: api/ imports packages/core and edge-polyfill
• Serverless / Edge functions: each file in api/ folder = separate endpoint
• Static site generation (SSG) + client-side React for docs/demo
• Polyfill layer for Web Streams API on edge runtime