Skip to content

Commit 589e86b

Browse files
mythzmythz
committed
update nextjs.mdx
1 parent 83c5cb9 commit 589e86b

File tree

1 file changed

+212
-25
lines changed

1 file changed

+212
-25
lines changed

‎content/docs/templates/nextjs.mdx‎

Lines changed: 212 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,236 @@
11
---
22
title: Next.js App
3-
description: The next-static template for Vibe Coding
3+
description: Full-featured Next.js Static Export Identity Auth Template
44
---
55

6-
# Next.js Static Template
6+
# .NET 10 Full-featured Next.js Static Export Identity Auth Template
77

8-
The `next-static` template is designed for building high-performance, static websites using Next.js and ServiceStack. It combines the SEO benefits of Static Site Generation (SSG) with the dynamic capabilities of a .NET backend.
8+
import TemplateIntro from '@/components/template-intro';
99

10-
## Features
10+
A modern full-stack .NET 10.0 + Next.js 16 project template that combines the power of ServiceStack with Next.js 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-
- **Next.js SSG**: Pre-render pages at build time for blazing fast load speeds.
13-
- **ServiceStack Backend**: Full .NET 8 Web API with AutoQuery, Auth, and more.
14-
- **Tailwind CSS**: Rapid styling with utility classes.
15-
- **TypeScript**: End-to-end type safety.
16-
- **Docker Support**: Ready for deployment with Docker and Kamal.
12+
<TemplateIntro
13+
image="https://raw.githubusercontent.com/ServiceStack/docs.servicestack.net/main/MyApp/wwwroot/img/pages/react/nextjs-static.webp"
14+
repo="https://github.com/NetCoreTemplates/nextjs"
15+
demo="https://nextjs.react-templates.net"
16+
name="Next.js Static Export Template"
17+
/>
1718

18-
## Project Structure
19-
20-
The project is organized into a clean monorepo structure:
19+
## Quick Start
2120

22-
- `MyApp/`: The ASP.NET Core backend.
23-
- `MyApp.Client/`: The Next.js frontend application.
24-
- `MyApp.ServiceModel/`: Shared DTOs.
25-
- `MyApp.ServiceInterface/`: Service implementations.
21+
```bash
22+
npx create-net nextjs MyProject
23+
```
2624

2725
## Getting Started
2826

29-
To create a new project with this template:
27+
Run Server .NET Project (automatically starts both .NET and Next.js dev servers):
3028

3129
```bash
32-
npx create-net next-static ProjectName
30+
cd MyProject
31+
dotnet watch
3332
```
3433

35-
### Development
34+
## Architecture
35+
36+
### Hybrid Development Approach
37+
38+
This template uses a hybrid architecture that differs between development and production environments:
39+
40+
**Development Mode:**
41+
42+
![](https://raw.githubusercontent.com/ServiceStack/docs.servicestack.net/refs/heads/main/MyApp/wwwroot/img/pages/react/info/next-static-dev.svg)
43+
44+
- ASP.NET Core proxies requests to Next.js dev server (running on port 3000)
45+
- Hot Module Replacement (HMR) support for instant UI updates
46+
- WebSocket proxying for Next.js HMR functionality
47+
- Automatic startup of Next.js dev server in `dotnet watch`
48+
49+
**Production Mode:**
50+
51+
![](https://raw.githubusercontent.com/ServiceStack/docs.servicestack.net/refs/heads/main/MyApp/wwwroot/img/pages/react/info/next-static-prod.svg)
52+
53+
- Next.js app is statically exported to `/dist`
54+
- Static files served directly from ASP.NET Core's `/wwwroot`
55+
- No separate Node.js server required in production
56+
- Single container deployment with all static assets
57+
58+
## Core Technologies
59+
60+
### Frontend (Next.js 16 + React 19)
61+
- **Next.js** with static export capability
62+
- **Tailwind CSS 4.x** - Utility-first styling with dark mode support
63+
- **TypeScript** - Type-safe development
64+
- **Vitest** - Modern testing framework
65+
- **shadcn/ui** - Beautiful, accessible component library
66+
- **ServiceStack React Components** - Pre-built UI components
67+
- **SWR** - React Hooks for data fetching with caching
68+
69+
### Backend (.NET 10.0)
70+
- **ServiceStack 10.x** - High-performance web services framework
71+
- **ASP.NET Core Identity Auth** - Complete authentication & authorization system
72+
- **Entity Framework Core** - For Identity Auth data management
73+
- **OrmLite** - ServiceStack's fast, lightweight Typed ORM
74+
- **SQLite** - Default database (easily upgradable to PostgreSQL/SQL Server/MySQL)
75+
76+
## Major Features
77+
78+
### 1. Identity Authentication
79+
- ASP.NET Core Identity integration with role-based access control
80+
- Credentials-based authentication with secure cookie sessions
81+
- User registration with email confirmation support
82+
- Admin users feature for user management at `/admin-ui/users`
83+
- API Keys for programmatic access
84+
- Custom user sessions with additional claims
85+
86+
### 2. AutoQuery CRUD
87+
- Declarative API development with minimal code
88+
- Complete Auth-protected CRUD operations (see Bookings example at `/bookings-auto`)
89+
- Automatic audit trails (created/modified/deleted tracking)
90+
- Built-in validation and authorization
91+
- Type-safe TypeScript DTOs auto-generated from C# models
92+
- AutoQueryGrid component for rapid data grids
93+
94+
### 3. AI Chat Integration
95+
- Built-in ChatFeature with multi-provider support
96+
- Configurable providers: ServiceStack, OpenAI, Anthropic, Google, Groq, and more
97+
- Persistent chat history with `DbChatStore`
98+
- Admin analytics at `/admin-ui/chat`
99+
100+
### 4. Background Jobs
101+
- `BackgroundsJobFeature` for async task processing
102+
- Command pattern for job execution
103+
- Email sending via background jobs
104+
- Recurring job scheduling support
105+
- Job dashboard at `/admin-ui/jobs`
106+
- Upgradable to `DatabaseJobsFeature` for enterprise RDBMS
107+
108+
### 5. MDX Blog
109+
- Integrated markdown blog with MDX support
110+
- Markdown with React components
111+
- Syntax highlighting with Prism.js
112+
- Static generation - pre-rendered at build time
113+
- YAML frontmatter metadata
114+
- Custom remark plugin for YouTube embeds
115+
- Beautiful typography with `@tailwindcss/typography`
116+
117+
### 6. Developer Experience
118+
- **Admin UI** at `/admin-ui` for App management
119+
- **Health checks** at `/up` endpoint
120+
- **Modular startup** configuration pattern
121+
- **Code-first migrations** with EF Core
122+
- **Request logging** with SqliteRequestLogger
123+
- **OpenAPI 3.0** with Scalar API documentation at `/scalar/v1`
124+
- **Docker support** with container publishing
125+
- **Kamal deployment** configuration included
126+
127+
### 7. Production Features
128+
- Static asset serving from ASP.NET Core
129+
- Clean URLs without `.html` extensions
130+
- HTTPS redirection and HSTS
131+
- Data protection with persistent keys
132+
- Health monitoring
133+
- Database admin UI at `/admin-ui/database`
134+
- Dark mode support with system preference detection
36135

37-
Run the following command to start both the backend and frontend in development mode:
136+
## Project Structure
38137

39-
```bash
40-
dotnet watch
41138
```
139+
MyApp/ # Main ASP.NET Core host
140+
├── Configure.*.cs # Modular startup configuration
141+
├── Program.cs # Application entry point
142+
└── wwwroot/ # Static files (production)
143+
144+
MyApp.Client/ # Next.js frontend application
145+
├── app/ # Next.js App Router pages
146+
├── components/ # React components
147+
├── lib/ # Utilities and helpers
148+
├── public/ # Static assets
149+
├── dist/ # Build output (production)
150+
└── styles/ # Tailwind CSS styles
151+
152+
MyApp.ServiceInterface/ # Service implementations
153+
├── MyServices.cs # Example services
154+
└── Data/ # EF Core DbContext
155+
156+
MyApp.ServiceModel/ # DTOs and service contracts
157+
├── Bookings.cs # AutoQuery CRUD example
158+
└── Hello.cs # Example service contract
159+
160+
MyApp.Tests/ # Integration and unit tests
161+
162+
config/ # Deployment configuration
163+
└── deploy.yml # Kamal deployment settings
164+
165+
.github/ # GitHub Actions workflows
166+
└── workflows/
167+
├── build.yml # CI build and test
168+
├── build-container.yml # Container image build
169+
└── release.yml # Production deployment with Kamal
170+
```
171+
172+
## Example Pages
173+
174+
| Page | Description |
175+
|------|-------------|
176+
| `/` | Home page with getting started guide |
177+
| `/todomvc` | TodoMVC example with ServiceStack APIs |
178+
| `/bookings-auto` | AutoQueryGrid with automatic columns |
179+
| `/bookings-custom` | Custom booking form with validation |
180+
| `/admin` | Protected admin page (requires Admin role) |
181+
| `/profile` | User profile management |
182+
| `/posts` | MDX blog listing |
183+
| `/shadcn-ui` | shadcn/ui component showcase |
184+
| `/about` | About page (MDX) |
185+
| `/features` | Template features overview (MDX) |
186+
| `/privacy` | Privacy policy page (MDX) |
187+
188+
## Admin UIs
42189

43-
This will launch the .NET API and the Next.js dev server, with proxying configured automatically.
190+
Access built-in admin dashboards at:
191+
192+
- `/admin-ui` - Admin dashboard home
193+
- `/admin-ui/users` - User management
194+
- `/admin-ui/database` - Database browser
195+
- `/admin-ui/logging` - Request logs
196+
- `/admin-ui/jobs` - Background jobs
197+
- `/admin-ui/apikeys` - API key management
198+
- `/admin-ui/chat` - AI chat analytics
199+
200+
## Development Workflow
201+
202+
For detailed information on the development workflow, including starting development servers, generating TypeScript DTOs, database migrations, and testing, see:
203+
204+
**[Development Workflow Documentation](/autoquery/dev-workflow)**
205+
206+
## Configuration
207+
208+
For detailed configuration information, including app settings, SMTP email setup, AI chat providers, and upgrading to enterprise databases (PostgreSQL/SQL Server/MySQL), see:
209+
210+
**[Configuration Documentation](/configuration)**
44211

45212
## Deployment
46213

47-
The template includes GitHub Actions for building and deploying your application using Kamal. It produces a single Docker image containing both the .NET backend and the static frontend assets.
214+
For deployment instructions, including Docker + Kamal setup and GitHub Actions configuration, see:
215+
216+
**[Deployment Documentation](/deployment)**
217+
218+
## Ideal Use Cases
219+
220+
- SaaS applications requiring authentication
221+
- Admin dashboards with CRUD operations
222+
- Content-driven sites with MDX blog
223+
- Applications needing AI chat integration
224+
- Projects requiring background job processing
225+
- Applications needing both SSG benefits and API capabilities
226+
- Teams wanting type-safety across full stack
227+
- Static sites that need dynamic API backends
228+
229+
## Learn More
48230

49-
[View Source on GitHub](https://github.com/NetCoreTemplates/next-static)
231+
- [ServiceStack Documentation](https://docs.servicestack.net)
232+
- [Next.js Documentation](https://nextjs.org/docs)
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)