{"id":25235427,"url":"https://github.com/kei-k23/react-express-auth-template","last_synced_at":"2026-04-12T15:44:14.721Z","repository":{"id":274318196,"uuid":"919331315","full_name":"Kei-K23/react-express-auth-template","owner":"Kei-K23","description":"A modern, type-safe authentication system built with React, Express, and TypeScript using a monorepo structure with pnpm workspace","archived":false,"fork":false,"pushed_at":"2025-02-01T04:36:24.000Z","size":4402,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-11T14:43:44.149Z","etag":null,"topics":["authentication","authorization","express","jwt","postgresql","prisma-orm","react","refresh-token","shadcn-ui","tailwindcss","typescript"],"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/Kei-K23.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}},"created_at":"2025-01-20T07:41:54.000Z","updated_at":"2025-02-01T04:36:28.000Z","dependencies_parsed_at":"2025-01-26T15:38:16.935Z","dependency_job_id":null,"html_url":"https://github.com/Kei-K23/react-express-auth-template","commit_stats":null,"previous_names":["kei-k23/react-express-auth-template"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kei-K23%2Freact-express-auth-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kei-K23%2Freact-express-auth-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kei-K23%2Freact-express-auth-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Kei-K23%2Freact-express-auth-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Kei-K23","download_url":"https://codeload.github.com/Kei-K23/react-express-auth-template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247376755,"owners_count":20929282,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["authentication","authorization","express","jwt","postgresql","prisma-orm","react","refresh-token","shadcn-ui","tailwindcss","typescript"],"created_at":"2025-02-11T14:38:27.416Z","updated_at":"2026-04-12T15:44:14.683Z","avatar_url":"https://github.com/Kei-K23.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# React + Express Auth Template\n\nA modern, type-safe authentication system built with React, Express, and TypeScript using a monorepo structure with pnpm workspace.\n\n## 🏗 Architecture\n\n### Monorepo Structure\n\n```\n├── packages/\n│   ├── types/          # Shared TypeScript types and Zod schemas\n|── apps/\n|   ├── backend/        # Express.js backend server\n|   └── frontend/       # React frontend application\n```\n\n### Technology Stack\n\n#### Backend\n\n- **Express.js** - Web framework\n- **Prisma** - Type-safe ORM\n- **PostgreSQL** - Database\n- **JWT** - Authentication tokens\n- **Zod** - Runtime type validation\n- **TypeScript** - Type safety\n\n#### Frontend\n\n- **React** - UI framework\n- **React Router** - Client-side routing\n- **React Query** - Data fetching and caching\n- **Zod** - Form validation\n- **ShadcnUI** - UI components\n- **TailwindCSS** - Styling\n- **Axios** - HTTP client\n\n#### Shared\n\n- **TypeScript** - Type definitions\n- **Zod** - Schema validation\n- **PNPM** - Package management\n\n## 🔄 Authentication Flow\n\n1. **Registration**\n\n   ```\n   Client → POST /api/auth/register → Validate Input → Hash Password → Create User → Generate Tokens → Return User \u0026 Tokens\n   ```\n\n2. **Login**\n\n   ```\n   Client → POST /api/auth/login → Validate Credentials → Generate Tokens → Return User \u0026 Tokens\n   ```\n\n3. **Token Refresh**\n\n   ```\n   Client → Access Token Expires → Use Refresh Token → Get New Access Token → Continue Using API\n   ```\n\n4. **Authentication**\n\n   ```\n   Client → Include Access Token in Header → Middleware Validates Token → Allow/Deny Access\n   ```\n\n5. **Logout**\n   ```\n   Client → POST /api/auth/logout → Revoke Refresh Token → Clear Cookies\n   ```\n\n## 🔒 Token System\n\n### Access Token\n\n- Short-lived (15 minutes)\n- Used for API authentication\n- JWT format\n- Stored in Client Browser Cookie\n- Automatically refreshed when expired\n\n### Refresh Token\n\n- Long-lived (30 days)\n- Used to obtain new access tokens\n- Secure random token\n- Stored in database\n- Can be revoked for security\n- One refresh token per login session\n\n## 🚀 Getting Started\n\n### Prerequisites\n\n- Node.js 16+\n- PNPM\n- PostgreSQL database\n\n### Installation\n\n1. Clone the repository:\n\n   ```bash\n   git clone react-express-auth-template\n   cd react-express-auth-template\n   ```\n\n2. Install dependencies:\n\n   ```bash\n   pnpm install\n   ```\n\n3. Set up environment variables:\n\n   **Backend** (`packages/backend/.env`):\n\n   ```\n   BACKEND_APP_PORT=3001\n   BACKEND_APP_JWT_KEY=\"your_secret_key\"\n   DATABASE_URL=\"postgresql://\u003cusername\u003e:\u003cpassword\u003e@localhost:5432/\u003cyour_db_name\u003e?schema=public\"\n   VITE_BACKEND_APP_API_URL=\"http://localhost:3001\"\n   ```\n\n   **Frontend** (`packages/frontend/.env`):\n\n   ```\n   BACKEND_APP_PORT=3001\n   BACKEND_APP_JWT_KEY=\"your_secret_key\"\n   DATABASE_URL=\"postgresql://\u003cusername\u003e:\u003cpassword\u003e@localhost:5432/\u003cyour_db_name\u003e?schema=public\"\n   VITE_BACKEND_APP_API_URL=\"http://localhost:3001\"\n   ```\n\n4. Initialize the database:\n\n   ```bash\n   cd packages/backend\n   pnpm prisma db push\n   ```\n\n5. Start development servers:\n   ```bash\n   # Root directory\n   pnpm dev\n   ```\n\n## 🔌 API Endpoints\n\n### Authentication Routes\n\n#### POST /api/auth/register\n\n```typescript\n// Request\n{\n  email: string; // Valid email\n  password: string; // Min 8 characters\n  username: string; // Min 2 characters\n}\n\n// Response\n{\n  user: {\n    id: string;\n    email: string;\n    username: string;\n    createdAt: string;\n    updatedAt: string;\n  }\n  accessToken: string;\n  refreshToken: string;\n}\n```\n\n#### POST /api/auth/login\n\n```typescript\n// Request\n{\n  email: string;\n  password: string;\n}\n\n// Response\n{\n  user: {\n    id: string;\n    email: string;\n    username: string;\n    createdAt: string;\n    updatedAt: string;\n  }\n  accessToken: string;\n  refreshToken: string;\n}\n```\n\n#### POST /api/auth/refresh\n\n```typescript\n// Request\n{\n  refreshToken: string;\n}\n\n// Response\n{\n  accessToken: string;\n}\n```\n\n#### POST /api/auth/logout\n\n```typescript\n// Request\n{\n  refreshToken: string;\n}\n\n// Response\n{\n  message: string;\n}\n```\n\n#### GET /api/auth/me\n\n```typescript\n// Headers\nAuthorization: Bearer\u003caccessToken\u003e;\n\n// Response\n{\n  id: string;\n  email: string;\n  username: string;\n  createdAt: string;\n  updatedAt: string;\n}\n```\n\n#### PATCH /api/auth/updateMe\n\n```typescript\n// Headers\nAuthorization: Bearer\u003caccessToken\u003e;\n\n// Request\n{\n  email: string; // Valid email\n  username: string; // Min 2 characters\n}\n\n// Response\n{\n  id: string;\n  email: string;\n  username: string;\n  createdAt: string;\n  updatedAt: string;\n}\n```\n\n#### DELETE /api/auth/updateMe\n\n```typescript\n// Headers\nAuthorization: Bearer\u003caccessToken\u003e;\n\n// Response\n{\n  message: string;\n}\n```\n\n## 🔒 Security Features\n\n1. **Token Security**\n\n   - Short-lived access tokens (15 minutes)\n   - Secure refresh token rotation\n   - Refresh token revocation\n   - Token blacklisting support\n\n2. **Password Security**\n\n   - Passwords are hashed using bcrypt\n   - Minimum password length enforcement\n   - Password never returned in API responses\n\n3. **Input Validation**\n\n   - Zod schema validation\n   - Type-safe request handling\n   - Sanitized database queries with Prisma\n\n4. **Protected Routes**\n   - Frontend route protection\n   - Backend middleware authentication\n   - Automatic token refresh\n   - Secure token storage\n\n## 🔄 Token Refresh Flow\n\n1. **Access Token Expires**\n\n   - Frontend detects 401 response\n   - Interceptor catches the error\n\n2. **Automatic Refresh**\n\n   - Uses refresh token to get new access token\n   - Handles concurrent requests\n   - Updates stored tokens\n\n3. **Error Handling**\n   - Invalid refresh token handling\n   - Automatic logout on refresh failure\n   - Race condition prevention\n\n## 🛠 Development Guidelines\n\n1. **Code Style**\n\n   - Use TypeScript for all new code\n   - Follow ESLint configuration\n   - Use Prettier for formatting\n\n2. **Authentication**\n\n   - Always use the `authenticate` middleware\n   - Implement proper token handling\n   - Follow security best practices\n\n3. **API Development**\n\n   - Use Zod for validation\n   - Implement proper error responses\n   - Document new endpoints\n\n4. **Frontend Development**\n   - Use ShadcnUI components\n   - Handle loading states\n   - Proper error handling\n\n## 🔍 Error Handling\n\n1. **Backend Errors**\n\n   - Token validation errors\n   - Authentication errors\n   - Database errors\n   - Validation errors\n\n2. **Frontend Errors**\n   - Token refresh errors\n   - API request failures\n   - Form validation\n   - Network issues\n\n## 📦 Available Scripts\n\n```bash\n# Install dependencies\npnpm install\n\n# Link .env file across apps\npnpm run postinstall\n\n# Start development servers\npnpm run dev\n\n# Build for production\npnpm run build\n\n# Lint code\npnpm run lint\n```\n\n## Todo\n\n- [ ] Add OAuth authentication (e.g Google, GitHub without using any third-part library)\n- [ ] Add Password reset via Email\n- [ ] Add more secure and advanced client session management\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Open a pull request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkei-k23%2Freact-express-auth-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkei-k23%2Freact-express-auth-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkei-k23%2Freact-express-auth-template/lists"}