rasengan-config

name	rasengan-config
description	Project configuration and rendering mode patterns for Rasengan.js. Covers rasengan.config.js, AppConfig interface, SSR/SSG/SPA modes, CLI commands, build output, Vite overrides, TypeScript setup, environment variables, module aliases, and styling (CSS Modules, Tailwind, preprocessors). Use when configuring a Rasengan.js project or switching rendering strategies.
license	MIT
metadata	{"author":"dilane3","framework":"rasengan","version":"2.0.0"}

Rasengan.js Configuration Patterns

When to Activate

• Creating or editing rasengan.config.js
• Switching between SSR, SSG, or SPA rendering modes
• Configuring Vite plugins or overrides
• Setting up TypeScript, environment variables, or module aliases
• Choosing a styling approach (CSS Modules, Tailwind, Sass, Less, Stylus)
• Running CLI commands for dev, build, or deploy

AppConfig Interface

interface AppConfig {
  ssr?: boolean; // default: true
  prerender?: boolean | { routes: string[] }; // SSG mode
  sageMode?: { reactCompiler?: boolean | { compilationMode: 'annotation' } };
  server?: { development?: { port?: number; open?: boolean } };
  vite?: ViteConfig; // partial Vite overrides
  redirects?: () => Promise<Redirect[]>; // static redirect rules
}

Rendering Modes

Mode	Config	When to Use
SSR	ssr: true (default)	Apps needing SEO, fast initial load, dynamic content
SPA	ssr: false	Dashboards, admin panels, authenticated apps
SSG	prerender: true	Content sites: docs, blogs, marketing pages

Sage Mode (React Compiler)

// Auto-memoize all components (requires React Compiler Babel plugin)
sageMode: {
  reactCompiler: true;
}

// Only memoize components with "use memo" directive
sageMode: {
  reactCompiler: {
    compilationMode: 'annotation';
  }
}

CLI Commands

rasengan dev          # Start dev server on port 5320
rasengan build        # Build for production
rasengan-serve ./dist # Serve production build
npx create-rasengan@latest  # Scaffold a new project

Build Output

dist/
  client/        # Client bundle + manifest.json
    assets/      # JS, CSS, config.json
    .vite/       # Vite manifest
  server/        # SSR server bundle
static/          # Pre-rendered HTML (SSG)

Vite Config Overrides

export default defineConfig({
  vite: {
    plugins: [mdx()],
    resolve: {
      alias: { '@': '/src' },
    },
  },
});

Styling

Approach	Config
CSS Modules	Built-in (.module.css files work out of the box)
Tailwind CSS	Install tailwindcss, add to Vite plugins
Preprocessors	Sass (.scss), Less (.less), Stylus (.styl) via Vite

TypeScript & Module Aliases

// rasengan.config.js
export default defineConfig({
  vite: {
    resolve: {
      alias: { '@': '/src' },
    },
  },
});

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": { "@/*": ["src/*"] }
  }
}

Environment Variables

• Prefix with RASENGAN_ for client-side exposure
• Access via import.meta.env.RASENGAN_*

Rules

• Use ssr: true by default — disable only for fully client-rendered SPAs
• Use prerender: true for static content sites (docs, blogs, marketing)
• Use prerender: { routes: [...] } to specify exact routes for partial SSG
• Enable sageMode.reactCompiler to reduce re-renders (requires React Compiler plugin)
• Set server.development.open: true to auto-open browser on dev start
• Pass partial Vite config — it deep-merges with Rasengan's defaults
• redirects is async, evaluated at build time — for static redirect rules
• Styling: CSS Modules work out of the box; Tailwind requires Vite plugin config
• Use RASENGAN_ prefix for env vars that should be available client-side
• All Rasengan projects require "type": "module" in package.json