ergosteur/instaarchive-viewer
1
0
Fork 0
mirror of https://github.com/ergosteur/instaarchive-viewer.git synced 2026-07-04 11:07:15 -04:00
Code Issues Packages Projects Releases Wiki Activity

docs: update README and GEMINI.md, remove AI Studio boilerplate and .env.example

Browse Source
This commit is contained in:
ergosteur
2026-03-07 00:36:46 -05:00
parent f685eaebd7
commit 41e7c5e206
3 changed files with 49 additions and 53 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
.env.example
View File

@@ -1,9 +0,0 @@
# GEMINI_API_KEY: Required for Gemini AI API calls.
# AI Studio automatically injects this at runtime from user secrets.
# Users configure this via the Secrets panel in the AI Studio UI.
GEMINI_API_KEY="MY_GEMINI_API_KEY"
# APP_URL: The URL where this applet is hosted.
# AI Studio automatically injects this at runtime with the Cloud Run service URL.
# Used for self-referential links, OAuth callbacks, and API endpoints.
APP_URL="MY_APP_URL"

46
GEMINI.md
View File

@@ -1,17 +1,17 @@
# GEMINI.md
# InstaArchive Technical Documentation
## Project Overview
**InstaArchive** is a high-performance, React-based Progressive Web App (PWA) designed to browse and explore archived Instagram data with a native-feeling interface. It allows users to load their local Instagram archive directories (either official Instagram exports or Instaloader format) and browse posts, reels, and stories in a modern, responsive grid view.
**InstaArchive** is a high-performance, React-based Progressive Web App (PWA) designed to browse and explore archived Instagram data with a native-feeling interface. It allows users to load local archive directories (either official Instagram exports or Instaloader format) and browse posts, reels, and stories.
### Key Features
### Key Technical Features
- **Local Archive Loading:** Uses the `webkitdirectory` API to scan and process local files securely on the client-side.
- **Support for Multiple Formats:** Recognizes official Instagram export structures and Instaloader regex-based naming conventions.
- **Dynamic Media Grid:** Customizable grid layouts (1:1 and 3:4 aspect ratios) with adjustable offsets ("bumps") for aesthetic alignment.
- **Story Viewer:** Native-like story experience with progress bars, automated playback, and touch/click navigation.
- **Post Detail Modal:** Comprehensive view for posts with media carousels, captions, and seamless navigation between posts.
- **Video Support:** Automatic video thumbnail generation and playback.
- **PWA Ready:** Built with `vite-plugin-pwa` for offline capabilities and a standalone application experience.
- **Compressed Metadata**: Support for `.json.xz` file decompression using `xz-decompress` (WASM-powered).
- **Dynamic Media Grid**: Customizable grid layouts (1:1 and 3:4 aspect ratios) with adjustable offsets ("bumps") for aesthetic alignment.
- **Story Viewer**: Native-like story experience with segmented progress bars, automated playback, audio controls, and chronological sorting.
- **Auto-Unmute**: Videos default to unmuted when opened in full view for a better user experience.
- **PWA Ready**: Built with `vite-plugin-pwa` for offline capabilities and a standalone application experience.
### Main Technologies
- **Frontend:** React 19, Vite, TypeScript
@@ -19,39 +19,21 @@
- **Icons:** Lucide React
- **Animations:** Framer Motion (`motion/react`)
- **Utility:** Date-fns, clsx, tailwind-merge
- **PWA:** vite-plugin-pwa
- **Decompression**: xz-decompress (WASM)
*Note: While `better-sqlite3`, `express`, and `@google/genai` are listed in `package.json`, the current core application logic is entirely frontend-driven.*
## Building and Running
### Prerequisites
- Node.js (Latest LTS recommended)
- npm or yarn
### Commands
## Commands
- `npm install`: Install project dependencies.
- `npm run dev`: Start the local development server on port 3000.
- `npm run build`: Generate the production-ready build in the `dist` folder.
- `npm run preview`: Locally preview the production build.
- `npm run lint`: Execute TypeScript type-checking (`tsc --noEmit`).
- `npm run clean`: Remove the `dist` directory.
### Environment Variables
- `GEMINI_API_KEY`: Required for AI-integrated features (though currently unutilized in core logic).
- `DISABLE_HMR`: If set to `true` (standard in AI Studio environments), Hot Module Replacement is disabled to prevent flickering during agent-driven edits.
## Development Conventions
- **Component Architecture:** Functional components with modern hooks. All main application logic currently resides in `src/App.tsx`.
- **Styling Strategy:** Utility-first CSS using Tailwind CSS v4. Styles are largely co-located with components.
- **Type Safety:** Strict TypeScript usage for all components and utility functions.
- **Iconography:** Consistent use of `lucide-react` for all UI icons.
- **Animations:** Smooth transitions and gestures powered by `motion/react`.
- **File Handling:** Privacy-focused client-side scanning of archive directories using browser-native APIs.
- **Component Architecture:** Functional components with modern hooks.
- **State Management**: React `useState`, `useMemo`, and `useCallback` for optimized performance during large archive scans.
- **File Handling:** Privacy-focused client-side scanning of archive directories.
- **Project Structure:**
- `src/App.tsx`: Main entry point and core application logic.
- `src/App.tsx`: Main entry point containing application logic and UI components.
- `src/main.tsx`: React DOM mounting.
- `src/index.css`: Global styles and Tailwind imports.
- `vite.config.ts`: Project build and PWA configuration.
- `metadata.json`: Project description for external integration tools.

47
README.md
View File

@@ -1,20 +1,43 @@
<div align="center">
<img width="1200" height="475" alt="GHBanner" src="https://github.com/user-attachments/assets/0aa67016-6eaf-458a-adb2-6e31a0763ed6" />
</div>
# InstaArchive Viewer
# Run and deploy your AI Studio app
A high-performance React PWA for browsing archived Instagram data with a native-feeling interface. Supports both official Instagram exports and Instaloader archives.
This contains everything you need to run your app locally.
## Features
View your app in AI Studio: https://ai.studio/apps/29dc2807-7763-419f-9f2f-ac644e1bf4a1
- **Local Privacy**: All processing is done client-side using browser APIs. Your data never leaves your computer.
- **Multiple Formats**: Supports official Instagram JSON exports and Instaloader regex-based naming conventions.
- **Metadata Support**: Robust parsing of `.json` and `.json.xz` files for captions, timestamps, and story metadata.
- **Story Viewer**: Native-like story experience with segmented progress bars, auto-playback, and audio controls.
- **Media Grid**: Customizable 1:1 or 3:4 grid views with adjustable offsets for aesthetic alignment.
- **Auto-Deduplication**: Intelligently prefers video files over thumbnail images for the same post.
## Run Locally
**Prerequisites:** Node.js
**Prerequisites:** Node.js (LTS recommended)
1. **Install dependencies:**
```bash
npm install
```
1. Install dependencies:
`npm install`
2. Set the `GEMINI_API_KEY` in [.env.local](.env.local) to your Gemini API key
3. Run the app:
`npm run dev`
2. **Start the development server:**
```bash
npm run dev
```
3. **Open in browser:**
Navigate to `http://localhost:3000` and select your Instagram archive directory.
## Building for Production
To generate a production-ready build in the `dist` folder:
```bash
npm run build
```
To preview the build:
```bash
npm run preview
```