A modern Python CLI tool that scans Laravel applications using Inertia.js and Vue 3 to identify potential Server-Side Rendering (SSR) compatibility issues.
- ✨ Features
- 💡 Why InertiaSSRPrepper?
- 🚀 Installation
- 🏃♂️ Quick Start
- 📊 Examples
- 📘 Usage
- 🔍 Issue Categories
- 📤 Output Formats
- 🛠️ Development
- 🤝 Contributing
- 📄 License
- 🙏 Acknowledgements
- 🔍 Scans your entire Laravel + Inertia.js + Vue 3 codebase for SSR compatibility issues
- 🚫 Identifies 25+ common SSR problems with detailed pattern matching
- 🎨 Generates colorful, interactive reports in terminal, HTML, or JSON formats
- 🧠 Uses Claude 3.7 AI to provide tailored, contextual solutions for each issue
- ⚡ Shows real-time progress with detailed statistics while scanning large codebases
- 🚦 Categorizes issues by severity (critical, major, medium, minor) for prioritization
- 🔧 Customizable ignore patterns and detection rules
- 🔍 Supports interactive search and filtering in HTML reports
Implementing Server-Side Rendering in an existing Laravel Inertia.js application can be challenging due to numerous client-side dependencies and browser-specific code patterns. InertiaSSRPrepper helps you:
- Identify SSR issues before they break your production app - Catch all potential SSR problems early
- Save hours of debugging time - Automatically find issues that would take days to discover manually
- Get expert solutions - Receive AI-powered suggestions for fixing each issue
- Plan your SSR migration - Prioritize fixes based on severity
- Improve overall code quality - Many SSR issues are also general best practices problems
# Clone this repository
git clone https://github.com/yourusername/inertiassrprepper.git
cd inertiassrprepper
# Install with uv
uv pip install -e .
# Or install with pip
pip install -e .Scan your Laravel Inertia.js application in just one step:
# Basic scan with terminal output
inertiassr scan /path/to/your/laravel/app
# Generate HTML report with Claude AI suggestions
inertiassr scan /path/to/your/laravel/app --output report.html --api-key $ANTHROPIC_API_KEYinertiassr scan /path/to/app --output report.html --api-key your-anthropic-keyinertiassr scan /path/to/app --output report.jsoninertiassr scan /path/to/app --ignore "*.test.js,*.spec.js,legacy/*"inertiassr scan /path/to/app --verbose| Option | Description |
|---|---|
path |
Path to your Laravel + Inertia.js application (required) |
--api-key, -k |
Anthropic API key for Claude (can also use ANTHROPIC_API_KEY env var) |
--output, -o |
Output file path for report (defaults to stdout) |
--format, -f |
Report format: 'json' or 'html' (defaults to using file extension) |
--ignore, -i |
Additional glob patterns to ignore (already ignores .git, node_modules, vendor, public, storage, etc.) |
--verbose, -v |
Enable verbose output |
--no-verify |
Skip verification of Laravel Inertia app |
--max-files |
Maximum number of files to scan (for testing) |
--version |
Show version information and exit |
ANTHROPIC_API_KEY: Your Anthropic API key for Claude integration
Click to expand issue categories
Issues are categorized by severity to help you prioritize fixes:
| Severity | Description |
|---|---|
| Critical | Issues that will completely break SSR functionality |
| Major | Issues likely to cause SSR rendering failures |
| Medium | Issues that may cause inconsistent SSR behavior |
| Minor | Issues that could cause subtle differences between SSR and client rendering |
- Browser API usage (
window,document,navigator, etc.) - Direct DOM manipulation (
document.getElementById, etc.) - Client-side only libraries (jQuery, etc.)
- Incorrect lifecycle hooks (Vue 2 style instead of Vue 3 Composition API)
- Improper Inertia.js imports
- Legacy Vue instance creation
- Direct event listener attachment
- Dynamic component loading without proper handling
- Incorrect Inertia props access
- Meta tag manipulation
- Timer functions without proper cleanup
- Missing key attributes on v-for loops
- Component registration issues
- Import path case sensitivity issues
- Browser-specific CSS features
- Inline scripts in templates
- Third-party script tags
- Colorful, interactive report in the terminal
- Tables showing issues grouped by file
- Issues are color-coded by severity
- Syntax-highlighted code snippets
- Interactive HTML report with filters and search
- Collapsible file sections
- Color-coded severities
- Syntax highlighting for code snippets
- Statistics and charts
- Browser-compatible simplified HTML report for maximum compatibility
- Structured JSON data for further processing
- Includes full issue details, file paths, line numbers, and solutions
- Compatible with other tools and integrations
╭─── SSR Compatibility Scan Summary ────────────────────────────────────╮
│ │
│ SSR Compatibility Scan Complete │
│ Found 24 potential issues in 8 files │
│ │
│ ┌────────────┬───────┐ │
│ │ Total Issues│ 24 │ │
│ │ Files with Issues│ 8 │ │
│ │ Issue Types│ 12 │ │
│ └────────────┴───────┘ │
│ │
│ ┌─────── Issues by Severity ────────┐ │
│ │ Severity │ Count │ Percentage │ Distribution │
│ │ Critical │ 8 │ 33.3% │ ████████████████ │
│ │ Major │ 10 │ 41.7% │ ████████████████████ │
│ │ Medium │ 4 │ 16.7% │ ████████ │
│ │ Minor │ 2 │ 8.3% │ ████ │
│ └───────────┴───────┴───────────────┴──────────────────────────────────┘
╰───────────────────────────────────────────────────────────────────────╯
# Clone the repository
git clone https://github.com/yourusername/inertiassrprepper.git
cd inertiassrprepper
# Create a virtual environment (recommended)
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install development dependencies
uv pip install -e ".[dev]"pytestruff checkContributions 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 'Add some 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.
Made with ❤️ for the Laravel and Inertia.js community