Skip to content

Commit 83c5cb9

Browse files
mythzmythz
committed
update react-static
1 parent 5fd9cf1 commit 83c5cb9

File tree

1 file changed

+210
-22
lines changed

1 file changed

+210
-22
lines changed

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

Lines changed: 210 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,234 @@
11
---
22
title: React Static
3-
description: The react-static template for Vibe Coding
3+
description: React + Vite + TypeScript + Tailwind CSS project template with ServiceStack .NET backend
44
---
55

6-
# React Static Template
6+
# .NET 10 React Static 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 + React Vite project template that combines the power of ServiceStack with React Vite static site generation and React 19. 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-static.webp"
14+
repo="https://github.com/NetCoreTemplates/react-static"
15+
demo="http://react-static.web-templates.io"
16+
name="React Static 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-static MyProject
23+
```
2324

2425
## Getting Started
2526

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

2829
```bash
29-
npx create-net react-static ProjectName
30+
cd MyProject
31+
dotnet watch
32+
```
33+
34+
## Architecture
35+
36+
### Hybrid Development Approach
37+
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+
- Vite React app is statically exported 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+
58+
- **React 19** - A JavaScript library for building user interfaces
59+
- **Vite 7** - Next Generation Frontend Tooling
60+
- **Tailwind CSS v4** - CSS-first configuration with `@tailwindcss/vite` plugin
61+
- **TypeScript 5** - JavaScript with syntax for types
62+
- **Vitest** - Modern testing framework
63+
- **ServiceStack React Components** - Pre-built UI components
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+
### 1. Authentication & Authorization
78+
- ASP.NET Core Identity integration with role-based access control
79+
- Custom user sessions with additional claims
80+
- Admin users feature for user management at `/admin-ui/users`
81+
- Email confirmation workflow (configurable SMTP)
82+
- Razor Pages for Identity UI (`/Identity` routes)
83+
- Credentials-based authentication
84+
85+
### [2. AutoQuery CRUD](#autoquery-crud-dev-workflow)
86+
- Declarative API development with minimal code
87+
- Complete Auth-protected CRUD operations (see Bookings example at `/bookings-auto`)
88+
- Automatic audit trails (created/modified/deleted tracking)
89+
- Built-in validation and authorization
90+
- Type-safe TypeScript DTOs auto-generated from C# models
91+
92+
### 3. Background Jobs
93+
- `BackgroundsJobFeature` for async task processing
94+
- Command pattern for job execution
95+
- Email sending via background jobs
96+
- Recurring job scheduling support
97+
- Upgradable to `DatabaseJobsFeature` for enterprise RDBMS
98+
99+
### 4. Developer Experience
100+
- **Admin UI** at `/admin-ui` for App management
101+
- **Health checks** at `/up` endpoint
102+
- **Modular startup** configuration pattern
103+
- **Code-first migrations** with OrmLite
104+
- **Docker support** with container publishing
105+
- **Kamal deployment** configuration included
106+
107+
### 5. Production Features
108+
- Static asset caching with intelligent cache invalidation
109+
- Clean URLs without `.html` extensions
110+
- HTTPS redirection and HSTS
111+
- Data protection with persistent keys
112+
- Health monitoring
113+
- Database developer page for EF Core errors
114+
115+
## Project Structure
116+
117+
```
118+
├── MyApp/ # .NET Backend
119+
│ ├── Configure.*.cs # Modular AppHost configuration
120+
│ ├── Migrations/ # EF Core & OrmLite migrations
121+
│ ├── Program.cs # Application entry point
122+
│ └── wwwroot/ # Static files (production build)
123+
│
124+
├── MyApp.Client/ # React Frontend
125+
│ ├── src/
126+
│ │ ├── components/ # React components
127+
│ │ ├── lib/
128+
│ │ │ ├── dtos.ts # Auto-generated TypeScript DTOs
129+
│ │ │ ├── gateway.ts # ServiceStack API client
130+
│ │ │ └── utils.ts # Utility functions
131+
│ │ ├── styles/
132+
│ │ │ └── index.css # Tailwind CSS styles
133+
│ │ ├── App.tsx # Main App component
134+
│ │ └── main.tsx # Application entry point
135+
│ ├── vite.config.ts # Vite configuration
136+
│ └── package.json # NPM dependencies
137+
│
138+
├── MyApp.ServiceInterface/ # Service implementations
139+
├── MyApp.ServiceModel/ # DTOs & API definitions
140+
├── MyApp.Tests/ # Integration & unit tests
141+
└── config/
142+
│ └── deploy.yml # Kamal deployment configuration
143+
│──.github/ # GitHub Actions workflows
144+
└── workflows/
145+
├── build.yml # CI build and test
146+
├── build-container.yml # Container image build
147+
└── release.yml # Production deployment with Kamal
30148
```
31149

32-
### Development
150+
## Development Workflow
151+
152+
For detailed information on the development workflow, including starting development servers, generating TypeScript DTOs, database migrations, and testing, see:
153+
154+
**[Development Workflow Documentation](/autoquery/dev-workflow)**
155+
156+
## Configuration
157+
158+
For detailed configuration information, including app settings, SMTP email setup, and upgrading to enterprise databases (PostgreSQL/SQL Server/MySQL), see:
159+
160+
**[Configuration Documentation](/configuration)**
161+
162+
## Deployment
33163

34-
Start the development environment:
164+
For deployment instructions, including Docker + Kamal setup and GitHub Actions configuration, see:
165+
166+
**[Deployment Documentation](/deployment)**
167+
168+
## AutoQuery CRUD Dev Workflow
169+
170+
For Rapid Development simple [TypeScript Data Models](https://docs.servicestack.net/autoquery/okai-models) can be used to generate C# AutoQuery APIs and DB Migrations.
171+
172+
### Cheat Sheet
173+
174+
Create a new Table use `init <Table>`, e.g:
35175

36176
```bash
37-
dotnet watch
177+
npx okai init Table
38178
```
39179

40-
This command spins up the ASP.NET Core backend and the Vite dev server.
180+
This will generate an empty `MyApp.ServiceModel/<Table>.d.ts` file along with stub AutoQuery APIs and DB Migration implementations.
41181

42-
## Architecture
182+
#### Regenerate AutoQuery APIs and DB Migrations
183+
184+
After modifying the TypeScript Data Model to include the desired fields, re-run the `okai` tool to re-generate the AutoQuery APIs and DB Migrations:
185+
186+
```bash
187+
npx okai Table.d.ts
188+
```
189+
190+
> Command can be run anywhere within your Solution
191+
192+
After you're happy with your Data Model you can run DB Migrations to run the DB Migration and create your RDBMS Table:
193+
194+
```bash
195+
npm run migrate
196+
```
197+
198+
#### Making changes after first migration
199+
200+
If you want to make further changes to your Data Model, you can re-run the `okai` tool to update the AutoQuery APIs and DB Migrations, then run the `rerun:last` npm script to drop and re-run the last migration:
201+
202+
```bash
203+
npm run rerun:last
204+
```
205+
206+
#### Removing a Data Model and all generated code
207+
208+
If you changed your mind and want to get rid of the RDBMS Table you can revert the last migration:
209+
210+
```bash
211+
npm run revert:last
212+
```
213+
214+
Which will drop the table and then you can get rid of the AutoQuery APIs, DB Migrations and TypeScript Data model with:
215+
216+
```bash
217+
npx okai rm Transaction.d.ts
218+
```
219+
220+
## Ideal Use Cases
221+
222+
- SaaS applications requiring authentication
223+
- Admin dashboards with CRUD operations
224+
- Content-driven sites with dynamic APIs
225+
- Applications needing background job processing
226+
- Projects requiring both SSG benefits and API capabilities
227+
- Teams wanting type-safety across full stack
43228

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.
229+
## Learn More
45230

46-
[View Source on GitHub](https://github.com/NetCoreTemplates/react-static)
231+
- [ServiceStack Documentation](https://docs.servicestack.net)
232+
- [React Documentation](https://react.dev)
233+
- [AutoQuery CRUD](https://docs.servicestack.net/autoquery-crud)
234+
- [ServiceStack Auth](https://docs.servicestack.net/authentication-and-authorization)

0 commit comments

Comments
 (0)