CLI tool that scans JavaScript, TypeScript, Python, and PHP projects and automatically generates clean README.md files with installation, usage, scripts, environment variables, and publishing checklist.
- Multi-Language Support — JavaScript, TypeScript, Python, and PHP projects
- Smart Project Detection — Automatically detects project types (Node.js, React, Vue, Next.js, Vite, Express, TypeScript, CLI packages, Python, Django, Flask)
- Package Manager Detection — npm, pnpm, yarn, bun for JS/TS; pip, Poetry, Pipenv for Python; Composer for PHP
- Package.json Analysis — Extracts metadata, scripts, dependencies, exports, and repository info
- Auto-Generated Documentation — Creates professional README sections with proper formatting
- Environment Variables — Parses
.env.exampleand includes variable tables - NPM Scripts Table — Generates markdown tables with human-readable script descriptions
- Python Dependencies — Parses requirements.txt and includes dependency tables
- Safe by Default — Won't overwrite existing files without
--forceflag - CLI & Library Support — Handles both CLI packages and regular npm libraries
- Project Structure — Optional file tree with
--include-tree - Publishing Checklist — Built-in checklist for npm package releases
npm install -g readme-autoscannpx readme-autoscangit clone https://github.com/JomsCode21/README-auto-scan.git
cd README-auto-scan
npm install
npm run buildGenerate a README.md in the current directory:
readme-autoscanPreview the output without writing a file:
readme-autoscan --dry-runWrite to a custom location:
readme-autoscan --output docs/README.mdOverwrite an existing README.md:
readme-autoscan --forceInclude the project file tree:
readme-autoscan --include-treeSkip the publishing checklist:
readme-autoscan --no-checklistreadme-autoscan
readme-autoscan --dry-run
readme-autoscan --output docs/README.md
readme-autoscan --force
readme-autoscan --include-tree
readme-autoscan --no-checklist| Option | Description |
|---|---|
--output <file> |
Write README to a custom file (default: README.md) |
--force |
Overwrite existing README.md |
--dry-run |
Print generated README without writing a file |
--include-tree |
Include project structure in the README |
--no-checklist |
Skip publishing checklist section |
-v, --version |
Show package version |
-h, --help |
Show help message |
Here's what a generated README looks like:
# my-awesome-package
A fantastic package that does amazing things.
## Features
- Auto-generated README with project metadata
- Project type detection (Node.js package, TypeScript package)
- NPM scripts documentation with descriptions
- Clean, professional markdown formatting
## Installation
\`\`\`bash
npm install my-awesome-package
\`\`\`
## Usage
\`\`\`javascript
import myawesomepackage from "my-awesome-package";
// Use the package
myawesomepackage.someFunction();
\`\`\`
## Available Scripts
| Script | Description | Command |
| ------ | ------------------------ | ------------------- |
| dev | Start development server | `vite` |
| build | Build for production | `tsc && vite build` |
| test | Run test suite | `vitest` |
## License
This project is licensed under the MIT License.README Auto Scan automatically detects these project types:
| Type | Detection Criteria |
|---|---|
| CLI Package | Has bin field in package.json |
| TypeScript | Has typescript dependency or tsconfig.json |
| React App | Has react dependency |
| Vue App | Has vue dependency |
| Next.js | Has next dependency or next.config.js |
| Vite | Has vite dependency or vite.config.* |
| Express | Has express dependency |
| Python | Has requirements.txt, pyproject.toml, setup.py, etc. |
| Django | Has manage.py or django in dependencies |
| Flask | Has app.py or flask in dependencies |
| Laravel | Has artisan or laravel/framework in composer requirements |
README Auto Scan supports JavaScript, TypeScript, Python, and PHP projects.
| Language | Detection Files |
|---|---|
| JavaScript/TypeScript | package.json, tsconfig.json, vite.config.*, next.config.js |
| Python | requirements.txt, pyproject.toml, setup.py, Pipfile, poetry.lock, main.py, app.py, manage.py |
| PHP | composer.json, composer.lock, index.php, artisan, phpunit.xml, phpunit.xml.dist |
README Auto Scan automatically detects your package manager from lock files and generates matching commands.
| Lock File | Package Manager |
|---|---|
package-lock.json |
npm |
pnpm-lock.yaml |
pnpm |
yarn.lock |
yarn |
bun.lockb or bun.lock |
bun |
Example with pnpm:
pnpm install
pnpm dev
pnpm buildREADME Auto Scan detects common Python project files and generates Python-friendly README sections.
| Python Tool | Detection File | Example Commands |
|---|---|---|
| pip | requirements.txt |
pip install -r requirements.txt |
| Poetry | pyproject.toml, poetry.lock |
poetry install |
| Pipenv | Pipfile |
pipenv install |
| Django | manage.py |
python manage.py runserver |
Example Python README output:
# my-python-project
A Python project.
## Installation
\`\`\`bash
pip install -r requirements.txt
\`\`\`
### Python Example
Run the application:
\`\`\`bash
python main.py
\`\`\`
Run tests:
\`\`\`bash
pytest
\`\`\`
Dependencies:
| Package | Version |
| ------- | ------- |
| requests | latest |
| flask | ==3.0.0 |README Auto Scan detects common PHP and Laravel project files and generates PHP-friendly README sections.
| PHP Type | Detection Files |
|---|---|
| Basic PHP | index.php, composer.json |
| Composer | composer.json, composer.lock |
| Laravel | artisan, routes/web.php, routes/api.php, bootstrap/app.php, app/Http |
| PHPUnit | phpunit.xml, phpunit.xml.dist |
| PHP Tool | Example Commands |
|---|---|
| Composer | composer install |
| Laravel Artisan | php artisan serve |
| Laravel Tests | php artisan test |
| PHPUnit | vendor/bin/phpunit |
# Install dependencies
npm install
# Run type checking
npm run check
# Build the project
npm run build
# Run tests
npm test
# Preview generated README for this project
npm run devreadme-autoscan/
├─ src/
│ ├─ cli.ts # CLI entry point and argument parsing
│ ├─ scanner.ts # Project scanning and analysis
│ ├─ detector.ts # Project type detection
│ ├─ generator.ts # README markdown generation
│ ├─ env.ts # .env.example parsing
│ ├─ scripts.ts # NPM script descriptions
│ ├─ package-manager.ts # Package manager detection
│ ├─ utils.ts # Utility functions
│ └─ languages/
│ ├─ python.ts # Python project detection
│ └─ php.ts # PHP/Laravel project detection
├─ tests/
│ ├─ generator.test.ts
│ ├─ package-manager.test.ts
│ ├─ scripts.test.ts
│ ├─ utils.test.ts
│ ├─ env.test.ts
│ └─ python.test.ts # Python detection tests
├─ bin/
│ └─ readme-autoscan.js # Executable entry point
├─ package.json
├─ tsconfig.json
├─ README.md
└─ LICENSE
The tool generates these sections based on your project:
- Title & Description — From package.json
- Features — Auto-detected capabilities
- Installation — NPM install instructions
- Usage — CLI or library usage examples
- CLI Usage — If it's a CLI package
- Available Scripts — Markdown table from package.json
- Environment Variables — From .env.example
- Project Structure — With
--include-tree - API / Exports — Main/module/types entries
- Development — Setup instructions
- Publishing Checklist — For npm packages
- License — From package.json
- Contributing — Standard contribution message
README Auto Scan includes example generated README files for all supported project types. Use these examples to preview the README style before running the CLI in your own project.
| Project Type | Example |
|---|---|
| JavaScript Package | examples/javascript-package/README.generated.md |
| TypeScript Package | examples/typescript-package/README.generated.md |
| Python pip Project | examples/python-pip/README.generated.md |
| Python Poetry Project | examples/python-poetry/README.generated.md |
| Python Pipenv Project | examples/python-pipenv/README.generated.md |
| Python Django Project | examples/python-django/README.generated.md |
| Basic PHP Project | examples/php-basic/README.generated.md |
| Laravel Project | examples/php-laravel/README.generated.md |
Preview an example locally:
cd examples/python-pip
npx readme-autoscan --dry-runSee examples/README.md for more details.
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License — see the LICENSE file for details.
Copyright (c) 2026 JomsCode21
- Repository: github.com/JomsCode21/README-auto-scan
- Issues: github.com/JomsCode21/README-auto-scan/issues
- NPM Package: npmjs.com/package/readme-autoscan
Made for the JavaScript, TypeScript, Python, and PHP community