This project is a high-performance, static-first replica of the ESM.sh package browser. It allows users to search NPM packages, view details, and generate ES Module import URLs.

The architecture is designed to be serverless and static, meaning it can be hosted on any static file server or CDN without a backend runtime (like Node.js or Python).

• Pure Static Frontend: Built with React and TypeScript.
• Hash Routing: Uses HashRouter for compatibility with all static hosts (no server-side redirects required).
• Import Maps: Loads major dependencies (React, Router, Recharts) via CDN to keep the bundle size tiny.
• Local Caching: Implements localStorage caching to minimize API calls to NPM registries.
• Responsive Design: Tailwind CSS styling for all device sizes.

---

To run the project locally on your machine:

1. Install Dependencies

   npm install
   

2. Start Development Server

   npm run dev
   

   Open your browser to http://localhost:5173 (or the port shown in your terminal).

---

Since this app removes backend dependencies (like the Gemini API), it can be deployed to any static hosting provider.

Run the build command to generate the static files:

npm run build

This will create a dist (or build) folder containing:

• index.html
• assets/ (JavaScript and CSS files)

1. Install Vercel CLI: npm i -g vercel
2. Run vercel in the project root.
3. Accept default settings.
4. Done! Your site is live globally.

1. Push your code to a GitHub repository.
2. Go to Settings > Pages.
3. Source: GitHub Actions or Deploy from branch.
4. If using a custom build workflow, ensure the dist folder content is uploaded to the gh-pages branch.
   • Note: Since we use HashRouter, you do not need a 404.html hack.

1. Drag and drop the dist folder into the Netlify Dashboard.
2. Or connect your GitHub repository and set the build command to npm run build and directory to dist.

Upload the contents of the dist folder to your web root (e.g., /var/www/html).

Nginx Configuration: Because we use Hash Routing (/#/package/react), no special try_files configuration is needed! The default static file serving is sufficient.

server {
    listen 80;
    server_name example.com;
    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

---

This application uses HashRouter (e.g., domain.com/#/package/react) instead of BrowserRouter (domain.com/package/react).

• Why? This ensures that if a user refreshes the page on a deep link while hosted on a static server (like GitHub Pages or S3), they won't get a 404 error. The server always serves index.html, and the client-side router handles the rest via the URL hash.

The application fetches data directly from the client browser using registry.npmmirror.com.

• This registry provides better CORS (Cross-Origin Resource Sharing) support than the official NPM registry, allowing the app to work purely in the browser without a proxy server.

To improve performance and reduce API limits during static hosting:

• Package details are cached in the browser's localStorage for 1 hour.
• Search results are fetched live to ensure freshness.