RS-SSG Documentation

Comprehensive guide to using RS-SSG, the React Static Site Generation framework that combines the power of React, Vite, and Tailwind CSS for building lightning-fast, SEO-optimized websites.

Blazing Fast

Leverage Vite's ultra-fast development server and optimized production builds using esbuild.

SEO Optimized

Pre-rendered HTML makes your content immediately available to search engines.

Zero Config

Works out of the box with sensible defaults. No complex configuration needed.

What is RS-SSG?

RS-SSG is a modern static site generator built on React that allows you to create fully optimized, SEO-friendly websites with minimal configuration. It combines the developer experience of React with the performance benefits of static site generation.

Unlike traditional React applications that render on the client side, RS-SSG pre-renders all pages at build time, generating static HTML files that can be served directly from a CDN for maximum performance.

Why Choose RS-SSG?

RS-SSG offers several advantages over traditional React setups and other static site generators:

Superior SEO: Pre-rendered HTML content is immediately crawlable by search engines
Better Performance: Static files can be served from CDNs worldwide, reducing latency
Developer Experience: Enjoy React's component model with the performance of static sites
Zero Configuration: Works out of the box with sensible defaults
Automatic Routing: Array based routing system eliminates configuration overhead

Key Features

Feature	Description
Array-based Routing	Automatic route generation based on array structure in the pages directory
Static Generation	Pre-render pages at build time for optimal performance and SEO
CSS Support	Built-in support for Tailwind CSS, CSS modules, and Sass
Image Optimization	Automatic image optimization and lazy loading
API Routes	Create API endpoints alongside your pages

Getting Started

Installation

RS-SSG can be installed globally via npm, yarn, or pnpm:

# Using npm
npm install -g rs-ssg

# Using yarn
yarn global add rs-ssg

# Using pnpm
pnpm add -g rs-ssg

Verify the installation by running rs-ssg --version in your terminal.

Creating a Project

Create a new RS-SSG project with the following command:

rs-ssg init my-project
cd my-project

This will create a new directory with the following structure:

my-project/
├── dist/
├── node_modules/
├── public/
├── src/
│   ├── components/
│   ├── pages/
│   ├── App.jsx
│   ├── client.jsx
│   ├── index.css
│   └── routes.js
├── index.html
├── package.json
├── pnpm-lock.yaml
├── ssg.config.js
└── .gitignore

Project Structure

RS-SSG follows a specific project structure to make development intuitive:

Folder/File	Purpose
src/pages/	Contains all page components. File names determine routes
src/components/	Reusable React components
src/App.jsx	Main application component with routing logic
src/client.jsx	Client-side hydration entry point
src/routes.js	Route definitions and configuration
src/index.css	Global styles and CSS
public/	Static assets that will be copied directly to output
dist/	Generated static files and build output
index.html	Main HTML template file
ssg.config.js	Configuration file for RS-SSG options

Running Development Server

Start the development server with hot reloading:

# Using npm
npm run dev

# Using yarn
yarn dev

# Using pnpm
pnpm dev

# Or using the global command
rs-ssg dev

The development server will start on http://localhost:3000 by default.

Core Concepts

Array-based Routing

RS-SSG uses an array-based routing system where routes are defined in a central configuration file. Each route object contains the path, component, and entry point for lazy loading.

import { lazy } from "react";

const routes = [
    {
        path: '/',
        component: lazy(() => import('./pages/Home.jsx')),
        entry: "./src/pages/Home.jsx",
    },
    {
        path: '/docs',
        entry: "./src/pages/Docs.jsx",
        component: lazy(() => import('./pages/Docs.jsx')),
    },
    {
        path: '/about',
        component: lazy(() => import('./pages/About.jsx')),
        entry: "./src/pages/About.jsx",
    },
    {
        path: '/blogs/:slug',
        component: lazy(() => import('./pages/BlogItemPage.jsx')),
        entry: "./src/pages/BlogItemPage.jsx",
    },
     {
        path: '/blogs',
        component: lazy(() => import('./pages/Blogs.jsx')),
        entry: "./src/pages/Blogs.jsx",
    },
];

export default routes;

This approach provides explicit control over routing configuration and enables automatic code splitting with lazy loading for better performance.

Creating Pages

Pages are React components that are lazy-loaded and defined in the routes array. Each page component can use static generation to pre-render HTML at build time.

// src/pages/About.jsx
import React from 'react';

function About() {
  return (
    <div>
      <h1>About Us</h1>
      <p>Learn more about our company.</p>
    </div>
  );
}
export default About

Dynamic Routes

Create dynamic routes by using parameter notation in the path property. Use colons to denote dynamic segments like :id or :slug.

Route Configuration

// Route configuration for dynamic blog posts
{
    path: '/blogs/:slug',
    component: lazy(() => import('./pages/BlogItemPage.jsx')),
    entry: "./src/pages/BlogItemPage.jsx",
}

Component Definition

// src/pages/BlogItemPage.jsx
import React from 'react';

export default function BlogPost({ data }) {
  const slug = data?.id
  
  return (
    <article>
      <h1>{data.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

Generate Static Paths

This function runs at build time and tells the framework which dynamic routes to pre-render. It fetches all available blog posts and creates a path for each one, enabling static generation for dynamic routes.

// Generate static paths for all blog posts
export async function getStaticPaths() {
  const posts = await fetchAllPosts();
  
  return {
    paths: posts.map(post => ({
      params: { id: post.id }
    })),
    fallback: false
  };
}

Key Points: The paths array contains all possible parameter combinations. Setting fallback: falsemeans any path not returned here will result in a 404 page.

Fetch Static Props

This function runs at build time for each path returned by getStaticPaths. It receives the route parameters and fetches the specific data needed for that page, returning it as props to the component.

// Fetch data for specific blog post
export async function getStaticProps({ params }) {
  const post = await fetchPostById(params.id);
  
  return {
    props: {
      post
    }
  };
}

How it works: The params object contains the dynamic route values (e.g., params.id). The returned props are passed directly to your React component.

Automatic Lazy Loading

RS-SSG automatically implements code splitting through lazy loading. Each route component is loaded only when needed, reducing the initial bundle size and improving performance.

Components are imported using React.lazy() for automatic code splitting
Routes are loaded on-demand when navigated to
Reduced initial JavaScript bundle size
Faster initial page load times

Tip: The entry property in each route helps the build system understand which files to process for static generation.

Static Generation

RS-SSG pre-renders pages at build time, generating static HTML files that can be served directly from a CDN. This provides several benefits:

Faster page loads with pre-generated HTML content
Better SEO as search engines can crawl content easily
Reduced server load with static file serving
Improved reliability with no server-side rendering needed

You can control static generation behavior using getStaticProps for page data and getStaticPaths for dynamic routes.

Navigation

Coming Soon: Soft Navigation

We're developing an advanced soft navigation system with client-side routing that will be available in the next release.

Currently, RS-SSG supports standard web navigation methods. While we work on our enhanced navigation system, you can use these approaches for moving between pages.

Standard Anchor Tags

Use standard HTML anchor tags for navigation between pages. This triggers a full page reload, which is currently the recommended approach.

// Basic navigation links
<a href="/" className="nav-link">Home</a>
<a href="/about" className="nav-link">About</a>
<a href="/docs" className="nav-link">Documentation</a>

// Navigation with dynamic routes
<a href="/blogs/my-first-post" className="nav-link">
  Read Blog Post
</a>

Programmatic Navigation

For programmatic navigation based on user actions or conditions, use JavaScript's window.location methods.

// Navigate to a new page
function navigateToAbout() {
    window.location.href = '/about';
}

// Replace current page in history
function replaceWithHome() {
    window.location.replace('/');
}

// Navigate with user interaction
function handleFormSubmit(data) {
    // Process form data...
    window.location.href = '/success';
}

// Conditional navigation
function handleLogin(isSuccess) {
    if (isSuccess) {
        window.location.href = '/dashboard';
    } else {
        window.location.href = '/login-error';
    }
}

Current Navigation Best Practices

Use descriptive anchor text for better accessibility and SEO
Ensure all routes defined in your routes array are navigable
Test navigation on all generated static pages
Use relative paths when possible for better portability

Upcoming: Soft Navigation System

Our upcoming soft navigation system will provide:

Client-side routing without full page reloads
Instant page transitions

Programmatic navigation hooks
Link component with prefetching

Example: Navigation Component

Here's how you might structure a navigation component with the current system:

// components/Navigation.jsx
import React from 'react';

const Navigation = () => {
    const navItems = [
        { href: '/', label: 'Home' },
        { href: '/about', label: 'About' },
        { href: '/docs', label: 'Documentation' },
        { href: '/blogs', label: 'Blog' },
    ];

    return (
        <nav className="flex space-x-6">
            {navItems.map((item) => (
                <a aria-label="test"
                    key={item.href}
                    href={item.href}
                    className="text-gray-700 hover:text-blue-600 
                             transition-colors duration-200"
                >
                    {item.label}
                </a>
            ))}
        </nav>
    );
};

export default Navigation;

SEO Optimization

RS-SSG provides built-in SEO optimization features to help your site rank better in search engines. The framework includes a powerful Seo component that makes managing meta tags and social sharing effortless.

The Seo Component

The Seo component from RS-SSG allows you to declaratively define meta tags, Open Graph properties, and other SEO elements directly in your React components.

import { Seo } from "rs-ssg";

function MyPage() {
    return (
        <>
            <Seo>
                <title>Rs SSG Documentation Home Page</title>
                <meta name="description" content="Using RSS Documentation Home page" />
                <meta name="keywords" content="RSS, Documentation, SSG, Static Site Generator" />
                <meta name="author" content="Rasel Mahmud" />
                <meta name="robots" content="index, follow" />
                <meta property="og:title" content="Rs SSG Documentation Home Page" />
                <meta property="og:description" content="Explore the Rs SSG Documentation to learn how to build optimized static sites easily." />
                <meta property="og:type" content="website" />
                <meta property="og:url" content="https://rs-ssg1.web.app/docs" />
                <meta property="og:image" content="https://rs-ssg1.web.app/rs-ssg.svg" />
            </Seo>
            
            <div>
                {/* Your page content */}
            </div>
        </>
    );
}

Key Benefit: The Seo component automatically injects these tags into the document head during static generation, ensuring perfect SEO for each page.

Meta Tags Management

Dynamic title and description tags
Keywords and author meta tags
Robot crawling directives
Custom meta tags support

Open Graph Integration

Social media preview optimization
Custom og:image for each page
Twitter Card support
Automatic URL canonicalization

Complete SEO Feature Set

Meta Tags

Comprehensive meta tag management

Sitemap

Automatic sitemap.xml generation

Performance

Optimized loading speeds

Code Splitting

Automatic lazy loading

SEO Best Practices with RS-SSG

Page-Specific SEO: Use the Seo component in each page to provide unique, relevant meta information

Dynamic Content: For dynamic routes, generate SEO tags based on content data

Image Optimization: Always include og:image for better social media sharing

Structured Data: Add JSON-LD structured data within the Seo component for rich snippets

Example: Dynamic SEO for Blog Posts

Here's how you can use the Seo component with dynamic content:

// pages/BlogPost.jsx
import { Seo } from "rs-ssg";

function BlogPost({ post }) {
    return (
        <>
            <Seo>
                <title>{post.title} | My Blog</title>
                <meta name="description" content={post.excerpt} />
                <meta name="keywords" content={post.tags.join(', ')} />
                <meta name="author" content={post.author} />
                <meta property="og:title" content={post.title} />
                <meta property="og:description" content={post.excerpt} />
                <meta property="og:image" content={post.featuredImage} />
                <meta property="og:url" content={`https://mysite.com/blog/${post.slug}`} />
                <meta property="article:published_time" content={post.publishedAt} />
                <meta property="article:author" content={post.author} />
            </Seo>
            
            <article>
                <h1>{post.title}</h1>
                <p>{post.content}</p>
            </article>
        </>
    );
}

Configuration

Configuration File

RS-SSG can be configured using a ssg.config.js file in your project root:

// ssg.config.js
export default {
  // Output directory for built files
  outputDir: 'dist',
  
  // Port for preview server
  port: 4173,
  
  // dev server port
  devPort: 3000,
  
  siteName: 'My App',
  host: 'localhost',
  siteUrl: 'https://rsraselmahmuddev.vercel.app',
  
  // global SEO settings if page level not provided then this will be used
  seo: {
    title: 'RS Rasel Mahmud Dev - Full Stack Developer',
    description: 'Full Stack Developer specializing in React, Node.js, and modern web technologies. Building scalable web applications and digital solutions.',
    keywords: 'full stack developer, react, nodejs, javascript, web development, frontend, backend, API, database, mongodb, postgresql',
    author: 'RS Rasel Mahmud',
    language: 'en-US',
    locale: 'en_US',

    // Open Graph defaults
    ogType: 'website',
    ogSiteName: 'RS Rasel Mahmud Dev',
    ogImage: '/images/og-default.jpg',
    ogImageAlt: 'RS Rasel Mahmud Dev - Full Stack Developer',
    ogImageWidth: '1200',
    ogImageHeight: '630',

    robots: 'index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1',
    googlebot: 'index, follow',
    revisitAfter: '7 days',
    rating: 'general',
    distribution: 'global',

    enableStructuredData: false,
    
    themeColor: '#000000',
    backgroundColor: '#ffffff',

    icons: {
      favicon: '/favicon.ico',
      icon16: '/favicon-16x16.png',
      icon32: '/favicon-32x32.png',
      appleTouchIcon: '/apple-touch-icon.png',
      androidIcon192: '/android-chrome-192x192.png',
      androidIcon512: '/android-chrome-512x512.png'
    },
    
    security: {
      contentSecurityPolicy: "default-src 'self'; script-src 'self' 'unsafe-inline' 'unsafe-eval' https:; style-src 'self' 'unsafe-inline' https:; img-src 'self' data: https:; font-src 'self' https:; connect-src 'self' https:;",
      xFrameOptions: 'DENY',
      xContentTypeOptions: 'nosniff',
      referrerPolicy: 'strict-origin-when-cross-origin'
    }
  }
};

Configuration Overview

The configuration file supports server settings, SEO metadata, Open Graph tags, security headers, and PWA options. All settings are optional with sensible defaults.

Build Options

Configure how RS-SSG builds your project:

export default {
  outputDir: 'dist',   // Output directory
  // coming soon more config.
};

Coming Soon

Additional build options like minification, source maps, and optimization settings will be available in future releases.

Preview Options

Options for previewing your built site:

export default {
  port: 5000,          // Port for preview server
  open: true,          // Open browser on start
  strict: false        // Strict mode for routing
};

Preview Commands

rs-ssg previewStart preview server with default settings

SEO & Metadata

The SEO configuration provides comprehensive metadata management for search engines and social media platforms:

Search Engine Optimization

• Meta title, description, and keywords
• Robots and Googlebot directives
• Structured data support
• Language and locale settings
• Open Graph tags for Facebook/LinkedIn
• Twitter Card metadata
• Social sharing optimization

Security Headers

Security headers help protect your site from common web vulnerabilities:

Content Security Policy

Controls which resources can be loaded and executed, preventing XSS attacks and unauthorized script execution.

Frame Protection

X-Frame-Options prevents your site from being embedded in iframes, protecting against clickjacking attacks.

Customizing Output Directory

Change the output directory for built files using the outputDir option:

export default {
  outputDir: 'build',  // Custom output directory
  // other config options...
};

Note: Make sure to update your deployment scripts and .gitignore file when changing the output directory.

Limitations

While RS-SSG provides powerful dynamic routing capabilities, there are some current limitations to be aware of when working with dynamic routes.

Current Limitations

•
Multi-level parameters not supported
Complex nested routes like /users/:id/posts/:slug are not currently available.
•
Single-level dynamic routes only
Only one dynamic parameter per route segment is supported (e.g., /blog/:slug).
•
JavaScript only
TypeScript support for dynamic routing is not yet available in the current version.
•
Static generation only
All dynamic routes are pre-generated at build time; runtime route generation is not supported.

These limitations are being actively addressed and will be improved in future releases.

Coming Soon more

We're actively working on adding more security features to RS-SSG to enhance the safety and integrity of your static sites. Here are some of the upcoming features: