docs: rewrite docs from scratch

Author: svedova

README.md

@@ -1,73 +1,231 @@
-> Minimal no-framework template built with Vite and React
+# React Starter Kit
 
-## Features
+> A minimal, flexible React template built with Vite supporting multiple rendering modes
 
-✔️  **Hybrid application:** Choose rendering method (SSG, SSR, SPA) based on routes
+## ✨ Features
 
-✔️  **API support:** Optional file-system routing support for API endpoints
+- 🔄 **Multiple Rendering Modes**: SSR, SSG, and SPA support with route-level control
+- 🚀 **File-based API Routes**: Build serverless APIs with simple file structure
+- 🎯 **Framework-agnostic**: Pure React with Vite - no complex abstractions
+- 🔍 **SEO Ready**: Built-in meta tags and server-side rendering for better SEO
+- 📦 **Universal Deployment**: Compatible with Stormkit, Netlify, Vercel and more
+- ⚡ **Hot Module Replacement**: Instant updates during development
+- 🏷️ **TypeScript First**: Full TypeScript support out of the box
+- 🎨 **Modern Tooling**: Vite for lightning-fast builds and development
 
-✔️  **No framework:** React knowledge is enough to use this template
+## 🚀 Quick Start
 
-✔️  **SEO:** SEO tags included for SSR and SSG
+### Installation
 
-✔️  **Compatible:** Build produces separate folders for client-side, server-side, and API. Highly compatible with hosting providers.
+```bash
+# Clone or use as template
+git clone <repository-url>
+cd react-starter
 
-✔️ &nbsp;**HMR:** Hot module replacement support for all apps (SSR, SSG, SPA, API)
+# Install dependencies
+npm install
+# or
+yarn install
+# or
+pnpm install
+```
 
-✔️ &nbsp;**Typescript:** Built-in TypeScript support
+### Development
 
-## Getting started
+```bash
+npm run dev
+```
 
-This is a starter template for building applications with Vite and React. Click `use this template` and start working right away.
+Visit `http://localhost:5173` to see your app running with HMR enabled.
 
-## Development
+## 📁 Project Structure
 
 ```
-# Using npm
+src/
+├── api/                 # API routes (serverless functions)
+│   └── hello.ts        # Example API endpoint
+├── pages/              # Application pages
+│   ├── home.tsx        # Home page (SPA)
+│   ├── about.tsx       # About page (SPA)
+│   └── ssr.tsx         # SSR example with fetchData
+├── components/         # Reusable components
+├── context.ts          # React context for data sharing
+├── entry-client.tsx    # Client-side entry point
+├── entry-server.tsx    # Server-side entry point
+├── prerender.ts        # SSG route configuration
+└── App.tsx            # Main application component
+```
+
+## 🔧 Build Commands
+
+### Development Server
+
+```bash
 npm run dev
+```
+
+Starts development server with HMR at `http://localhost:5173`
 
-# Using yarn
-yarn dev
+### Single Page Application (SPA)
 
-# Using pnpm
-pnpm run dev
+```bash
+npm run build:spa
 ```
 
-This will spawn an Express server that serves your application. Built-in Hot Module Replacement (HMR) support.
+Builds a traditional SPA. Output: `.stormkit/public/`
 
-## How it works?
+### Server-Side Rendering (SSR)
+
+```bash
+npm run build:ssr
+```
 
-In the local environment, [src/entry-server.tsx](./src/entry-server.tsx) is the entry point for the application. It uses
-`react-router` to understand what page to render. If the route exports a `fetchData` method, the component will be server-side-rendered.
-Otherwise, it will be client-side rendered. Data returned by `fetchData` will be made available to the component by [React Context](./src/context.ts).
+Builds for serverless deployment with SSR. Output: `.stormkit/server/`
+
+### Static Site Generation (SSG)
+
+```bash
+npm run build:spa  # Build SPA first
+npm run build:ssg  # Generate static pages
+```
 
-See [src/pages/ssr.tsx](./src/pages/ssr.tsx) for an example.
+Pre-renders specified routes at build time. Output: `.stormkit/public/`
 
-## Static site generator
+### API Only
+
+```bash
+npm run build:api
+```
+
+Builds only the API functions. Output: `.stormkit/api/`
+
+## 🎯 Rendering Modes
+
+### Single Page Application (Default)
+
+All routes are client-side rendered by default:
+
+```tsx
+// src/pages/home.tsx
+export default function Home() {
+  return <h1>Welcome to Home</h1>;
+}
+```
+
+### Server-Side Rendering
+
+Add a `fetchData` export to enable SSR:
+
+```tsx
+// src/pages/ssr.tsx
+export async function fetchData() {
+  const data = await fetch("https://api.example.com/data");
+  return data.json();
+}
+
+export default function SSRPage({ data }: { data: any }) {
+  return <h1>Server-rendered: {data.title}</h1>;
+}
+```
 
-You can define which routes to prerender by modifying the [src/prerender.ts](./src/prerender.ts) file. During build time, the builder will be make a
-request to each route exported by this file and will take a snapshot of the HTML document.
+### Static Site Generation
 
-## Single page app
+Configure routes to pre-render in `src/prerender.ts`:
+
+```tsx
+// src/prerender.ts
+export default [{ path: "/" }, { path: "/about" }, { path: "/blog/post-1" }];
+```
+
+## 🔌 API Routes
+
+Create API endpoints by adding files to `src/api/`:
+
+```typescript
+// src/api/hello.ts
+export default function handler(request: Request) {
+  return new Response(JSON.stringify({ message: "Hello, World!" }), {
+    headers: { "Content-Type": "application/json" },
+  });
+}
+```
+
+Access at: `http://localhost:5173/api/hello`
+
+### Dynamic API Routes
+
+```typescript
+// src/api/users/[id].ts
+export default function handler(request: Request) {
+  const url = new URL(request.url);
+  const id = url.pathname.split("/").pop();
+
+  return new Response(JSON.stringify({ userId: id }), {
+    headers: { "Content-Type": "application/json" },
+  });
+}
+```
+
+## 🚀 Deployment
+
+### Stormkit
+
+Import this application on Stormkit (either self-hosted or cloud) and simply click deploy. It works with zero-config.
+
+### Static Hosting
+
+```bash
+npm run build:spa
+npm run build:ssg  # Optional: for pre-rendered pages
+```
+
+Deploy the `.stormkit/public` folder.
+
+## 🔧 Configuration
+
+### Vite Configuration
+
+- `vite.config.ts` - Development server
+- `vite.config.ssr.ts` - SSR build
+- `vite.config.spa.ts` - SPA build
+- `vite.config.api.ts` - API build
+
+## 🛠️ Advanced Usage
+
+### Custom Server
+
+```typescript
+// server.ts
+import { handler } from "./.stormkit/server/server.mjs";
+
+const server = express();
+server.use(handler);
+server.listen(3000);
+```
 
-By default, every route is a single-page application.
+## 🤝 Contributing
 
-## API
+1. Fork the repository
+2. Create your feature branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m 'Add amazing feature'`
+4. Push to the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
 
-The [src/api/](./src/api/) directory contains functions that act as API. The path to the file and the file name is used to determine the endpoint.
-The API is comptabile with [Stormkit](https://www.stormkit.io). [Check the docs](https://www.stormkit.io/docs/features/writing-api) for more information.
+## 📚 Resources
 
-If you need to host the API elsewhere, you'll need to change the [vite.config.api.ts](./vite.config.api.ts) file and create a bundle from it. You may
-also need to write an entry point that calls the appropriate function based on the route.
+- [Vite Documentation](https://vitejs.dev/)
+- [React Documentation](https://react.dev/)
+- [Stormkit Documentation](https://stormkit.io/docs)
 
-## Community
+## 🌟 Showcase
 
-Here's a curated list of websites using this framework. Please feel free to add your own:
+Websites built with this template:
 
-| Site name                              | Description                                            |
-| -------------------------------------- | ------------------------------------------------------ |
-| [Stormkit.io](https://www.stormkit.io) | Deploy full stack javascript applications on the cloud |
+| Site                                                     | Description                       | Features Used   |
+| -------------------------------------------------------- | --------------------------------- | --------------- |
+| [Stormkit.io](https://stormkit.io)                       | Deploy full-stack JavaScript apps | SSR, API Routes |
+| [Add your site](https://github.com/your-repo/issues/new) | Submit your project               | -               |
 
-## License
+## 📄 License
 
-MIT
+MIT ©