blumenjs 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# SSR Go + React
+
+A minimal, production-quality SSR engine built with Go and React. The Go server handles HTTP routing and serves as the entry point, while a Node.js service renders React components to HTML.
+
+## Architecture
+
+```
+Browser → Go Server (:3000) → Node SSR (:4000) → React → HTML
+                           ↓
+                    Static JS bundle → Hydration
+```
+
+- **Go Server** — Routing, SSR orchestration, static files
+- **Node SSR Service** — React `renderToString` via HTTP API
+- **React App** — Isomorphic pages (Home, About)
+
+## Quick Start
+
+### Prerequisites
+
+- Go 1.21+
+- Node.js 18+
+- npm or yarn
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Build Client Bundle
+
+```bash
+npm run build:client
+```
+
+### Start Both Servers
+
+Terminal 1 — Node SSR Service:
+```bash
+npm run dev:ssr
+```
+
+Terminal 2 — Go Server:
+```bash
+npm run dev:go
+```
+
+Or use the convenience command (requires `concurrently`):
+```bash
+npm run dev
+```
+
+### Visit the App
+
+Open http://localhost:3000
+
+## Development
+
+### Project Structure
+
+```
+.
+├── go-server/
+│   └── main.go          # Go HTTP server, SSR proxy
+├── node-ssr/
+│   └── server.ts        # Node SSR service (renderToString endpoint)
+├── app/
+│   ├── pages/
+│   │   ├── Home.tsx     # Home page component
+│   │   └── About.tsx    # About page component
+│   └── client/
+│       └── entry.tsx    # Client hydration entry point
+├── templates/
+│   └── index.html       # HTML template (Go html/template)
+├── static/
+│   └── js/
+│       └── bundle.js    # Compiled client bundle (generated)
+├── package.json
+├── tsconfig.json
+└── webpack.config.js
+```
+
+### Request Flow
+
+1. Browser requests `GET /`
+2. Go server prepares SSR request with path, query, params
+3. Go POSTs JSON to Node SSR service at `:4000/render`
+4. Node renders the React page component to HTML string
+5. Go injects HTML + serialized props into template
+6. Browser receives full HTML, client bundle hydrates React
+
+## Production Build
+
+```bash
+npm run build
+npm start
+```
+
+## API
+
+### POST /render (Node SSR)
+
+Request:
+```json
+{
+  "path": "/about",
+  "query": {},
+  "params": {}
+}
+```
+
+Response:
+```json
+{
+  "html": "<div class=\"about-page\">...</div>",
+  "props": { "serverRendered": true, "timestamp": 1234567890 }
+}
+```
+
+## Future Roadmap
+
+- File-based routing
+- API routes
+- CLI tooling
+- Hot reload in development
+- Production build optimization