# Create Webapp

> Scaffolds a new .NET 10 + Vite React + Postgres web app by cloning the dotnet-vite-webapp-template, renaming AppName, configuring env/JWT, and starting Docker Compose with smoke tests. Use when the user invokes /create-webapp, asks to create a new webapp from the template, or wants a Docker-based .NET React starter.

- Skill: `manifold-works/create-webapp` (Agent Skill)
- Install (CLI): `npx skillmds@latest add manifold-works/create-webapp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/manifold-works/create-webapp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Manifold-Works (https://skillmd.com/u/manifold-works)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/manifold-works/create-webapp

---


# Create Webapp

Scaffold a runnable app from the public template. **Read first:** [`~/.cursor/skills/webapp-shared/reference.md`](../webapp-shared/reference.md).

**Template:** `https://github.com/Manifold-Works/dotnet-vite-webapp-template`

## Prerequisites

- [ ] Docker + Compose plugin available
- [ ] `git` available
- [ ] Target directory writable and empty (or user confirms overwrite)

## Gather inputs

Ask if not provided:

| Input | Default | Notes |
|-------|---------|-------|
| App name | — | PascalCase, e.g. `DemoApp` |
| Target directory | `./{kebab-name}` | e.g. `./demo-app` for `DemoApp` |

## Checklist

Copy and track:

```
Create-webapp progress:
- [ ] 1. Shallow clone template
- [ ] 2. Detach from template remote
- [ ] 3. Rename AppName → app name
- [ ] 4. Configure .env + JWT key
- [ ] 5. Docker Compose up
- [ ] 6. Smoke test API + auth
- [ ] 7. Run backend + frontend tests
- [ ] 8. Report result (pass/fail with logs)
```

## Step 1: Clone

```bash
git clone --depth 1 https://github.com/Manifold-Works/dotnet-vite-webapp-template.git <target-dir>
cd <target-dir>
```

If clone fails (network), ask the user to run the clone in their terminal and resume from step 2.

## Step 2: Detach remote

Keep git history; remove template origin:

```bash
git remote remove origin
```

Only re-init (`rm -rf .git && git init`) if the user explicitly wants a clean history.

## Step 3: Rename

The template uses literal placeholder **`AppName`**. Rename before any other edits:

```bash
chmod +x scripts/rename-app.sh scripts/generate-jwt-key.sh
./scripts/rename-app.sh <NewPascalName>
```

Verify no `AppName` remains in paths or namespaces:

```bash
grep -r "AppName" --include="*.cs" --include="*.csproj" --include="*.json" . 2>/dev/null | head
# Expect zero matches in source (obj/bin ignored)
```

## Step 4: Environment

```bash
cp .env.example .env
./scripts/generate-jwt-key.sh
```

- Paste the generated key into `.env` as `Jwt__SigningKey=...`
- Update `Jwt__Issuer`, `Jwt__Audience`, and `POSTGRES_DB` if rename script did not set them
- Confirm `Cors__Origins=http://localhost:5173`
- Confirm `ASPNETCORE_ENVIRONMENT=Development`

Never commit `.env`.

## Step 5: Start stack

```bash
docker compose up --build -d
```

Wait for services (API may take 30–90s on first build):

```bash
docker compose ps
docker compose logs api --tail 50
```

Development auto-migrates on API startup — no manual migrate needed for first boot.

## Step 6: Smoke tests

```bash
# Health
curl -sf http://localhost:8080/api/health

# Register
curl -sf -X POST http://localhost:8080/api/auth/register \
  -H 'Content-Type: application/json' \
  -d '{"email":"smoke@test.local","password":"Password1!"}'

# Login
curl -sf -X POST http://localhost:8080/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"smoke@test.local","password":"Password1!"}'
# Save accessToken and refreshToken from response

# Me (replace ACCESS_TOKEN)
curl -sf http://localhost:8080/api/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

# Refresh (replace REFRESH_TOKEN)
curl -sf -X POST http://localhost:8080/api/auth/refresh \
  -H 'Content-Type: application/json' \
  -d '{"refreshToken":"REFRESH_TOKEN"}'
```

Optional: open `http://localhost:5173` and confirm login/register UI loads.

## Step 7: Tests

```bash
cd backend && dotnet test
cd ../frontend && npm ci && npm test -- --run
```

If Testcontainers fails in sandbox, run tests on the host or ask the user to run them.

## Step 8: Report

**Success when:** health OK, register/login/refresh/me work, tests pass.

Report to user:

- App directory and renamed solution name
- Dev URLs: web `http://localhost:5173`, api `http://localhost:8080`
- Next steps: `add-feature` for new slices, `dev-webapp` for day-2 DX, `deploy-webapp` for production

On failure: paste relevant `docker compose logs api db web` output and the failing command.

## Do not

- Invent alternate folder layouts — follow the template
- Skip rename — `AppName` must become the user's app name
- Commit `.env` or generated secrets
- Embed app source inside skill directories — clone is the distribution channel

## Additional resources

- Layout, auth, env, ports: [`reference.md`](../webapp-shared/reference.md)
- Template README in the cloned repo for project-specific notes