Skip to content

Commit e5e6ebc

Browse files
mythzmythz
committed
update react-spa.mdx
1 parent 589e86b commit e5e6ebc

File tree

1 file changed

+260
-23
lines changed

1 file changed

+260
-23
lines changed

‎content/docs/templates/react-spa.mdx‎

Lines changed: 260 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,283 @@
11
---
22
title: React SPA
3-
description: The react-static template for Vibe Coding
3+
description: Full-featured Vite React SPA with .NET 10 Identity Auth Template
44
---
55

6-
# React Static Template
6+
# .NET 10 Full-featured Vite React SPA Identity Auth Template
77

8-
The `react-static` template offers a classic Single Page Application (SPA) experience, optimized for productivity and simplicity. It uses Vite for fast builds and hot module replacement.
8+
import TemplateIntro from '@/components/template-intro';
99

10-
## Features
10+
A modern full-stack .NET 10.0 + Vite React 19 SPA project template that combines the power of ServiceStack with a fast Vite-powered React development experience. It provides a production-ready foundation for building scalable web applications with integrated authentication, database management, and background job processing.
1111

12-
- **Vite**: Lightning-fast dev server and bundler.
13-
- **React SPA**: Client-side routing and rendering.
14-
- **ServiceStack Backend**: Robust .NET 8 API.
15-
- **Tailwind CSS**: Modern styling.
16-
- **TypeScript**: Typed DTOs and components.
12+
<TemplateIntro
13+
image="https://raw.githubusercontent.com/ServiceStack/docs.servicestack.net/main/MyApp/wwwroot/img/pages/react/react-spa.webp"
14+
repo="https://github.com/NetCoreTemplates/react-spa"
15+
demo="http://react-spa.web-templates.io"
16+
name="React SPA Template"
17+
/>
1718

18-
## Ideal Use Cases
19+
## Quick Start
1920

20-
- **Dashboards**: Admin panels and internal tools.
21-
- **SaaS Applications**: Rich, interactive web apps.
22-
- **Mobile Wrappers**: Apps that need to be wrapped for mobile stores.
21+
```bash
22+
npx create-net react-spa MyProject
23+
```
2324

2425
## Getting Started
2526

26-
Create a new project:
27+
Run Server .NET Project (automatically starts both .NET and Vite dev servers):
2728

2829
```bash
29-
npx create-net react-static ProjectName
30+
cd MyProject
31+
dotnet watch
3032
```
3133

32-
### Development
34+
## Architecture
35+
36+
### Hybrid Development Approach
3337

34-
Start the development environment:
38+
**Development Mode:**
39+
40+
![](https://raw.githubusercontent.com/ServiceStack/docs.servicestack.net/refs/heads/main/MyApp/wwwroot/img/pages/react/info/react-static-dev.svg)
41+
42+
- ASP.NET Core proxies requests to Vite dev server (running on port 5173)
43+
- Hot Module Replacement (HMR) support for instant UI updates
44+
- WebSocket proxying for Vite HMR functionality
45+
46+
**Production Mode:**
47+
48+
![](https://raw.githubusercontent.com/ServiceStack/docs.servicestack.net/refs/heads/main/MyApp/wwwroot/img/pages/react/info/react-static-prod.svg)
49+
50+
- React app is built and output to `/dist`
51+
- Static files served directly from ASP.NET Core's `/wwwroot`
52+
- No separate Node.js server required in production
53+
54+
## Core Technologies
55+
56+
### Frontend
57+
- **React 19** - Latest React with concurrent features
58+
- **Vite** - Lightning-fast build tool with HMR
59+
- **React Router 7** - Type-safe client-side routing
60+
- **shadcn/ui** - Beautiful, accessible component library
61+
- **Tailwind CSS 4** - Utility-first styling with dark mode support
62+
- **@servicestack/react** - Pre-built form components and AutoQueryGrid
63+
- **SWR** - React Hooks for data fetching with caching
64+
65+
### .NET Frontend (Integrated + Optional)
66+
- **Razor Pages** - For Identity Auth UI (`/Identity` routes)
67+
68+
### Backend (.NET 10.0)
69+
- **ServiceStack 10.x** - High-performance web services framework
70+
- **ASP.NET Core Identity** - Complete authentication & authorization system
71+
- **Entity Framework Core** - For Identity data management
72+
- **OrmLite** - ServiceStack's fast, lightweight Typed ORM for application data
73+
- **SQLite** - Default database (easily upgradable to PostgreSQL/SQL Server/MySQL)
74+
75+
## Major Features
76+
77+
### 🔐 Identity Authentication
78+
79+
Full ASP.NET Core Identity integration with ServiceStack's Auth features:
80+
81+
- **Credentials Authentication** - Email/password sign-in with secure cookie sessions
82+
- **User Registration** - With email confirmation support
83+
- **Role-based Authorization** - Admin, Manager, Employee roles with `[ValidateHasRole]`
84+
- **Admin Users UI** - Built-in user management at `/admin-ui/users`
85+
- **API Keys** - Generate and manage API keys for programmatic access
86+
87+
### 📊 AutoQuery CRUD
88+
89+
Declarative APIs with automatic query and CRUD functionality:
90+
91+
- **AutoQuery** - Queryable APIs with filtering, sorting, and pagination
92+
- **AutoQueryData** - In-memory queryable data sources
93+
- **Audit History** - Automatic tracking of data changes
94+
- **Bookings Example** - Complete CRUD example with role-based permissions
95+
96+
### 🤖 AI Chat Integration
97+
98+
Built-in AI chat capabilities:
99+
100+
- **ChatFeature** - Multi-provider AI chat API
101+
- **Configurable Providers** - ServiceStack, OpenAI, Anthropic, Google, Groq, and more
102+
- **Chat History** - Persistent storage with `DbChatStore`
103+
- **Admin Analytics** - Chat usage insights at `/admin-ui/chat`
104+
105+
### ⚙️ Background Jobs
106+
107+
Durable job processing with ServiceStack's Background Jobs:
108+
109+
- **Command Pattern** - Type-safe job definitions
110+
- **Email Queue** - SMTP email sending via background jobs
111+
- **Recurring Jobs** - Scheduled task execution
112+
- **Job Dashboard** - Monitor jobs at `/admin-ui/jobs`
113+
114+
### 📝 MDX Blog
115+
116+
Integrated markdown blog with:
117+
118+
- **MDX Support** - Markdown with React components
119+
- **Syntax Highlighting** - Prism.js code blocks
120+
- **vite-plugin-press** - Static content generation
121+
- **Frontmatter** - YAML metadata for posts
122+
- **Typography Styling** - Beautiful prose with `@tailwindcss/typography`
123+
124+
### 🗄️ Database
125+
126+
SQLite with dual ORM support:
127+
128+
- **OrmLite** - ServiceStack's fast micro-ORM for services
129+
- **Entity Framework Core** - For Identity and complex queries
130+
- **Code-First Migrations** - EF Core migrations in `/Migrations`
131+
- **Database Admin UI** - Browse data at `/admin-ui/database`
132+
133+
### 📡 Request Logging
134+
135+
Comprehensive API logging:
136+
137+
- **SqliteRequestLogger** - Persistent request logging to SQLite
138+
- **Request Body Tracking** - Full request payload capture
139+
- **Error Tracking** - Automatic error logging
140+
- **Admin Dashboard** - View logs at `/admin-ui/logging`
141+
142+
### 🏥 Health Checks
143+
144+
Production-ready health monitoring:
145+
146+
- **Health Endpoint** - `/up` for load balancer checks
147+
- **Custom Health Checks** - Extensible health check framework
148+
149+
### 🔄 TypeScript DTOs
150+
151+
Automatic TypeScript type generation:
152+
153+
- **Type-Safe API Calls** - Generated from C# DTOs
154+
- **Sync Command** - `npm run dtos` to update types
155+
- **ServiceStack Client** - Full-featured TypeScript client
156+
157+
### 📖 OpenAPI & Scalar
158+
159+
API documentation with modern tooling:
160+
161+
- **OpenAPI 3.0** - Auto-generated API specifications
162+
- **Scalar API Reference** - Interactive API documentation at `/scalar/v1`
163+
- **Development Mode** - API docs available in development
164+
165+
### 🐳 Docker Deployment
166+
167+
Production-ready containerization:
168+
169+
- **Kamal Deployment** - Zero-downtime deploys with Kamal
170+
- **GitHub Container Registry** - Automatic container builds
171+
- **SSL Auto-Certification** - Let's Encrypt integration
172+
- **Volume Persistence** - `App_Data` volume mounting for SQLite
173+
174+
### 🌙 Dark Mode
175+
176+
Built-in theme support:
177+
178+
- **System Preference** - Respects OS dark mode setting
179+
- **Tailwind CSS 4** - Native dark mode utilities
180+
- **Consistent Theming** - All components support dark mode
181+
182+
## Project Structure
35183

36-
```bash
37-
dotnet watch
38184
```
185+
MyApp/ # Main ASP.NET Core host
186+
├── Configure.*.cs # Modular startup configuration
187+
├── Program.cs # Application entry point
188+
└── wwwroot/ # Static files (production)
39189
40-
This command spins up the ASP.NET Core backend and the Vite dev server.
190+
MyApp.Client/ # Vite React SPA frontend
191+
├── src/
192+
│ ├── pages/ # React Router pages
193+
│ ├── components/ # React components
194+
│ ├── lib/ # Utilities and helpers
195+
│ └── styles/ # Tailwind CSS styles
196+
├── public/ # Static assets
197+
├── dist/ # Build output (production)
198+
└── vite.config.ts # Vite configuration
41199
42-
## Architecture
200+
MyApp.ServiceInterface/ # Service implementations
201+
├── MyServices.cs # Example services
202+
└── Data/ # EF Core DbContext
203+
204+
MyApp.ServiceModel/ # DTOs and service contracts
205+
├── Bookings.cs # AutoQuery CRUD example
206+
└── Hello.cs # Example service contract
207+
208+
MyApp.Tests/ # Integration and unit tests
209+
210+
config/ # Deployment configuration
211+
└── deploy.yml # Kamal deployment settings
212+
213+
.github/ # GitHub Actions workflows
214+
└── workflows/
215+
├── build.yml # CI build and test
216+
├── build-container.yml # Container image build
217+
└── release.yml # Production deployment with Kamal
218+
```
219+
220+
## Example Pages
221+
222+
| Page | Description |
223+
|------|-------------|
224+
| `/` | Home page with getting started guide |
225+
| `/todomvc` | TodoMVC example with ServiceStack APIs |
226+
| `/bookings-auto` | AutoQueryGrid with automatic columns |
227+
| `/bookings-custom` | Custom booking form with validation |
228+
| `/admin` | Protected admin page (requires Admin role) |
229+
| `/profile` | User profile management |
230+
| `/blog` | MDX blog listing |
231+
| `/shadcn-ui` | shadcn/ui component showcase |
232+
| `/about` | About page (MDX) |
233+
| `/privacy` | Privacy policy page (MDX) |
234+
235+
## Admin UIs
236+
237+
Access built-in admin dashboards at:
238+
239+
- `/admin-ui` - Admin dashboard home
240+
- `/admin-ui/users` - User management
241+
- `/admin-ui/database` - Database browser
242+
- `/admin-ui/logging` - Request logs
243+
- `/admin-ui/jobs` - Background jobs
244+
- `/admin-ui/apikeys` - API key management
245+
- `/admin-ui/chat` - AI chat analytics
246+
247+
## Development Workflow
248+
249+
For detailed information on the development workflow, including starting development servers, generating TypeScript DTOs, database migrations, and testing, see:
250+
251+
**[Development Workflow Documentation](/autoquery/dev-workflow)**
252+
253+
## Configuration
254+
255+
For detailed configuration information, including app settings, SMTP email setup, and upgrading to enterprise databases (PostgreSQL/SQL Server/MySQL), see:
256+
257+
**[Configuration Documentation](/configuration)**
258+
259+
## Deployment
260+
261+
For deployment instructions, including Docker + Kamal setup and GitHub Actions configuration, see:
262+
263+
**[Deployment Documentation](/deployment)**
264+
265+
## Ideal Use Cases
266+
267+
- **Dashboards** - Admin panels and internal tools
268+
- **SaaS Applications** - Rich, interactive web apps
269+
- **Mobile Wrappers** - Apps that need to be wrapped for mobile stores
270+
- Full-featured applications requiring authentication
271+
- Projects needing AI chat integration
272+
- Applications with background job processing requirements
273+
- Teams wanting type-safety across full stack
43274

44-
In production, the React app is built into static files and served directly by the ASP.NET Core Kestrel server, simplifying deployment to a single binary or container.
275+
## Learn More
45276

46-
[View Source on GitHub](https://github.com/NetCoreTemplates/react-static)
277+
- [ServiceStack Documentation](https://docs.servicestack.net)
278+
- [Vite Documentation](https://vite.dev)
279+
- [React Documentation](https://react.dev)
280+
- [ServiceStack React Components](https://docs.servicestack.net/react)
281+
- [AutoQuery CRUD](https://docs.servicestack.net/autoquery-crud)
282+
- [Background Jobs](https://docs.servicestack.net/background-jobs)
283+
- [AI Chat API](https://docs.servicestack.net/ai-chat-api)

0 commit comments

Comments
 (0)