Skip to content

Commit 0d2a861

Browse files
mythzmythz
committed
Update README.md
1 parent fce78c7 commit 0d2a861

File tree

1 file changed

+229
-10
lines changed

1 file changed

+229
-10
lines changed

‎README.md‎

Lines changed: 229 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,236 @@
1-
# react-spa
1+
# .NET 10 Full-featured Vite React SPA Identity Auth Template
22

3-
.NET 8.0 react-spa Pages Tailwind Website
3+
![](https://github.com/ServiceStack/docs.servicestack.net/blob/main/MyApp/wwwroot/img/pages/react/react-spa.webp)
44

5-
[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/react-spa.png)](http://react-spa.react-templates.net)
5+
> Browse [source code](https://github.com/NetCoreTemplates/react-spa)
66
7-
> Browse [source code](https://github.com/NetCoreTemplates/react-spa), view live demo [react-spa.react-templates.net](http://react-spa.react-templates.net) and install with [dotnet-new](https://docs.servicestack.net/dotnet-new):
7+
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.
88

9-
$ dotnet tool install -g x
9+
## Quick Start
1010

11-
$ x new react-spa ProjectName
11+
```bash
12+
npx create-net react-spa MyProject
13+
```
1214

13-
Alternatively write new project files directly into an empty repository, using the Directory Name as the ProjectName:
15+
## Getting Started
1416

15-
$ git clone https://github.com/<User>/<ProjectName>.git
16-
$ cd <ProjectName>
17-
$ x new react-spa
17+
Run Server .NET Project (automatically starts both .NET and Vite dev servers):
18+
19+
```bash
20+
cd MyProject
21+
dotnet watch
22+
```
23+
24+
## Architecture
25+
26+
### Hybrid Development Approach
27+
28+
**Development Mode:**
29+
30+
![](https://raw.githubusercontent.com/ServiceStack/docs.servicestack.net/refs/heads/main/MyApp/wwwroot/img/pages/react/info/react-static-dev.svg)
31+
32+
- ASP.NET Core proxies requests to Vite dev server (running on port 5173)
33+
- Hot Module Replacement (HMR) support for instant UI updates
34+
- WebSocket proxying for Vite HMR functionality
35+
36+
**Production Mode:**
37+
38+
![](https://raw.githubusercontent.com/ServiceStack/docs.servicestack.net/refs/heads/main/MyApp/wwwroot/img/pages/react/info/react-static-prod.svg)
39+
40+
- React app is built and output to `/dist`
41+
- Static files served directly from ASP.NET Core's `/wwwroot`
42+
- No separate Node.js server required in production
43+
44+
### Project Structure
45+
46+
```
47+
MyApp/ # Main ASP.NET Core host
48+
├── Configure.*.cs # Modular startup configuration
49+
├── Program.cs # Application entry point
50+
└── wwwroot/ # Static files (production)
51+
52+
MyApp.Client/ # Vite React SPA frontend
53+
├── src/
54+
│ ├── pages/ # React Router pages
55+
│ ├── components/ # React components
56+
│ ├── lib/ # Utilities and helpers
57+
│ └── styles/ # Tailwind CSS styles
58+
├── public/ # Static assets
59+
├── dist/ # Build output (production)
60+
└── vite.config.ts # Vite configuration
61+
62+
MyApp.ServiceInterface/ # Service implementations
63+
├── MyServices.cs # Example services
64+
└── Data/ # EF Core DbContext
65+
66+
MyApp.ServiceModel/ # DTOs and service contracts
67+
├── Bookings.cs # AutoQuery CRUD example
68+
└── Hello.cs # Example service contract
69+
70+
MyApp.Tests/ # Integration and unit tests
71+
72+
config/ # Deployment configuration
73+
└── deploy.yml # Kamal deployment settings
74+
75+
.github/ # GitHub Actions workflows
76+
└── workflows/
77+
├── build.yml # CI build and test
78+
├── build-container.yml # Container image build
79+
└── release.yml # Production deployment with Kamal
80+
```
81+
82+
## Features
83+
84+
### 🔐 Identity Authentication
85+
86+
Full ASP.NET Core Identity integration with ServiceStack's Auth features:
87+
88+
- **Credentials Authentication** - Email/password sign-in with secure cookie sessions
89+
- **User Registration** - With email confirmation support
90+
- **Role-based Authorization** - Admin, Manager, Employee roles with `[ValidateHasRole]`
91+
- **Admin Users UI** - Built-in user management at `/admin-ui/users`
92+
- **API Keys** - Generate and manage API keys for programmatic access
93+
94+
### 📊 AutoQuery CRUD
95+
96+
Declarative APIs with automatic query and CRUD functionality:
97+
98+
- **AutoQuery** - Queryable APIs with filtering, sorting, and pagination
99+
- **AutoQueryData** - In-memory queryable data sources
100+
- **Audit History** - Automatic tracking of data changes
101+
- **Bookings Example** - Complete CRUD example with role-based permissions
102+
103+
### 🎨 React 19 + shadcn/ui Components
104+
105+
Modern UI built with:
106+
107+
- **React 19** - Latest React with concurrent features
108+
- **Vite** - Lightning-fast build tool with HMR
109+
- **React Router 7** - Type-safe client-side routing
110+
- **shadcn/ui** - Beautiful, accessible component library
111+
- **Tailwind CSS 4** - Utility-first styling with dark mode support
112+
- **@servicestack/react** - Pre-built form components and AutoQueryGrid
113+
- **SWR** - React Hooks for data fetching with caching
114+
115+
### 🤖 AI Chat Integration
116+
117+
Built-in AI chat capabilities:
118+
119+
- **ChatFeature** - Multi-provider AI chat API
120+
- **Configurable Providers** - ServiceStack, OpenAI, Anthropic, Google, Groq, and more
121+
- **Chat History** - Persistent storage with `DbChatStore`
122+
- **Admin Analytics** - Chat usage insights at `/admin-ui/chat`
123+
124+
### ⚙️ Background Jobs
125+
126+
Durable job processing with ServiceStack's Background Jobs:
127+
128+
- **Command Pattern** - Type-safe job definitions
129+
- **Email Queue** - SMTP email sending via background jobs
130+
- **Recurring Jobs** - Scheduled task execution
131+
- **Job Dashboard** - Monitor jobs at `/admin-ui/jobs`
132+
133+
### 📝 MDX Blog
134+
135+
Integrated markdown blog with:
136+
137+
- **MDX Support** - Markdown with React components
138+
- **Syntax Highlighting** - Prism.js code blocks
139+
- **vite-plugin-press** - Static content generation
140+
- **Frontmatter** - YAML metadata for posts
141+
- **Typography Styling** - Beautiful prose with `@tailwindcss/typography`
142+
143+
### 🗄️ Database
144+
145+
SQLite with dual ORM support:
146+
147+
- **OrmLite** - ServiceStack's fast micro-ORM for services
148+
- **Entity Framework Core** - For Identity and complex queries
149+
- **Code-First Migrations** - EF Core migrations in `/Migrations`
150+
- **Database Admin UI** - Browse data at `/admin-ui/database`
151+
152+
### 📡 Request Logging
153+
154+
Comprehensive API logging:
155+
156+
- **SqliteRequestLogger** - Persistent request logging to SQLite
157+
- **Request Body Tracking** - Full request payload capture
158+
- **Error Tracking** - Automatic error logging
159+
- **Admin Dashboard** - View logs at `/admin-ui/logging`
160+
161+
### 🏥 Health Checks
162+
163+
Production-ready health monitoring:
164+
165+
- **Health Endpoint** - `/up` for load balancer checks
166+
- **Custom Health Checks** - Extensible health check framework
167+
168+
### 🔄 TypeScript DTOs
169+
170+
Automatic TypeScript type generation:
171+
172+
- **Type-Safe API Calls** - Generated from C# DTOs
173+
- **Sync Command** - `npm run dtos` to update types
174+
- **ServiceStack Client** - Full-featured TypeScript client
175+
176+
### 📖 OpenAPI & Scalar
177+
178+
API documentation with modern tooling:
179+
180+
- **OpenAPI 3.0** - Auto-generated API specifications
181+
- **Scalar API Reference** - Interactive API documentation at `/scalar/v1`
182+
- **Development Mode** - API docs available in development
183+
184+
### 🐳 Docker Deployment
185+
186+
Production-ready containerization:
187+
188+
- **Kamal Deployment** - Zero-downtime deploys with Kamal
189+
- **GitHub Container Registry** - Automatic container builds
190+
- **SSL Auto-Certification** - Let's Encrypt integration
191+
- **Volume Persistence** - `App_Data` volume mounting for SQLite
192+
193+
### 🌙 Dark Mode
194+
195+
Built-in theme support:
196+
197+
- **System Preference** - Respects OS dark mode setting
198+
- **Tailwind CSS 4** - Native dark mode utilities
199+
- **Consistent Theming** - All components support dark mode
200+
201+
## Example Pages
202+
203+
| Page | Description |
204+
|------|-------------|
205+
| `/` | Home page with getting started guide |
206+
| `/todomvc` | TodoMVC example with ServiceStack APIs |
207+
| `/bookings-auto` | AutoQueryGrid with automatic columns |
208+
| `/bookings-custom` | Custom booking form with validation |
209+
| `/admin` | Protected admin page (requires Admin role) |
210+
| `/profile` | User profile management |
211+
| `/blog` | MDX blog listing |
212+
| `/shadcn-ui` | shadcn/ui component showcase |
213+
| `/about` | About page (MDX) |
214+
| `/privacy` | Privacy policy page (MDX) |
215+
216+
## Admin UIs
217+
218+
Access built-in admin dashboards at:
219+
220+
- `/admin-ui` - Admin dashboard home
221+
- `/admin-ui/users` - User management
222+
- `/admin-ui/database` - Database browser
223+
- `/admin-ui/logging` - Request logs
224+
- `/admin-ui/jobs` - Background jobs
225+
- `/admin-ui/apikeys` - API key management
226+
- `/admin-ui/chat` - AI chat analytics
227+
228+
## Learn More
229+
230+
- [ServiceStack Documentation](https://docs.servicestack.net)
231+
- [Vite Documentation](https://vite.dev)
232+
- [React Documentation](https://react.dev)
233+
- [ServiceStack React Components](https://docs.servicestack.net/react)
234+
- [AutoQuery CRUD](https://docs.servicestack.net/autoquery-crud)
235+
- [Background Jobs](https://docs.servicestack.net/background-jobs)
236+
- [AI Chat API](https://docs.servicestack.net/ai-chat-api)

0 commit comments

Comments
 (0)