# ๐Ÿš€ StaticFlow **Automated SSG Engine for React SPAs** โ€” Zero-config static site generation with AI-first optimization. [![npm version](https://img.shields.io/npm/v/@mamdouh-aboammar/staticflow.svg)](https://www.npmjs.com/package/@mamdouh-aboammar/staticflow) [![npm downloads](https://img.shields.io/npm/dm/@mamdouh-aboammar/staticflow.svg)](https://www.npmjs.com/package/@mamdouh-aboammar/staticflow) [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![GitHub stars](https://img.shields.io/github/stars/Pixora-dev-ai/StaticFlow.svg?style=social&label=Star)](https://github.com/Pixora-dev-ai/StaticFlow) [![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue)](https://www.typescriptlang.org/) [![React 19](https://img.shields.io/badge/React-19-61dafb)](https://react.dev/) --- ## ๐ŸŽฏ Problem **React SPAs render empty HTML:** ```html My Site
``` **Result:** - โŒ AI crawlers (ChatGPT, Claude, Gemini) see nothing - โŒ Search engines index empty pages - โŒ No SEO/AEO/GEO optimization - โŒ Poor social media previews --- ## โœจ Solution **StaticFlow transforms your SPA into fully static, pre-rendered HTML:** ```html My Awesome App | Home

Welcome to My Awesome App

``` **Result:** - โœ… AI agents read full content - โœ… Search engines index everything - โœ… Perfect SEO/AEO/GEO scores - โœ… Rich social media previews --- ## ๐Ÿ“ฆ Installation ```bash npm install @mamdouh-aboammar/staticflow --save-dev # Optional: For ZIP deployment feature npm install archiver --save-dev ``` --- ## ๐Ÿš€ Quick Start ### 1. Vite Plugin (Recommended) Add to your `vite.config.ts`: ```typescript import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import { staticFlowPlugin } from '@mamdouh-aboammar/staticflow'; export default defineConfig({ plugins: [ react(), staticFlowPlugin({ // Zero config! Auto-detects routes, pages, content }), ], }); ``` Build your site: ```bash npm run build ``` **That's it!** StaticFlow automatically: - ๐Ÿ“„ Scans all routes in `src/pages/`, `src/routes/` - ๐Ÿ”ง Pre-renders HTML with React 19 SSR - ๐Ÿ“‹ Generates `sitemap.xml` + `ai-sitemap.xml` - ๐Ÿ—œ๏ธ Minifies HTML/CSS/JS - ๐Ÿš€ Outputs to `dist/` ready for deployment --- ### 2. CLI Tool ```bash # Build static site npx staticflow build # Analyze project structure npx staticflow analyze # Build + create deployment ZIP npx staticflow build --zip # Skip optimization npx staticflow build --no-optimize ``` --- ## ๐Ÿ“š API Reference ### `staticFlowPlugin(config?)` Vite plugin for automatic SSG. ```typescript interface StaticFlowConfig { root?: string; // Project root (default: process.cwd()) base?: string; // Base URL path (default: '/') routes?: { include?: string[]; // Glob patterns (default: ['src/pages/**/*.tsx']) exclude?: string[]; // Exclude patterns }; content?: { dir?: string; // Content directory (default: 'src/content') patterns?: string[]; // File patterns (default: ['**/*.md', '**/*.mdx']) }; output?: { dir?: string; // Output directory (default: 'dist') sitemap?: boolean; // Generate sitemaps (default: true) robots?: boolean; // Generate robots.txt (default: true) }; seo?: { defaultTitle?: string; defaultDescription?: string; keywords?: string[]; twitterSite?: string; ogImage?: string; }; optimization?: { minifyHTML?: boolean; // Minify HTML (default: true) minifyCSS?: boolean; // Minify CSS (default: true) minifyJS?: boolean; // Minify JS (default: true) inlineCriticalCSS?: boolean; // Inline critical CSS (default: true) }; hooks?: { beforeScan?: () => void | Promise; afterScan?: (routes: Route[]) => void | Promise; beforeRender?: (route: Route) => void | Promise; afterRender?: (result: RenderResult) => void | Promise; beforeBuild?: () => void | Promise; afterBuild?: (result: BuildResult) => void | Promise; }; } ``` --- ### `StaticFlowEngine` Programmatic API for advanced use cases. ```typescript import { StaticFlowEngine } from '@staticflow/core'; const engine = new StaticFlowEngine({ root: process.cwd(), output: { dir: 'dist' }, }); // Scan project const scanResult = await engine.scan(); // Pre-render routes await engine.preRender(scanResult.routes, (completed, total) => { console.log(`Progress: ${completed}/${total}`); }); // Generate sitemaps await engine.generateSitemaps(scanResult.routes); // Full build const buildResult = await engine.build(); ``` --- ## ๐ŸŽจ Features ### โœ… Zero-Config Auto-Discovery Automatically finds: - **Static pages**: `src/pages/Home.tsx` โ†’ `/` - **Nested routes**: `src/pages/about/Team.tsx` โ†’ `/about/team` - **Dynamic routes**: `src/routes/BlogPost.tsx` โ†’ `/blog/:slug` - **Content files**: `src/content/posts/hello.md` โ†’ `/blog/hello` ### โœ… React 19 SSR Uses latest React APIs: - `renderToStaticMarkup()` for full HTML - `react-helmet-async` for meta tags - Streaming support (future) ### โœ… AI-First Optimization Generates **2 sitemaps**: **sitemap.xml** (standard): ```xml https://your-site.com/ 2025-11-18 1.0 ``` **ai-sitemap.xml** (AI-optimized): ```xml https://your-site.com/ 1.0 weekly Comprehensive documentation and guides for React developers... React, SPA, SSG, SEO, Static Generation, Performance ``` ### โœ… Performance Optimization - ๐Ÿ—œ๏ธ HTML/CSS/JS minification (30-50% reduction) - ๐ŸŽจ Critical CSS inlining (faster FCP) - ๐Ÿ“ฆ Asset compression - ๐Ÿš€ Parallel rendering (5 routes at once) ### โœ… Internationalization (i18n) Preserves: - `dir` attributes (RTL/LTR) - `lang` attributes (any language) - Helmet meta tags in any language - Structured data localization --- ## ๐Ÿ“Š Performance **Real-world production site (42 pages):** | Metric | Before (SPA) | After (StaticFlow) | Improvement | |--------|-------------|-------------------|-------------| | **HTML Size** | 1.2KB (empty) | 10KB+ (full) | **+733%** | | **First Contentful Paint** | 2.8s | 0.9s | **3.1x faster** | | **SEO Score** | 45/100 | 98/100 | **+118%** | | **AI Indexable** | โŒ 0 pages | โœ… 42 pages | **โˆž** | | **Build Time** | 8.2s | 14.2s | +6s | --- ## ๐Ÿ—๏ธ Architecture ``` StaticFlow Engine โ”‚ โ”œโ”€โ”€ Scanner (Auto-Discovery) โ”‚ โ”œโ”€โ”€ scanStaticPages() โ†’ src/pages/**/*.tsx โ”‚ โ”œโ”€โ”€ scanContentFiles() โ†’ src/content/**/*.md โ”‚ โ””โ”€โ”€ scanDynamicRoutes() โ†’ src/routes/**/*.tsx โ”‚ โ”œโ”€โ”€ Renderer (SSR) โ”‚ โ”œโ”€โ”€ renderRoute() โ†’ React โ†’ HTML โ”‚ โ”œโ”€โ”€ renderAll() โ†’ Parallel (5x) โ”‚ โ””โ”€โ”€ minifyHTML() โ†’ html-minifier-terser โ”‚ โ”œโ”€โ”€ Optimizer (Assets) โ”‚ โ”œโ”€โ”€ minifyHTML() โ”‚ โ”œโ”€โ”€ minifyCSS() โ”‚ โ”œโ”€โ”€ inlineCriticalCSS() โ”‚ โ””โ”€โ”€ compressImages() โ†’ (requires sharp) โ”‚ โ””โ”€โ”€ Engine (Orchestrator) โ”œโ”€โ”€ scan() โ†’ Routes โ”œโ”€โ”€ preRender() โ†’ HTML files โ”œโ”€โ”€ generateSitemaps() โ†’ sitemap.xml, ai-sitemap.xml โ””โ”€โ”€ build() โ†’ Full pipeline ``` --- ## ๐Ÿงช Testing ```bash # Run tests npm test # Type check npm run typecheck # Build library npm run build ``` --- ## ๐Ÿ“ Examples ### Custom SEO ```typescript staticFlowPlugin({ seo: { defaultTitle: 'My Awesome App', defaultDescription: 'A modern React application with full SEO support', keywords: ['react', 'spa', 'ssg', 'seo'], ogImage: 'https://your-site.com/og-image.jpg', twitterSite: '@your_handle', }, }); ``` ### Lifecycle Hooks ```typescript staticFlowPlugin({ hooks: { afterScan: async (routes) => { console.log(`Found ${routes.length} routes`); }, beforeRender: async (route) => { console.log(`Rendering ${route.path}...`); }, afterBuild: async (result) => { console.log(`Build complete in ${result.duration}ms`); }, }, }); ``` ### Custom Routes ```typescript staticFlowPlugin({ routes: { include: [ 'src/pages/**/*.tsx', 'src/views/**/*.tsx', 'app/routes/**/*.tsx', ], exclude: ['**/*.test.tsx', '**/*.stories.tsx'], }, }); ``` --- ## ๐Ÿšข Deployment ### Hostinger (Apache/LiteSpeed) ```bash # Build + ZIP npx staticflow build --zip # Upload to Hostinger # Extract to public_html/ # Done! โœ… ``` ### Vercel/Netlify ```bash npm run build # Outputs to dist/ # Auto-deploys via Git ``` ### Docker ```dockerfile FROM node:22-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build # Serve dist/ with nginx/serve ``` --- ## ๐Ÿค Contributing We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md). --- ## ๐Ÿ“„ License MIT ยฉ 2025 Mamdouh Aboammar --- ## ๐Ÿ™ Credits **Built with:** - [React 19](https://react.dev/) โ€” UI framework - [Vite](https://vite.dev/) โ€” Build tool - [TypeScript](https://www.typescriptlang.org/) โ€” Type safety - [fast-glob](https://github.com/mrmlnc/fast-glob) โ€” File scanning - [gray-matter](https://github.com/jonschlinkert/gray-matter) โ€” Markdown parsing - [html-minifier-terser](https://github.com/terser/html-minifier-terser) โ€” HTML optimization --- ## ๐Ÿ“ž Support - **Issues**: [GitHub Issues](https://github.com/Pixora-dev-ai/StaticFlow/issues) - **Discussions**: [GitHub Discussions](https://github.com/Pixora-dev-ai/StaticFlow/discussions) - **Email**: mamdouhfces1997@gmail.com --- **Made with โค๏ธ for the React community**