.NET 10 Astro Static Identity Auth TemplateCopy Anchor Link

A modern full-stack .NET 10.0 + Astro project template that combines the power of ServiceStack with a statically generated Astro site and interactive React 19 islands. It's ideal for content-first websites like blogs, docs, marketing and product sites: pages are written in Astro, Markdown or MDX and prerendered to HTML that ships no JavaScript by default, while React islands add interactive features powered by ServiceStack APIs and ASP.NET Core Identity Auth. There's no Node.js server to run in production.

astro-static.react-templates.net

Live DemoView Source

Quick StartCopy Anchor Link

npx create-net astro-static MyProject

Getting StartedCopy Anchor Link

Run Server .NET Project (automatically starts both .NET and Astro dev servers):

cd MyProject
dotnet watch

Why Astro?Copy Anchor Link

Astro is a web framework for content-driven websites, and an alternative to Next.js for sites where most pages are content with some interactive features:

• Zero JavaScript by default - pages are rendered to plain HTML and CSS with no JavaScript shipped to the browser unless a component needs it, giving you small pages, fast first loads and great SEO and Core Web Vitals scores without having to optimize for them
• Islands Architecture - interactive React components are hydrated as independent "islands" in an otherwise static page, where you choose when each one loads, e.g. client:load to hydrate immediately, client:visible when scrolled into view or client:only to only render in the browser
• Content-first - Markdown and MDX are first-class pages, whilst Content Collections validate each post's frontmatter against a typed schema, so a missing title or invalid date is a build error instead of a broken page
• Just HTML, plus components - .astro components are HTML templates with a frontmatter script that runs at build time, so there are no React Server Components, "use client" boundaries or server/client component rules to learn, making pages simpler to reason about and easier for AI Agents to get right
• Built on Vite - Astro uses Vite for its dev server, HMR and production builds, and the template uses the Vite+ toolchain for checking, linting, formatting and testing
• Static by default - static output is Astro's default rather than an export mode with features to avoid, so there are no unsupported APIs to work around when serving your site from your .NET App
• Batteries included - official integrations for MDX, RSS feeds, sitemaps and optimized images, with React support provided by the @astrojs/react integration, letting you reuse React components and the @servicestack/react component library
• Vendor Neutral - Astro isn't designed around any hosting platform, and with static output it's deployed as part of your .NET App

ArchitectureCopy Anchor Link

Hybrid Development ApproachCopy Anchor Link

This template uses a hybrid architecture that optimizes for both development speed and production performance:

Development Mode:

• ASP.NET Core proxies requests to the Astro dev server (running on port 5173), which renders pages on request
• Hot Module Replacement (HMR) support: React islands update in place, whilst .astro and Markdown changes reload the page
• WebSocket proxying for Vite HMR functionality

Production Mode:

• Every page is prerendered to static HTML in MyApp.Client/dist, plus rss.xml and the sitemap
• Static files served directly from ASP.NET Core's /wwwroot, with clean URLs (/blog/first-post => blog/first-post.html)
• Any other path returns the prerendered 404.html with a 404 status
• No separate Node.js server required in production

Pages and React IslandsCopy Anchor Link

Pages are .astro, .md or .mdx files in src/pages/, each one a separate HTML document using layouts/Layout.astro for the shared <head>, header and footer. React components without a client:* directive are rendered to static HTML at build time, whilst components with one are hydrated in the browser:

---
import { ShellCommand } from 'react-net-templates'
import { HelloApi } from '../components/islands'
import Layout from '../layouts/Layout.astro'
---

<Layout>
    <!-- Rendered to static HTML at build time, with no JS -->
    <ShellCommand>npx create-net astro-static MyProject</ShellCommand>

    <!-- Interactive React island, hydrated in the browser -->
    <HelloApi client:load value="Astro" />
</Layout>

As each island is a separate React root, interactive components are wrapped with withApp() from lib/app.tsx, which provides the ServiceStack ClientContext for useClient() and loads the App's metadata and signed-in user once per page load, shared by every island on the page:

// components/islands.tsx
import { withApp } from '@/lib/app'
import HelloApiComponent from './HelloApi'

export const HelloApi = withApp(HelloApiComponent)

Markdown & MDX BlogCopy Anchor Link

Blog posts are Markdown/MDX files in src/content/blog/, a content collection whose frontmatter is validated by the schema in content.config.ts:

const blog = defineCollection({
    loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
    schema: ({ image }) =>
        z.object({
            title: z.string(),
            description: z.string(),
            pubDate: z.coerce.date(),
            updatedDate: z.coerce.date().optional(),
            heroImage: z.optional(image()),
        }),
})

Each post is prerendered by pages/blog/[...slug].astro, and listed in the RSS feed at /rss.xml and the generated sitemap.

Static Site RulesCopy Anchor Link

As there's no Node.js server in production:

• Frontmatter code runs at build time - code between the --- fences runs in Node.js when the site is built, not in the browser, so don't fetch per-user data or call authenticated APIs there. Call ServiceStack APIs from React islands with useClient() instead
• Dynamic routes must be known at build time - [param].astro pages must list every value in getStaticPaths(), so data that changes at runtime should be fetched in a React island from a ServiceStack API
• Pages are prerendered signed-out - check ready from appAuth() before rendering user-specific UI, render such components with client:only="react", and protect them with ValidateAuth() from lib/auth.tsx, which waits for the App to be ready before redirecting
• Props passed to hydrated islands must be serializable - e.g. no functions

These rules are also documented in the template's AGENTS.md so AI Agents know which Astro features to use and which to avoid.

Core TechnologiesCopy Anchor Link

Frontend (Astro + React 19)Copy Anchor Link

• Astro - Content-driven web framework, used for static site generation, Markdown/MDX pages and React islands
• Vite+ - Unified toolchain: Vitest, Oxlint and Oxfmt via the vp CLI
• Tailwind CSS 4.x - CSS-first configuration with @tailwindcss/vite plugin
• TypeScript - Type-safe development, type checked by Oxlint (TypeScript Go)
• Vitest - Modern testing framework
• ServiceStack React Components - Pre-built UI components

.NET Frontend (Integrated + Optional)Copy Anchor Link

• Razor Pages - For Identity Auth UI (/Identity routes)

Backend (.NET 10.0)Copy Anchor Link

• ServiceStack 10.x - High-performance web services framework
• ASP.NET Core Identity - Complete authentication & authorization system
• Entity Framework Core - For Identity data management
• OrmLite - ServiceStack's fast, lightweight Typed ORM for application data
• SQLite - Default database (easily upgradable to PostgreSQL/SQL Server/MySQL)

Major FeaturesCopy Anchor Link

1. ContentCopy Anchor Link

• Markdown/MDX blog with typed frontmatter
• RSS feed and sitemap generation
• Pages ship no JavaScript unless they include an interactive island

2. Authentication & AuthorizationCopy Anchor Link

• ASP.NET Core Identity integration with role-based access control
• Custom user sessions with additional claims
• Admin users feature for user management at /admin-ui/users
• Email confirmation workflow (configurable SMTP)
• Razor Pages for Identity UI (/Identity routes)
• Credentials-based authentication

3. AutoQuery CRUD

• Declarative API development with minimal code
• Automatic audit trails (created/modified/deleted tracking)
• Built-in validation and authorization
• Type-safe TypeScript DTOs auto-generated from C# models

4. Background JobsCopy Anchor Link

• BackgroundsJobFeature for async task processing
• Command pattern for job execution
• Email sending via background jobs
• Recurring job scheduling support
• Upgradable to DatabaseJobsFeature for enterprise RDBMS

5. Developer ExperienceCopy Anchor Link

• Admin UI at /admin-ui for App management
• Health checks at /up endpoint
• Modular startup configuration pattern
• Code-first migrations with OrmLite
• Docker support with container publishing
• Kamal deployment configuration included

6. Production FeaturesCopy Anchor Link

• Static asset caching with intelligent cache invalidation
• Clean URLs without .html extensions
• HTTPS redirection and HSTS
• Data protection with persistent keys
• Health monitoring
• Database developer page for EF Core errors

Project StructureCopy Anchor Link

MyApp/                         # .NET Backend (hosts both .NET and Astro)
├── Configure.*.cs             # Modular startup configuration
├── Migrations/                # EF Core Identity migrations + OrmLite app migrations
├── Pages/                     # Identity Auth Razor Pages
└── wwwroot/                   # Production static files (from MyApp.Client/dist)

MyApp.Client/                  # Astro Frontend
├── src/
│   ├── pages/                 # File-based routes
│   │   ├── index.astro        # Home page (/)
│   │   ├── about.astro        # About page (/about)
│   │   ├── profile.astro      # Auth-protected page (/profile)
│   │   ├── forbidden.astro    # 403 page (/forbidden)
│   │   ├── 404.astro          # 404 page
│   │   ├── blog/              # Blog index and a page per post
│   │   └── rss.xml.js         # RSS feed (/rss.xml)
│   ├── layouts/               # Layout.astro (every page), BlogPost.astro (blog posts and about)
│   ├── content/blog/          # Markdown/MDX blog posts
│   ├── content.config.ts      # Content collection schemas
│   ├── components/
│   │   ├── islands.tsx        # React islands: HelloApi, UserMenu, AuthButtons, Profile, DarkModeToggle
│   │   └── *.astro            # Header, Footer, BaseHead, ...
│   ├── lib/
│   │   ├── dtos.ts            # Auto-generated from C# on .NET App startup
│   │   ├── gateway.ts         # ServiceStack JsonServiceClient, init(), useAppReady()
│   │   ├── app.tsx            # withApp() wrapper for React islands
│   │   ├── auth.tsx           # ValidateAuth() and appAuth()
│   │   └── utils.ts           # Utility functions
│   ├── consts.ts              # Site title and description
│   └── styles/global.css      # Tailwind CSS
├── astro.config.mjs           # Astro config: static output, integrations, dev server
└── vite.config.ts             # Vite+ config: lint, fmt, test

MyApp.ServiceModel/            # DTOs & API contracts
├── *.cs                       # C# Request/Response DTOs
├── api.d.ts                   # TypeScript data models Schema
└── *.d.ts                     # TypeScript data models for okai code generation

MyApp.ServiceInterface/        # Service implementations
├── Data/                      # EF Core DbContext and Identity models
└── *Services.cs               # ServiceStack service implementations

MyApp.Tests/                   # .NET tests (NUnit)
├── IntegrationTest.cs         # API integration tests
└── MigrationTasks.cs          # Migration task runner

config/
└── deploy.yml                 # Kamal deployment settings
.github/
└── workflows/
    ├── build.yml              # CI build and test
    ├── build-container.yml    # Container image build
    └── release.yml            # Production deployment with Kamal

Development WorkflowCopy Anchor Link

For detailed information on the development workflow, including starting development servers, generating TypeScript DTOs, database migrations, and testing, see:

Development Workflow Documentation

ConfigurationCopy Anchor Link

For detailed configuration information, including app settings, SMTP email setup, and upgrading to enterprise databases (PostgreSQL/SQL Server/MySQL), see:

Configuration Documentation

DeploymentCopy Anchor Link

For deployment instructions, including Docker + Kamal setup and GitHub Actions configuration, see:

Deployment Documentation

AutoQuery CRUD Dev WorkflowCopy Anchor Link

For Rapid Development simple TypeScript Data Models can be used to generate C# AutoQuery APIs and DB Migrations.

Ideal Use CasesCopy Anchor Link

• Blogs, documentation, marketing and product sites written in Markdown/MDX
• Content-first sites that want fast page loads and SEO without shipping a JavaScript framework on every page
• Teams preferring HTML-first pages and plain React components over Next.js and React Server Components
• Sites adding interactive features, authentication and APIs to otherwise static content

Learn MoreCopy Anchor Link

• Astro Documentation
• Astro Islands
• ServiceStack Documentation
• AutoQuery CRUD
• ServiceStack Auth