Smart README Generator is an AI-powered tool to help developers create professional, interactive, and visually appealing README.md files for their GitHub repositories.
It fetches GitHub user data and project repositories, then uses AI to suggest content for sections like Bio, Skills, Projects, and Badges, allowing users to generate a complete README with minimal effort.
This project is open-source, supports dynamic templates, dark/light themes, and allows real-time preview and AI suggestions.
The goal is to make contributing to GitHub easier, saving developers time while ensuring READMEs are consistent, attractive, and informative.
- Fetch GitHub profile and repositories automatically
- Generate full README using AI (OpenAI GPT integration)
- AI-assisted suggestions per section (Bio, Skills, Projects)
- Multiple pre-defined and customizable templates
- Live Markdown preview
- Copy to clipboard and download as
.md - Dark/Light theme support with auto-detection and toggle
- Undo/Redo editing functionality
- Loading and error states for smooth UX
- Rate-limit handling for GitHub and AI APIs
- Mobile-friendly, responsive UI
Frontend:
- Next.js (CSR-focused for dynamic interaction)
- React.js
- Tailwind CSS
- react-markdown for live preview
Backend:
- Node.js / Express (MVP server for README generation)
- GitHub API integration
- AI integration (OpenAI GPT or similar)
- Caching for API responses
DevOps & Quality:
- GitHub Actions (CI/CD)
- Husky & lint-staged (pre-commit hooks)
- ESLint & Prettier (code quality & formatting)
The following folder structure is an example of how the Smart README Generator project can be organized.
It separates the frontend, backend, templates, and documentation to make the project easy to navigate, maintain, and contribute to.
- backend/ – Contains the Node.js/Express server, API routes, services, and backend tests.
- frontend/ – Contains the Next.js frontend with Redux state management, reusable components, templates, and styles.
- templates/ – Stores Markdown README templates that users can select when generating a README.
- docs/ – Project documentation and additional guides.
- scripts/ – Utility scripts for build, deployment, or other automation tasks.
⚠️ Note: This folder structure is an example. You can adjust it depending on your needs and scale of the project.
smart-readme-generator/
backend/
├── src/
│ ├── config/ # Environment & DB setup
│ │ └── env.ts
│ ├── controllers/ # Request handling (req, res)
│ │ ├── githubController.ts
│ │ └── aiController.ts
│ ├── services/ # Business logic & API calls (Octokit, OpenAI)
│ │ ├── githubService.ts
│ │ └── aiService.ts
│ ├── routes/ # Route definitions
│ │ └── index.ts
│ ├── utils/ # Pure helper functions
│ │ ├── logger.ts
│ │ └── validator.ts
│ ├── app.ts # Express setup & Middleware
│ └── index.ts # Entry point (Server listener)
├── tests/ # Unit and Integration tests
├── .env
├── .env.example
├── package.json
└── tsconfig.json
│
│
├─ frontend/ # Next.js frontend (CSR)
│ ├─ app/
│ │ ├─ components/ # Reusable UI components
│ │ │ ├─ Button.tsx
│ │ │ ├─ Editor.tsx
│ │ │ ├─ TemplateCard.tsx
│ │ ├─ pages/ # Next.js pages
│ │ │ ├─ index.tsx
│ │ │ ├─ _app.tsx
│ │ ├─ hooks/ # Custom React hooks
│ │ │ ├─ useAI.ts
│ │ │ ├─ useGitHub.ts
│ │ ├─ services/ # API clients
│ │ │ ├─ githubClient.ts
│ │ │ ├─ aiClient.ts
│ │ ├─ store/ # Redux store & slices
│ │ │ ├─ index.ts # Configure store
│ │ │ ├─ themeSlice.ts
│ │ │ ├─ editorSlice.ts
│ │ │ ├─ templateSlice.ts
│ │ ├─ styles/ # Global CSS
│ │ │ └─ globals.css
│ │ ├─ types/ # TypeScript types
│ │ └─ utils/ # Helpers
│ ├─ public/ # Static assets (icons, images)
│ ├─ templates/ # README templates
│ │ ├─ template1.md
│ │ ├─ template2.md
│ │ └─ ...
│ ├─ tests/ # Frontend unit/integration tests
│ ├─ package.json
│ └─ tailwind.config.js # Tailwind config
├─ docs/ # Project documentation
├─ scripts/ # Build/deployment/util scripts
├─ .gitignore
├─ package.json
├─ LICENSE
├─ CONTRIBUTING.md
└─ README.md
git clone https://github.com/Open-Core-Lab/smart-readme-generator.git
cd smart-readme-generator/frontend
npm install
npm run devcd smart-readme-generator/backend
npm install
cp .env.example .env
# Add GitHub API token and OpenAI API key
npm run devThis project is licensed under the MIT License - see the LICENSE file for details. © Madhusha Prasad