Create Webapp

Create Webapp

Scaffold a runnable app from the public template. Read first: ~/.cursor/skills/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:

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

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:

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:

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

Verify no AppName remains in paths or namespaces:

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

Step 4: Environment

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

docker compose up --build -d

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

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

# 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

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
• Template README in the cloned repo for project-specific notes