KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#typescript #ai-agents #developer-tools #claude-code #codex #cli #agent-skills #ai #dsh-plugin #mcp #windows #agent

MyLists

★ 109 Open GitHub ↗

MyLists: organize series, anime, movies, games, books and manga, all in one place.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MyLists

[![Bun](https://img.shields.io/badge/Bun-v1.3.2-white?style=flat&logo=bun&logoColor=%23fbf0df)](https://bun.sh)
[![React](https://img.shields.io/badge/React-19.2-%2361DAFB?style=flat&logo=react&logoColor=black)](https://react.dev)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-%233178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![TanStack](https://img.shields.io/badge/TanStack-Start-%2306B6D4?style=flat&logo=tanstack&logoColor=white)](https://tanstack.com/)
[![Drizzle](https://img.shields.io/badge/Drizzle-ORM-%23C5F74F?style=flat&logoColor=black)](https://orm.drizzle.team/)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4.1-%2338BDF8?style=flat&logo=tailwind-css&logoColor=white)](https://tailwindcss.com/)

**The all-in-one media tracking platform.**

MyLists is a comprehensive, type-safe web-app designed to help you organize and track your movies, TV series, anime, manga, books, and video games in one unified interface.

### Key Features

- **Multi-Media lists**: Dedicated lists for Movies, Series, Anime, Manga, Books, and Games.
- **Upcoming Media**: Get notified when new Media are released.
- **Advanced Analytics**: Visualize your habits with detailed statistics, trends, and platform-wide insights.
- **Modern Full-Stack Architecture**: Built with TanStack Start and end-to-end type-safety.
- **Daily Moviedle**: A daily guessing game to test your movie knowledge.
- **Achievements System**: Earn unique badges and track your progress as you consume more media.
- **Secure Authentication**: Robust user management powered by Better-Auth.

### Quick Start

Ensure you have [Bun](https://bun.sh) installed on your machine.

1. **Clone the repo**
   ```bash
   git clone https://github.com/crossoufire/MyLists.git
   cd MyLists
   ```

2. **Install deps**
   ```bash
   bun install
   ```

3. **Configure the env file**

Create a `.env` file in the root directory and set the three required security values:

```bash
   cp .env.example .env
   openssl rand -hex 32
   ```

Run the OpenSSL command twice and use the generated values for `ADMIN_TOKEN_SECRET` and
   `BETTER_AUTH_SECRET`, then choose an `ADMIN_PASSWORD` of at least 8 chars. All other values have defaults or enable optional features.

4. **Initialize Database**
   Initialize a new SQLite database in the `instance` directory.

```bash
   bun run new:db
   ```

5. **Create a new user**
   To create a new user without email verification, OAuth2 setup, and with different roles (user, manager, admin), you can use the CLI:

```bash
   bun run cli -- create-user \
     --email admin@example.com \
     --password "change-me-strong-password" \
     --username admin \
     --role admin
   ```

6. **Run the Dev Server**

```bash
   bun run dev
   ```

### Docker Deployment

Docker deployment is documented in [docs/docker-deployment.md](./docs/docker-deployment.md).

The Docker Compose setup builds the app image and starts Redis. It mounts persistent storage for SQLite, images, and Redis data. Provide cron/maintenance scheduling and public
HTTPS from your deployment platform when needed. PostHog is optional and disabled when its public key is empty.

---

### Environment Variables

Below is an explanation for each key found in `.env.example`:

| Variable                                    | Description                                                 | Required | Default                        |
|---------------------------------------------|-------------------------------------------------------------|----------|--------------------------------|
| **Main Configuration**                      |                                                             |          |                                |
| `DATABASE_URL`                              | SQLite database path                                        | ❌       | `./instance/site.db`           |
| `VITE_BASE_URL`                             | Base URL used by the frontend                               | ❌       | `http://localhost:3000`        |
| `VITE_CONTACT_MAIL`                         | Email used to be contacted by users                         | ❌       |                                |
| **File Management**                         |                                                             |          |                                |
| `UPLOADS_DIR_NAME`                          | Folder name where uploaded files are stored                 | ❌       | `static`                       |
| `BASE_UPLOADS_LOCATION`                     | Path to the uploads dir (relative or absolute)              | ❌       | `./public/static/`             |
| **Admin Access**                            |                                                             |          |                                |
| `ADMIN_PASSWORD`                            | Admin dashboard privilege-escalation password               | ✅       |                                |
| `ADMIN_TOKEN_SECRET`                        | Secret key for admin access token signing                   | ✅       |                                |
| `ADMIN_TTL_COOKIE_MIN`                      | Lifespan of the admin session cookie (in minutes)           | ❌       | `10`                           |
| **Admin Mail Service**                      |                                                             |          |                                |
| `ADMIN_MAIL_USERNAME`                       | Gmail address used to send application emails               | ❌       |                                |
| `ADMIN_MAIL_PASSWORD`                       | Gmail password or app password                              | ❌       |                                |
| **Cache / Redis**                           |                                                             |          |                                |
| `CACHE_TTL_MIN`                             | Cache duration (in minutes)                                 | ❌       | `5`                            |
| `REDIS_ENABLED`                             | Enables Redis-backed cache, rate limits, and API monitoring | ❌       | `false`                        |
| `REDIS_URL`                                 | Redis connection string, required only if Redis is enabled  | ❌       | `redis://localhost:6379`       |
| **Authentication**                          |                                                             |          |                                |
| `BETTER_AUTH_SECRET`                        | Secret used by Better Auth for encryption                   | ✅       |                                |
| **OAuth2 Providers**                        |                                                             |          |                                |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | GitHub OAuth2 credentials                                   | ❌       |                                |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | Google OAuth2 credentials                                   | ❌       |                                |
| **API Keys**                                |                                                             |          |                                |
| `THEMOVIEDB_API_KEY`                        | Enables movie, series, and anime external data through TMDB | ❌       |                                |
| `GOOGLE_BOOKS_API_KEY`                      | API key for Google Books                                    | ❌       |                                |
| `MAL_CLIENT_ID`                             | Enables manga data and anime genres through MyAnimeList     | ❌       |                                |
| `IGDB_CLIENT_ID` / `IGDB_CLIENT_SECRET`     | Enables game external data through IGDB                     | ❌       |                                |
| **LLM Integration (Optional)**              |                                                             |          |                                |
| `LLM_MODEL_ID`                              | Model ID (OpenRouter) used to generate book genres          | ❌       | `google/gemini-2.5-flash-lite` |
| `LLM_BASE_URL`                              | Base URL for the chosen LLM API                             | ❌       | `https://openrouter.ai/api/v1` |
| `LLM_API_KEY`                               | API key token for the LLM provider                          | ❌       |                                |

---

### Redis Setup

Redis caching is optional.

- To run without Redis, set:
  ```bash
  REDIS_ENABLED=false
  ```
- To use Redis, ensure Redis is available and configured:
  ```bash
  REDIS_ENABLED=true
  REDIS_URL=redis://redis:6379
  ```

- Redis is used for shared caching, shared rate limiting, and API monitoring rollups.
- Without Redis, the app falls back to in-memory cache/rate limiting.
- The admin API monitoring page will not collect outbound API rollups without Redis.

---

### Optional Feature Availability

Missing optional configuration does not prevent MyLists from starting. Login and registration only show configured authentication methods, while unavailable media providers return
a clear error when used.

- Without admin mail credentials, email registration, password reset, email changes, and mail-dependent maintenance are disabled. Email login still works for verified accounts
  created with the `create-user` CLI.
- GitHub and Google OAuth are enabled independently when their complete client ID/secret pair is present.
- Without TMDB, movie, series, and anime external search/details are unavailable. Without IGDB, game external search/details are unavailable.
- Without `MAL_CLIENT_ID`, manga external search/details are unavailable and anime uses TMDB genres without MyAnimeList enrichment. Register an API client at
  [MyAnimeList API Configuration](https://myanimelist.net/apiconfig).
- Google Books remains available without credentials. `GOOGLE_BOOKS_API_KEY` is optional.
- Without `LLM_API_KEY`, book genre enrichment is skipped with a task warning.

For every optional credential pair, either set both values or leave both blank. A partial pair is treated as a configuration error so typos are caught early.

---

### LLM Integration (Optional)

The LLM is **exclusively used to generate genre data for books** since Google Books does not provide genre metadata. You can choose how this background task runs:

1. **Manually**, by executing it with the CLI
2. **Automatically**, using a scheduled cron job

When `LLM_API_KEY` is absent, direct and scheduled enrichment runs are skipped with a log.

---

### Contributing

Contributions are welcome!  
If you’d like to improve MyLists, fork the repo, create a feature branch, and open a pull request.

---

**Built with ❤️ using Bun, Drizzle, Better-Auth, React, TypeScript, and TanStack.**

MyLists

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README