Jepsh Ssg

A static site generator for modern web frameworks with route crawling and hydration support

#cli #hydration #puppeteer #react #ssg #static-site-generator #svelte #vue #web-crawler #jepsh

JepshSSG - Static Site Generator

JepshSSG is a powerful static site generator that crawls modern web applications (JepshJS, React, Vue, Svelte) and generates static HTML files for improved performance and SEO. It supports dynamic routes, sitemap generation, incremental builds, and provides a sleek CLI experience with interactive configuration.

This is a built-in tool for the JepshJS web framework.

Why JepshSSG?

Static site generation transforms your dynamic single-page applications into pre-rendered HTML files, providing numerous benefits:

Performance: Pre-rendered pages load instantly, reducing time-to-first-byte
SEO Optimization: Search engines can easily crawl and index static HTML content
Better Core Web Vitals: Improved LCP, FID, and CLS scores
Cost Effective: Serve static files from CDNs with minimal server resources
Enhanced Security: No server-side vulnerabilities in static files

Features

Dynamic Routes: Full support for parameterized routes (e.g., /users/:id, /blog/:slug)
Sitemap Generation: Automatically creates sitemap.xml for enhanced SEO
Incremental Builds: Smart caching system skips unchanged routes for faster builds
Watch Mode: Automatically rebuilds when source files change
Auto-Route Detection: Intelligently infers routes from your input directory structure
Hydration Support: Seamlessly injects client-side JavaScript for interactivity
Debug Tools: Comprehensive debugging with screenshots and detailed logs
Flexible Configuration: Multiple configuration methods with clear precedence
Interactive CLI: User-friendly prompts guide you through setup
CSS Optimization: Built-in CSS inlining with Critters for performance

Installation

Global Installation (Recommended)

npm install -g jepsh-ssg

Local Installation

npm install jepsh-ssg --save-dev
npx jepsh-ssg

Using with Different Package Managers

# Using Yarn
yarn global add jepsh-ssg
# or locally
yarn add -D jepsh-ssg

# Using pnpm
pnpm add -g jepsh-ssg
# or locally
pnpm add -D jepsh-ssg

Quick Start

Build your application (React, Vue, Svelte, or JepshJS)
Run JepshSSG to generate static files:

npx jepsh-ssg

Deploy the generated static files to any hosting platform

Example Workflow

# Build your React/Vue/Svelte app
npm run build

# Generate static site
npx jepsh-ssg --routes /,/about,/contact --sitemap --base-url https://mysite.com

# Deploy (example with Netlify)
netlify deploy --prod --dir=build-ssg

Configuration

JepshSSG offers flexible configuration with the following precedence order:

CLI Flags (highest priority)
Configuration File (jepsh.config.js or package.json)
Interactive Prompts (when no config is found)

1. CLI Flags

Basic Usage:

npx jepsh-ssg --routes /,/about --port 5000 --out-dir static

Advanced Usage with Hydration:

npx jepsh-ssg --hydrate --hydrate-bundle assets/js/main.js --sitemap --base-url https://example.com

Complete Flag Reference:

Flag	Description	Corresponding Field
`--routes <routes>`	Comma-separated routes or 'auto' for auto-detection	`routes`
`--base-path <path>`	Base path prefix for all routes	`basePath`
`--base-url <url>`	Base URL for sitemap generation (e.g., `https://example.com`)	`baseUrl`
`-i, --input-dir <path>`	Input directory containing built files	`inputDir`
`-o, --out-dir <path>`	Output directory for generated static files	`outDir`
`-p, --port <number>`	Development server port (1-65535)	`port`
`--concurrency <number>`	Number of concurrent crawling processes	`concurrency`
`--flat-output`	Generate `page.html` instead of `page/index.html`	`flatOutput`
`--hydrate`	Enable client-side hydration (experimental)	`hydrate`
`--hydrate-bundle <path>`	Path to hydration bundle (relative to input directory)	`hydrateBundle`
`--framework <name>`	Target framework: `react`, `vite`, `vue`, or `svelte`	`framework`
`--batch-size <number>`	Number of routes to process per batch	`batchSize`
`--incremental`	Enable incremental builds with caching (experimental)	`incremental`
`-t, --timeout <number>`	Timeout per route in milliseconds	`timeout`
`--inline-css`	Enable CSS inlining optimization	`inlineCss`
`--sitemap`	Generate sitemap.xml (recommended for SEO)	`sitemap`
`--exclude-routes <routes>`	Comma-separated routes to exclude from generation	`excludeRoutes`
`--custom-selectors <selectors>`	Custom CSS selectors for content extraction	`customSelectors`
`--watch`	Watch for file changes and rebuild automatically	-
`--dry-run`	Preview routes without generating files	-
`-V, --version`	Display version information	-
`-h, --help`	Show help information	-
`--clear-cache`	Clear cached data in `.jepsh`	-
`--clear-logs`	Clear logs in `.jepsh`	-
`--clean`	Clear all cache and logs in `.jepsh`	-

💡 Tip: When using --sitemap, always specify --base-url for proper SEO. Without it, URLs will default to https://localhost:3000.

2. Configuration File

Using `jepsh.config.js` (Recommended)

export default {
  ssg: {
    routes: ["/", "/about", "/contact"],
    inputDir: "dist",
    outDir: "dist-ssg",
    baseUrl: "https://mysite.com",
    sitemap: true,
    framework: "react",
    concurrency: 5,
    timeout: 45000,
    hydrate: true,
    hydrateBundle: "assets/js/bundle.js",
  },
};

Using `package.json`

{
  "name": "my-app",
  "scripts": {
    "build": "vite build",
    "ssg": "jepsh-ssg"
  },
  "jepsh": {
    "ssg": {
      "routes": ["/", "/about", "/contact"],
      "inputDir": "dist",
      "outDir": "dist-ssg",
      "baseUrl": "https://mysite.com",
      "sitemap": true
    }
  }
}

Dynamic Routes Configuration

For applications with dynamic routes, use objects with path and params:

export default {
  ssg: {
    routes: [
      "/",
      "/about",
      {
        path: "/users/:id",
        params: [{ id: "1" }, { id: "2" }, { id: "admin" }],
      },
      {
        path: "/blog/:category/:slug",
        params: [
          { category: "tech", slug: "react-tips" },
          { category: "design", slug: "ui-patterns" },
        ],
      },
    ],
    // ... other configuration
  },
};

Complete Configuration Reference

Field	Type	Description	Default	CLI Flag
`routes`	`string[]` \| `object[]`	Routes to crawl or 'auto' for detection	`['/']`	`--routes`
`basePath`	`string`	Base path prefix for routes	`''`	`--base-path`
`baseUrl`	`string`	Base URL for sitemap and canonical URLs	`'http://localhost:3000'`	`--base-url`
`inputDir`	`string`	Directory containing built application files	`'build'`	`-i, --input-dir`
`outDir`	`string`	Output directory for static files	`'build-ssg'`	`-o, --out-dir`
`port`	`number`	Development server port	`3000`	`-p, --port`
`concurrency`	`number`	Concurrent crawling processes	`3`	`--concurrency`
`flatOutput`	`boolean`	Flat file structure vs. directory structure	`false`	`--flat-output`
`hydrate`	`boolean`	Enable client-side hydration (experimental)	`false`	`--hydrate`
`hydrateBundle`	`string`	Path to hydration JavaScript bundle	`null`	`--hydrate-bundle`
`framework`	`'react'` \| `'vite'` \| `'vue'` \| `'svelte'`	Target framework for optimization	`'react'`	`--framework`
`batchSize`	`number`	Routes processed per batch	`50`	`--batch-size`
`incremental`	`boolean`	Enable incremental builds (experimental)	`false`	`--incremental`
`timeout`	`number`	Timeout per route in milliseconds	`30000`	`-t, --timeout`
`inlineCss`	`boolean`	Enable CSS inlining with Critters	`false`	`--inline-css`
`sitemap`	`boolean`	Generate sitemap.xml	`false`	`--sitemap`
`excludeRoutes`	`string[]`	Routes to exclude from generation	`[]`	`--exclude-routes`
`customSelectors`	`string[]`	Custom CSS selectors for content	`[]`	`--custom-selectors`

⚠️ Note: CLI flags always override configuration file settings. Features like --watch and --dry-run are CLI-only but can be combined with file configuration.

3. Interactive Configuration

When no configuration is detected, JepshSSG launches an interactive setup wizard:

npx jepsh-ssg

? Input directory (where your built files are located): dist
? Output directory (where static files will be saved): dist-ssg
? Server port (1-65535): 3000
? Routes to crawl (comma-separated or 'auto'): /,/about,/users/:id[1,2,3]
? Enable sitemap generation? (Y/n): Y
? Base URL for sitemap: https://mysite.com
? Framework (react/vite/vue/svelte): react
? Enable CSS inlining? (Y/n): Y
? Concurrency level (1-10): 3

The wizard saves your preferences and generates a configuration file for future use.

Advanced Features

1. Sitemap Generation

JepshSSG automatically generates SEO-optimized sitemaps with proper lastmod timestamps and canonical URLs.

Enable sitemap generation:

npx jepsh-ssg --sitemap --base-url https://mysite.com

Generated sitemap.xml example:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://mysite.com/</loc>
    <lastmod>2025-05-30T04:42:18.000Z</lastmod>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://mysite.com/about</loc>
    <lastmod>2025-05-30T04:42:18.000Z</lastmod>
    <priority>0.8</priority>
  </url>
  <url>
    <loc>https://mysite.com/users/1</loc>
    <lastmod>2025-05-30T04:42:18.000Z</lastmod>
    <priority>0.6</priority>
  </url>
</urlset>

2. Incremental Builds

Dramatically reduce build times by only regenerating changed routes. JepshSSG maintains a cache of file hashes to detect changes.

Enable incremental builds:

npx jepsh-ssg --incremental

How it works:

Calculates checksums for source files
Stores metadata in .jepsh/caches/ssg.json
Skips unchanged routes on subsequent builds
Automatically handles dependency changes

⚠️ Experimental: This feature is under active development. Please report issues on our GitHub repository.

3. Debug and Development Tools

JepshSSG provides comprehensive debugging capabilities for troubleshooting generation issues.

Debug folder structure:

.jepsh/
├── caches/
│   └── ssg.json                 # Incremental build cache
└── debug/
    ├── logs/
    │   └── ssg.log              # Detailed operation logs
    └── screenshots/
        └── ssg/
            ├── _.png            # Homepage screenshot
            ├── _about.png       # About page screenshot
            └── _users_1.png     # Dynamic route screenshot

Add to .gitignore:

# Dependencies
/node_modules/

# JepshSSG debug and cache files
/.jepsh/

# Environment files
.env*

4. Watch Mode

Automatically rebuild when source files change during development:

npx jepsh-ssg --watch

Perfect for development workflows where you want to see static generation results in real-time.

5. Hydration Support (Experimental)

Add client-side interactivity to your static pages:

npx jepsh-ssg --hydrate --hydrate-bundle assets/js/app.js

How hydration works:

Generates static HTML for fast initial load
Injects specified JavaScript bundle
Re-hydrates components for full interactivity
Maintains SEO benefits with dynamic functionality

Framework-Specific Examples

React with CRA

# Build React app
npm run build

# Generate static site
npx jepsh-ssg --framework react --input-dir build

React with Vite

# Build React app
npm run build

# Generate static site
npx jepsh-ssg --framework vite --input-dir dist --sitemap --base-url https://myapp.com

Vue with Nuxt

# Build Vue app
npm run generate

# Generate static site
npx jepsh-ssg --framework vue --input-dir .output/public --routes auto

Svelte with SvelteKit

# Build Svelte app
npm run build

# Generate static site
npx jepsh-ssg --framework svelte --input-dir build --hydrate

Performance Optimization

CSS Optimization

JepshSSG uses Critters to inline critical CSS:

Automatically inlines above-the-fold CSS
Lazy-loads non-critical stylesheets
Reduces render-blocking resources
Improves Core Web Vitals scores

Batch Processing

Configure batch processing for optimal performance:

# Process 20 routes at a time with 5 concurrent workers
npx jepsh-ssg --batch-size 20 --concurrency 5

Memory Management

For large sites, tune memory usage:

# Increase Node.js memory limit
NODE_OPTIONS="--max-old-space-size=4096" npx jepsh-ssg

Logging and Reporting

JepshSSG provides detailed logging and comprehensive reports:

  ███████╗███████╗██████╗ ███████╗██╗  ██╗
  ╚══███╔╝██╔════╝██╔══██╗██╔════╝██║  ██║
    ███╔╝ █████╗  ██████╔╝███████╗███████║
   ███╔╝  ██╔══╝  ██╔═══╝ ╚════██║██╔══██║
  ███████╗███████╗██║     ███████║██║  ██║
  ╚══════╝╚══════╝╚═╝     ╚══════╝╚═╝  ╚═╝
  v1.0.17

• Configuration
  Routes      : 15 routes (3 dynamic)
  Input       : dist
  Output      : dist-ssg
  Port        : 3000
  Framework   : react
  Started     : 5/30/2025, 7:05:18 PM

+ [7:05:18 PM]  INFO     Serving dist at http://localhost:3000
✔ [7:05:19 PM]  SUCCESS  Copied 'dist' → 'dist-ssg' (2.3 MB)
+ [7:05:20 PM]  INFO     Processing batch 1/3 (5 routes)...
+ [7:05:24 PM]  SUCCESS  CSS inlined for 5 routes
✔ [7:05:24 PM]  SUCCESS  Batch 1/3 completed
+ [7:05:25 PM]  INFO     Processing batch 2/3 (5 routes)...
✔ [7:05:28 PM]  SUCCESS  Batch 2/3 completed
+ [7:05:29 PM]  INFO     Processing batch 3/3 (5 routes)...
✔ [7:05:32 PM]  SUCCESS  Batch 3/3 completed
+ [7:05:32 PM]  INFO     Cache saved: '.jepsh/caches/ssg.json'
+ [7:05:32 PM]  SUCCESS  Generated sitemap: 'dist-ssg/sitemap.xml'
✔ [7:05:32 PM]  SUCCESS  Crawling finished

• Reports
  Successful  : 15 routes
  Failed      : 0 routes
  Total       : 15 routes
  Skipped     : 2 routes (excluded)

• Performance
  Duration    : 14.2s
  Average     : 0.95s per route
  Cache hits  : 3 routes
  File size   : 4.7 MB generated

+ [7:05:32 PM]  SUCCESS  All 15 route(s) processed successfully
+ [7:05:32 PM]  SUCCESS  Done!

Troubleshooting

Common Issues

1. Routes not found

# Enable debug mode and check auto-detection
npx jepsh-ssg --routes auto --dry-run

2. Build fails with timeout

# Increase timeout for complex pages
npx jepsh-ssg --timeout 60000

3. Memory issues

# Reduce concurrency and batch size
npx jepsh-ssg --concurrency 1 --batch-size 10

4. CSS not loading

# Enable CSS inlining if needed
npx jepsh-ssg --inline-css

Debug Information

Check debug logs for detailed information:

# View debug logs
cat .jepsh/debug/logs/ssg.log

# View generated screenshots
ls .jepsh/debug/screenshots/ssg/

Integration Examples

GitHub Actions

name: Deploy Static Site

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "18"

      - name: Install dependencies
        run: npm ci

      - name: Build application
        run: npm run build

      - name: Generate static site
        run: npx jepsh-ssg --sitemap --base-url https://mysite.com

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build-ssg

Netlify Configuration

Create netlify.toml:

[build]
  command = "npm run build && npx jepsh-ssg --sitemap --base-url https://mysite.netlify.app"
  publish = "build-ssg"

[build.environment]
  NODE_VERSION = "18"

[[headers]]
  for = "/*"
  [headers.values]
    X-Frame-Options = "DENY"
    X-XSS-Protection = "1; mode=block"

Vercel Configuration

Create vercel.json:

{
  "buildCommand": "npm run build && npx jepsh-ssg --sitemap --base-url https://mysite.vercel.app",
  "outputDirectory": "build-ssg",
  "framework": null
}

Migration Guide

From Gatsby

# Replace gatsby build with:
npm run build  # Your normal build command
npx jepsh-ssg --routes auto --sitemap --base-url https://yoursite.com

From Next.js Static Export

# Replace next export with:
npm run build
npx jepsh-ssg --framework react --routes auto --sitemap

From Nuxt Generate

# Replace nuxt generate with:
npm run build
npx jepsh-ssg --framework vue --input-dir .output/public --routes auto

Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Clone your fork: git clone https://github.com/yourusername/jepsh-ssg.git
Install dependencies: npm install
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Test your changes: npm test
Commit your changes: git commit -m 'Add amazing feature'
Push to your branch: git push origin feature/amazing-feature
Create a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/jepsh/jepsh-ssg.git
cd jepsh-ssg

# Install dependencies
npm install

# Run tests
npm test

# Run in development mode
npm run dev

Code Style

We use ESLint and Prettier for code formatting. Before submitting:

npm run lint      # Check code style
npm run lint:fix  # Auto-fix issues
npm run format    # Format code

Please read our Contributing Guidelines for detailed information about our development process, issue reporting, and pull request procedures.

License

Apache-2.0 License - see LICENSE file for details.

Support

Documentation: JepshSSG Docs
Bug Reports: GitHub Issues
Discussions: GitHub Discussions
Feature Requests: GitHub Issues

⭐ Star us on GitHub if you find JepshSSG helpful!

Top categories

tailwind daisyui admin template popup mdsvex portfolio blog form ecommerce ui carousel auth dark seo image routing