# Web

> Use for end-to-end web apps — rendering strategy, data fetching, auth, builds, deployment. SPAs, SSR/SSG (Next.js, Nuxt, SvelteKit, Remix, Astro). Not for pure backend APIs → skill backend.

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

---


# Web Application Skill

**Scope: framework-agnostic web concerns. Next.js specifics → `.claude/skills/react-next/SKILL.md`.**

## When to use

- Starting a new web project (greenfield or from spec)
- Adding a significant feature: auth, payments, real-time, i18n, image pipeline
- Migrating rendering strategy (CSR → SSR, pages → app router, etc.)
- Diagnosing performance regressions (LCP, CLS, TTI, bundle size)
- Preparing a web app for production (HTTPS, caching, CSP, monitoring)

---

## Workflow

1. **Classify the project** — Read `docs/specs/product-spec.md` and `.claude/stack-matrix/` to confirm framework, rendering model (CSR / SSR / SSG / ISR), and target environments (browser-only, hybrid, PWA). If none exist, ask the founder interview questions first (see `.claude/agents/core/orchestrator.md`).

2. **Confirm rendering strategy** — Match business requirements to strategy:
   | Requirement | Preferred strategy |
   |---|---|
   | SEO-critical public pages | SSR or SSG |
   | Highly dynamic per-user UI | CSR with API |
   | Mostly static, rare updates | SSG + ISR |
   | Mixed | Hybrid (e.g. Next.js App Router) |

3. **Scaffold project structure** — Use the framework CLI (`next`, `nuxt`, `create-svelte`, `astro`) with TypeScript enabled. Record the chosen structure in `docs/architecture/overview.md`.

4. **Wire data layer** — Choose one pattern and be consistent:
   - Server components / loaders → fetch on the server, pass serialized data down
   - API routes / BFF → client calls `/api/*`, server owns data access
   - React Query / SWR → client cache + revalidation
   Validate schema at the boundary with Zod or Valibot.

5. **Implement auth** — Follow `.claude/skills/security/SKILL.md`. Prefer an established library (NextAuth/Auth.js, Lucia, Clerk) over hand-rolled sessions. Enforce HTTPS-only cookies with `SameSite=Strict`.

6. **Build UI** — Component-first. Create atomic components before page-level compositions. Enforce WCAG 2.1 AA: semantic HTML, keyboard navigation, color contrast ≥ 4.5:1. Reference `.claude/checklists/accessibility.md`.

7. **Optimize bundle** — After first working build:
   - Run `next build --analyze` (or equivalent) and identify chunks > 100 KB.
   - Code-split dynamic imports (`next/dynamic`, `React.lazy`).
   - Serve images via optimized pipeline (Next Image, Astro `<Image>`, etc.) with `loading="lazy"` and explicit width/height.

8. **Configure environment & secrets** — `.env.local` for dev; never commit secrets. Use typed env validation (`@t3-oss/env-nextjs` or equivalent). Document all required variables in `.env.example`.

9. **Write tests** — Unit: component logic with Vitest. Integration: user flows with Playwright or Cypress. Target ≥ 80% branch coverage on critical paths. Reference `.claude/checklists/qa.md`.

10. **Run pre-deploy checklist** — See `.claude/checklists/production.md`. Confirm: CSP headers, error boundaries, logging, rate-limiting on auth routes, CDN caching headers.

11. **Deploy** — Build → containerize or use platform deploy hook (Vercel, Netlify, Fly.io, AWS Amplify). Run smoke tests against preview URL before promoting to production.

---

## Standards

**Do**
- Validate all user input server-side, never trust the client.
- Use `Content-Security-Policy` headers; disable `unsafe-inline` where possible.
- Serve static assets with `Cache-Control: public, max-age=31536000, immutable` and hash-based filenames.
- Keep `node_modules` out of Docker images — copy `package.json` + lock file, run `npm ci`, then copy source.
- Lazy-load routes and heavy third-party scripts.
- Prefer relative imports with path aliases (`@/components`) defined in `tsconfig.json`.

**Do not**
- Store tokens in `localStorage` (use `httpOnly` cookies).
- Render raw user HTML without sanitization (use `DOMPurify` or server-side escaping).
- Inline `<script>` tags that bypass CSP.
- Block the main thread with synchronous I/O or heavy computation; offload to Web Workers.
- Hard-code environment-specific URLs in source code.
- Ship `console.log` or debug code to production.

---

## Common mistakes to avoid

- **Missing `key` props in lists** — causes subtle reconciliation bugs; always use stable, unique keys (not array index).
- **Fetching on every render** — memoize requests with React Query, SWR, or server-component caching; missing dependencies in `useEffect` is the classic trigger.
- **SSR/hydration mismatch** — avoid accessing `window` or `document` at module scope; guard with `typeof window !== 'undefined'` or use `useEffect`.
- **Unhandled loading and error states** — every async data fetch needs a loading skeleton and an error fallback; missing them produces blank screens.
- **Forgetting `rel="noopener noreferrer"` on external links** — tabnapping vulnerability.
- **Over-fetching in API routes** — select only the columns/fields the page needs; returning full ORM objects leaks internal data.
- **Not invalidating CDN cache after deploy** — stale assets served to users; use versioned filenames or cache-busting query params.

---

## Output format

A production-ready web project should include:

```
/
├── src/
│   ├── app/ (or pages/)        # Route files
│   ├── components/             # Reusable UI
│   ├── lib/                    # Shared utilities, data-access, auth
│   ├── styles/                 # Global CSS / Tailwind config
│   └── types/                  # Shared TypeScript types
├── public/                     # Static assets (favicon, robots.txt)
├── tests/                      # Unit + e2e tests
├── .env.example                # Required env vars (no values)
├── Dockerfile (optional)
└── README.md                   # Local setup in < 5 commands
```

---

## Related checklists

- `.claude/checklists/security.md`
- `.claude/checklists/accessibility.md`
- `.claude/checklists/performance.md`
- `.claude/checklists/qa.md`
- `.claude/checklists/production.md`

## Related agents

- `.claude/agents/core/orchestrator.md`
- `.claude/agents/engineering/frontend-engineer.md`
- `.claude/agents/quality/security-auditor.md`