vue-static

A minimal full-stack .NET 10.0 + Vue Vite project template optimized for AI assisted development that combines the power of ServiceStack with Vue Vite static site generation and Vue 3. It provides a production-ready foundation for building scalable web applications with integrated authentication, database management, and background job processing.

Browse source code, view live demo vue-static.web-templates.io and install with:

Quick Start

npx create-net vue-static MyProject

Jumpstart with Copilot

Instantly scaffold a new App with this template using GitHub Copilot, just describe the features you want and watch Copilot build it!

Getting Started

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

cd MyProject
dotnet watch

Architecture

Hybrid Development Approach

Development Mode:

ASP.NET Core proxies requests to Vite dev server (running on port 5173)
Hot Module Replacement (HMR) support for instant UI updates
WebSocket proxying for Vite HMR functionality

Production Mode:

Vite Vue app is statically exported to /dist
Static files served directly from ASP.NET Core's /wwwroot
No separate Node.js server required in production

Core Technologies

Frontend

Vue 3 - A JavaScript library for building user interfaces
Vite 7 - Next Generation Frontend Tooling
Tailwind CSS v4 - CSS-first configuration with @tailwindcss/vite plugin
TypeScript 5 - JavaScript with syntax for types
Vitest - Modern testing framework
ServiceStack Vue Components - Pre-built UI components

.NET Frontend (Integrated + Optional)

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

Backend (.NET 10.0)

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 - Upgrade to PostgreSQL/SQL Server/MySQL

Major Features

1. Authentication & Authorization

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

2. 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

3. Background Jobs

BackgroundsJobFeature for async task processing
Command pattern for job execution
Email sending via background jobs
Recurring job scheduling support
Uses monthly rolling Sqlite databases by default - Upgrade to PostgreSQL/SQL Server/MySQL

4. Developer Experience

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

5. Production Features

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 Structure

MyApp/                         # .NET Backend (hosts both .NET and Vite Vue
├── 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/                  # Vue Frontend
├── src/
│   ├── lib/
│   │   ├── dtos.ts            # Auto-generated from C# (via `npm run dtos`)
│   │   ├── gateway.ts         # ServiceStack JsonServiceClient
│   │   └── utils.ts           # Utility functions
│   ├── components/            # Vue components
│   └── styles/                # Tailwind CSS
└── vite.config.ts             # Vite config for dev mode

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 Workflow

1. Start Development

dotnet watch

This automatically starts both .NET and Vite dev servers.

2. Generate TypeScript DTOs

After modifying C# service models, regenerate TypeScript dtos.ts in MyApp or MyApp.Client with:

npm run dtos

3. Database Migrations

OrmLite and Entity Framework:

npm run migrate

OrmLite (for application data):

Create migration classes in MyApp/Migrations/ following the pattern in Migration1000.cs.

4. Testing

Frontend:

cd MyApp.Client
npm run test        # Run tests in watch mode
npm run test:ui     # Run tests with UI
npm run test:run    # Run tests once

Configuration

Key Configuration Files

MyApp/appsettings.json - Application configuration
MyApp.Client/next.config.mjs - Next.js configuration
MyApp.Client/styles/index.css - Tailwind CSS configuration
config/deploy.yml - Kamal deployment settings

App Settings

Configure in appsettings.json or environment:

{
  "ConnectionStrings": {
    "DefaultConnection": "DataSource=App_Data/app.db;Cache=Shared"
  },
  "SmtpConfig": {
    "Host": "smtp.example.com",
    "Port": 587,
    "FromEmail": "noreply@example.com",
    "FromName": "MyApp"
  },
  "AppConfig": {
    "BaseUrl": "https://myapp.example.com"
  }
}

App Settings Secrets

Instead of polluting each GitHub Reposity with multiple App-specific GitHub Action Secrets, you can save all your secrets in a single APPSETTINGS_PATCH GitHub Action Secret to patch appsettings.json with environment-specific configuration using JSON Patch. E.g:

[
    {
        "op":"replace",
        "path":"/ConnectionStrings/DefaultConnection",
        "value":"Server=service-postgres;Port=5432;User Id=dbuser;Password=dbpass;Database=dbname;Pooling=true;"
    },
    { "op":"add", "path":"/SmtpConfig", "value":{
        "UserName": "SmptUser",
        "Password": "SmptPass",
        "Host": "email-smtp.us-east-1.amazonaws.com",
        "Port": 587,
        "From": "noreply@example.org",
        "FromName": "MyApp",
        "Bcc": "copy@example.org"
      } 
    },
    { "op":"add", "path":"/Admins", "value": ["admin1@email.com","admin2@email.com"] },
    { "op":"add", "path":"/CorsFeature/allowOriginWhitelist/-", "value":"https://servicestack.net" }
]

SMTP Email

Enable email sending by uncommenting in Program.cs:

services.AddSingleton<IEmailSender<ApplicationUser>, EmailSender>();

Upgrading to Enterprise Database

To switch from SQLite to PostgreSQL/SQL Server/MySQL:

Install preferred RDBMS (ef-postgres, ef-mysql, ef-sqlserver), e.g:

npx add-in ef-postgres

Install db-identity to use RDBMS DatabaseJobsFeature for background jobs and DbRequestLogger for Request Logs:

npx add-in db-identity

AutoQuery CRUD Dev Workflow

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

Cheat Sheet

Create a new Table

Create a new Table use init <Table>, e.g:

npx okai init Table

This will generate an empty MyApp.ServiceModel/<Table>.d.ts file along with stub AutoQuery APIs and DB Migration implementations.

Use AI to generate the TypeScript Data Model

Or to get you started quickly you can also use AI to generate the initial TypeScript Data Model with:

npx okai "Table to store Customer Stripe Subscriptions"

This launches a TUI that invokes ServiceStack's okai API to fire multiple concurrent requests to frontier cloud and OSS models to generate the TypeScript Data Models required to implement this feature. You'll be able to browse and choose which of the AI Models you prefer which you can accept by pressing a to (a) accept. These are the data models Claude Sonnet 4.5 generated for this prompt.

Regenerate AutoQuery APIs and DB Migrations

After modifying the Table.d.ts TypeScript Data Model to include the desired fields, re-run the okai tool to re-generate the AutoQuery APIs and DB Migrations:

npx okai Table.d.ts

Command can be run anywhere within your Solution

After you're happy with your Data Model you can run DB Migrations to run the DB Migration and create your RDBMS Table:

npm run migrate

Making changes after first migration

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:

npm run rerun:last

Removing a Data Model and all generated code

If you changed your mind and want to get rid of the RDBMS Table you can revert the last migration:

npm run revert:last

Which will drop the table and then you can get rid of the AutoQuery APIs, DB Migrations and TypeScript Data model with:

npx okai rm Transaction.d.ts

Deployment

Docker + Kamal

This project includes GitHub Actions for CI/CD with automatic Docker image builds and production deployment with Kamal. The /config/deploy.yml configuration is designed to be reusable across projects—it dynamically derives service names, image paths, and volume mounts from environment variables, so you only need to configure your server's IP and hostname using GitHub Action secrets.

GitHub Action Secrets

*Required - App Specific:

The only secret needed to be configured per Repository.

Variable	Example	Description
`KAMAL_DEPLOY_HOST`	`example.org`	Hostname used for SSL certificate and Kamal proxy

Required (Organization Secrets):

Other Required variables can be globally configured in your GitHub Organization or User secrets which will enable deploying all your Repositories to the same server.

Variable	Example	Description
`KAMAL_DEPLOY_IP`	`100.100.100.100`	IP address of the server to deploy to
`SSH_PRIVATE_KEY`	`ssh-rsa ...`	SSH private key to access the server
`LETSENCRYPT_EMAIL`	`me@example.org`	Email for Let's Encrypt SSL certificate

Optional:

Variable	Example	Description
`SERVICESTACK_LICENSE`	`...`	ServiceStack license key

Inferred (from GitHub Action context):

These are inferred from the GitHub Action context and don't need to be configured.

Variable	Source	Description
`GITHUB_REPOSITORY`	`${{ github.repository }}`	e.g. `acme/example.org` - used for service name and image
`KAMAL_REGISTRY_USERNAME`	`${{ github.actor }}`	GitHub username for container registry
`KAMAL_REGISTRY_PASSWORD`	`${{ secrets.GITHUB_TOKEN }}`	GitHub token for container registry auth

Features

Docker containerization with optimized .NET images
SSL auto-certification via Let's Encrypt
GitHub Container Registry integration
Volume persistence for App_Data including any SQLite database

AI-Assisted Development with CLAUDE.md

As part of our objectives of improving developer experience and embracing modern AI-assisted development workflows - all new .NET SPA templates include a comprehensive AGENTS.md file designed to optimize AI-assisted development workflows.

What is CLAUDE.md?

CLAUDE.md and AGENTS.md onboards Claude (and other AI assistants) to your codebase by using a structured documentation file that provides it with complete context about your project's architecture, conventions, and technology choices. This enables more accurate code generation, better suggestions, and faster problem-solving.

What's Included

Each template's AGENTS.md contains:

Project Architecture Overview - Technology stack, design patterns, and key architectural decisions
Project Structure - Gives Claude a map of the codebase
ServiceStack Conventions - DTO patterns, Service implementation, AutoQuery, Authentication, and Validation
API Integration - TypeScript DTO generation, API client usage, component patterns, and form handling
Database Patterns - OrmLite setup, migrations, and data access patterns
Common Development Tasks - Step-by-step guides for adding APIs, implementing features, and extending functionality
Testing & Deployment - Test patterns and deployment workflows

Extending with Project-Specific Details

The existing CLAUDE.md serves as a solid foundation, but for best results, you should extend it with project-specific details like the purpose of the project, key parts and features of the project and any unique conventions you've adopted.

Benefits

Faster Onboarding - New developers (and AI assistants) understand project conventions immediately
Consistent Code Generation - AI tools generate code following your project's patterns
Better Context - AI assistants can reference specific ServiceStack patterns and conventions
Reduced Errors - Clear documentation of framework-specific conventions
Living Documentation - Keep it updated as your project evolves

How to Use

Claude Code and most AI Assistants already support automatically referencing CLAUDE.md and AGENTS.md files, for others you can just include it in your prompt context when asking for help, e.g:

Using my project's AGENTS.md, can you help me add a new AutoQuery API for managing Products?

The AI will understand your App's ServiceStack conventions, React setup, and project structure, providing more accurate and contextual assistance.

Ideal Use Cases

SaaS applications requiring authentication
Admin dashboards with CRUD operations
Content-driven sites with dynamic APIs
Applications needing background job processing
Projects requiring both SSG benefits and API capabilities
Teams wanting type-safety across full stack

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.github/workflows		.github/workflows
.kamal		.kamal
MyApp.Client		MyApp.Client
MyApp.ServiceInterface		MyApp.ServiceInterface
MyApp.ServiceModel		MyApp.ServiceModel
MyApp.Tests		MyApp.Tests
MyApp		MyApp
config		config
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
MyApp.slnx		MyApp.slnx
README.md		README.md
load-env.sh		load-env.sh

NetCoreTemplates/vue-static

Folders and files

Latest commit

History

Repository files navigation