{"id":41915896,"url":"https://github.com/nperez0111/cache-nx","last_synced_at":"2026-01-25T16:23:10.391Z","repository":{"id":304000140,"uuid":"1017437967","full_name":"nperez0111/cache-nx","owner":"nperez0111","description":"NX 21+ cache server that stores to redis","archived":false,"fork":false,"pushed_at":"2025-12-12T15:28:24.000Z","size":126,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-14T06:50:31.047Z","etag":null,"topics":["cache","monorepo","nx","server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nperez0111.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-10T14:30:11.000Z","updated_at":"2025-12-12T15:28:28.000Z","dependencies_parsed_at":"2025-07-10T21:56:24.479Z","dependency_job_id":null,"html_url":"https://github.com/nperez0111/cache-nx","commit_stats":null,"previous_names":["nperez0111/cache-nx"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nperez0111/cache-nx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nperez0111%2Fcache-nx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nperez0111%2Fcache-nx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nperez0111%2Fcache-nx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nperez0111%2Fcache-nx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nperez0111","download_url":"https://codeload.github.com/nperez0111/cache-nx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nperez0111%2Fcache-nx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28755250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-25T13:59:49.818Z","status":"ssl_error","status_checked_at":"2026-01-25T13:59:33.728Z","response_time":113,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","monorepo","nx","server"],"created_at":"2026-01-25T16:23:08.455Z","updated_at":"2026-01-25T16:23:10.386Z","avatar_url":"https://github.com/nperez0111.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nx Cache Server\n\nA self-hosted Nx cache server built with Bun and Elysia, featuring Redis storage and a web management interface.\n\n## Features\n\n- 🚀 **High Performance**: Built with Bun and Elysia for maximum performance\n- 🔐 **Secure Authentication**: Token-based authentication with read/write permissions\n- 📊 **Web Interface**: Built-in web dashboard to view and manage cache items\n- 🐳 **Docker Ready**: Complete Docker setup with Redis included\n- ⚡ **Redis Backend**: Fast, reliable caching with configurable TTL\n- 🔄 **Full Nx Compatibility**: Implements the complete Nx remote cache API specification\n\n## Quick Start\n\n### Docker Compose (Recommended)\n\n1. Clone this repository:\n\n```bash\ngit clone \u003crepository-url\u003e\ncd nx-cache-server\n```\n\n2. Start the services:\n\n```bash\ndocker-compose up -d\n```\n\n3. The server will be available at:\n   - **API**: `http://localhost:3000`\n   - **Web Interface**: `http://localhost:3000`\n   - **Health Check**: `http://localhost:3000/health`\n\n### Local Development\n\n1. **Prerequisites**:\n   - [Bun](https://bun.sh) installed\n   - Redis server running locally\n\n2. **Install dependencies**:\n\n```bash\nbun install\n```\n\n3. **Configure environment** (copy from `.env.example`):\n\n```bash\ncp .env.example .env\n```\n\n4. **Start the server**:\n\n```bash\nbun dev\n```\n\n## Configuration\n\nConfigure the server using environment variables:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `3000` | Server port |\n| `REDIS_URL` | `redis://localhost:6379` | Redis connection URL |\n| `AUTH_SECRET_KEY` | `nx-cache-server-secret-key` | Secret key for token signing |\n| `READ_ONLY_TOKEN` | `readonly` | Token for read-only access |\n| `READ_WRITE_TOKEN` | `readwrite` | Token for read-write access |\n| `CACHE_TTL` | `604800` | Cache TTL in seconds (7 days) |\n| `MAX_ITEM_SIZE` | `104857600` | Maximum cache item size in bytes (100MB) |\n| `MAX_TOTAL_CACHE_SIZE` | `10737418240` | Maximum total cache size in bytes (10GB). When exceeded, least recently used entries are evicted. |\n\n## Using with Nx\n\n**Requirements**: Nx version 21 or higher\n\n### Environment Variables Configuration\n\nSet the following environment variables in your Nx workspace:\n\n```bash\n# Development\nexport NX_SELF_HOSTED_REMOTE_CACHE_SERVER=\"http://localhost:3000\"\nexport NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=\"your-access-token\"\n\n# Production\nexport NX_SELF_HOSTED_REMOTE_CACHE_SERVER=\"https://your-cache-server.com\"\nexport NX_SELF_HOSTED_REMOTE_CACHE_ACCESS_TOKEN=\"your-production-access-token\"\n```\n\n### Generating Access Tokens\n\nYou can generate custom tokens using the built-in helper function:\n\n```typescript\nimport { generateCustomToken } from './src/lib/auth';\nconst token = generateCustomToken('readwrite', 'user123');\n```\n\nOr manually using the `generate-token` script:\n\n```typescript\nbun run scripts/generate-token.ts readwrite user123\n```\n\n### Testing the cache\n\nRun a cacheable task twice to see the cache in action:\n\n```bash\n# First run - will populate the cache\nnx build my-app\n\n# Second run - will use cached result\nnx build my-app\n```\n\nYou should see output indicating the cache was used on the second run.\n\n## Authentication\n\nThe server supports multiple authentication methods:\n\n### Simple Tokens\n\nUse predefined tokens for quick setup:\n\n- Read-only: Set `READ_ONLY_TOKEN` environment variable\n- Read-write: Set `READ_WRITE_TOKEN` environment variable\n\n### Custom HMAC Tokens\n\nFor enhanced security, generate custom tokens using Bun's crypto API as shown above.\n\n## Web Interface\n\nAccess the web interface at `http://localhost:3000` to:\n\n- View cache statistics (total items, total size)\n- Browse all cached items with metadata\n- Delete individual cache items\n- Purge all caches\n- Monitor cache usage in real-time\n\nThe interface auto-refreshes every 30 seconds and provides a clean, responsive UI built with React and Tailwind CSS.\n\n## Docker\n\n### Using the Official Image\n\nThe server is available as a Docker image at `ghcr.io/nperez0111/cache-nx`:\n\n```bash\ndocker pull ghcr.io/nperez0111/cache-nx\n```\n\n### Docker Compose Example\n\n```yaml\nversion: '3.8'\nservices:\n  nx-cache-server:\n    image: ghcr.io/nperez0111/cache-nx\n    ports:\n      - \"3000:3000\"\n    environment:\n      - PORT=3000\n      - REDIS_URL=redis://valkey:6379\n      - AUTH_SECRET_KEY=${AUTH_SECRET_KEY}\n      - READ_ONLY_TOKEN=${READ_ONLY_TOKEN}\n      - READ_WRITE_TOKEN=${READ_WRITE_TOKEN}\n      - CACHE_TTL=604800\n      - MAX_ITEM_SIZE=104857600\n      - MAX_TOTAL_CACHE_SIZE=10737418240\n    depends_on:\n      valkey:\n        condition: service_healthy\n    restart: unless-stopped\n\n  valkey:\n    image: valkey/valkey:latest\n    volumes:\n      - valkey_data:/data\n    healthcheck:\n      test: [\"CMD\", \"valkey-cli\", \"ping\"]\n      interval: 30s\n      timeout: 10s\n      retries: 3\n    restart: unless-stopped\n\nvolumes:\n  valkey_data:\n```\n\n## Monitoring\n\n### Health Check\n\nThe server provides a health endpoint at `/health`:\n\n```bash\ncurl http://localhost:3000/health\n```\n\nResponse:\n\n```json\n{\n  \"status\": \"ok\",\n  \"timestamp\": \"2024-01-01T00:00:00.000Z\"\n}\n```\n\n### Logs\n\nThe server provides structured logging for:\n\n- Cache hits/misses\n- Authentication attempts\n- Error conditions\n- Redis connection status\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Redis connection failed**\n   - Verify Redis is running and accessible\n   - Check the `REDIS_URL` configuration\n   - Ensure network connectivity\n\n2. **Authentication failures**\n   - Verify tokens match between Nx and server configuration\n   - Check for extra whitespace in token values\n   - Ensure proper Bearer token format\n\n3. **Cache not working**\n   - Verify Nx version is 21 or higher\n   - Check environment variables are set correctly\n   - Test server logs for errors\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\nFor issues and questions:\n\n- Create an issue on GitHub\n- Check the troubleshooting section\n- Review the Nx documentation for cache configuration\n\n---\n\nBuilt with ❤️ using [Bun](https://bun.sh) and [Elysia](https://elysiajs.com)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnperez0111%2Fcache-nx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnperez0111%2Fcache-nx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnperez0111%2Fcache-nx/lists"}