From 16c20bcd6c525020c0857df6707acb83a04929f5 Mon Sep 17 00:00:00 2001 From: zlei9 Date: Sun, 29 Mar 2026 10:15:04 +0800 Subject: [PATCH] Initial commit with translated description --- SKILL.md | 43 +++++++++++++++++++++++++++++++++++++++++++ _meta.json | 6 ++++++ deploy.md | 35 +++++++++++++++++++++++++++++++++++ frameworks.md | 27 +++++++++++++++++++++++++++ html-css.md | 24 ++++++++++++++++++++++++ javascript.md | 35 +++++++++++++++++++++++++++++++++++ performance.md | 44 ++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 214 insertions(+) create mode 100644 SKILL.md create mode 100644 _meta.json create mode 100644 deploy.md create mode 100644 frameworks.md create mode 100644 html-css.md create mode 100644 javascript.md create mode 100644 performance.md diff --git a/SKILL.md b/SKILL.md new file mode 100644 index 0000000..515af6b --- /dev/null +++ b/SKILL.md @@ -0,0 +1,43 @@ +--- +name: Web Development +description: "使用HTML、CSS、JavaScript、现代框架和生产最佳实践构建、调试和部署网站。" +--- + +## Quick Reference + +| Need | See | +|------|-----| +| HTML/CSS issues | `html-css.md` | +| JavaScript patterns | `javascript.md` | +| React/Next.js/frameworks | `frameworks.md` | +| Deploy to production | `deploy.md` | +| Performance/SEO/a11y | `performance.md` | + +## Critical Rules + +1. **DOCTYPE matters** — Missing `` triggers quirks mode; layouts break unpredictably +2. **CSS specificity beats cascade** — `.class` overrides element selectors regardless of order +3. **`===` not `==`** — Type coercion causes `"0" == false` to be true +4. **Async/await in loops** — `forEach` doesn't await; use `for...of` or `Promise.all` +5. **CORS is server-side** — No client-side fix; configure `Access-Control-Allow-Origin` on the server +6. **Responsive = viewport meta** — Without ``, mobile renders desktop-width +7. **Form without `preventDefault`** — Page reloads; call `e.preventDefault()` in submit handler +8. **Images need dimensions** — Missing `width`/`height` causes layout shift (CLS penalty) +9. **HTTPS or blocked** — Mixed content (HTTP resources on HTTPS pages) gets blocked by browsers +10. **Environment variables leak** — `NEXT_PUBLIC_*` exposes to client; never prefix secrets + +## Common Requests + +**"Make it responsive"** → Mobile-first CSS with media queries; test at 320px, 768px, 1024px +**"Deploy to production"** → See `deploy.md` for Vercel/Netlify/VPS patterns +**"Fix CORS error"** → Server must send headers; proxy through same-origin if you can't control server +**"Improve performance"** → Lighthouse audit; focus on LCP, CLS, FID; lazy-load below-fold images +**"Add SEO"** → Title/description per page, semantic HTML, OG tags, sitemap.xml + +## Framework Decision Tree + +- **Static content, fast builds** → Astro or plain HTML +- **Blog/docs with MDX** → Astro or Next.js App Router +- **Interactive app with auth** → Next.js or Remix +- **Full SSR/ISR control** → Next.js +- **Simple SPA, no SEO needed** → Vite + React/Vue diff --git a/_meta.json b/_meta.json new file mode 100644 index 0000000..abce4c3 --- /dev/null +++ b/_meta.json @@ -0,0 +1,6 @@ +{ + "ownerId": "kn73vp5rarc3b14rc7wjcw8f8580t5d1", + "slug": "web", + "version": "1.0.0", + "publishedAt": 1771082933366 +} \ No newline at end of file diff --git a/deploy.md b/deploy.md new file mode 100644 index 0000000..342b822 --- /dev/null +++ b/deploy.md @@ -0,0 +1,35 @@ +# Deployment Patterns + +## Platform Comparison + +| Platform | Best for | Gotchas | +|----------|----------|---------| +| Vercel | Next.js, serverless | Cold starts; limited to 10s (Hobby) or 60s (Pro) for functions | +| Netlify | Static + serverless | Functions timeout at 10s (free) / 26s (paid) | +| Cloudflare Pages | Static + Workers | Workers have no Node APIs; use `node-compat` flag | +| VPS (Docker) | Full control, long-running | You manage SSL, updates, scaling | +| Railway/Render | Docker apps | Sleep after inactivity on free tier | + +## Common Deploy Issues + +- **Build fails locally works** — Check Node version matches; use `.nvmrc` or `engines` in package.json +- **Environment variables missing** — Platform dashboards don't auto-sync; redeploy after adding vars +- **Static export breaks API routes** — `next export` is static only; use Vercel/custom server for API routes +- **Trailing slashes** — Configure consistently; `/about` vs `/about/` causes duplicate content/redirects + +## DNS Setup + +1. **Add A record** — Point `@` to platform IP (or use CNAME for subdomains) +2. **Add CNAME for www** — Point `www` to apex or platform domain +3. **Wait for propagation** — Up to 48h but usually minutes; check with `dig` or online tools +4. **SSL auto-provisions** — Most platforms handle Let's Encrypt; may take a few minutes after DNS resolves + +## Deployment Checklist + +- [ ] Environment variables set in platform dashboard +- [ ] Build command correct (`npm run build`, not `npm start`) +- [ ] Output directory correct (`out`, `.next`, `dist`) +- [ ] Domain DNS configured and propagated +- [ ] HTTPS working (check certificate valid) +- [ ] 404 page configured +- [ ] Redirects for old URLs if migrating diff --git a/frameworks.md b/frameworks.md new file mode 100644 index 0000000..f5a3de5 --- /dev/null +++ b/frameworks.md @@ -0,0 +1,27 @@ +# Framework Patterns and Traps + +## React + +- **State updates are async** — `setState(x)` doesn't immediately change state; use callback form for derived state +- **Keys must be stable** — Don't use array index as key if list reorders; causes bugs with forms/animations +- **useEffect dependencies** — Missing deps cause stale closures; ESLint exhaustive-deps catches these +- **useEffect cleanup** — Return cleanup function for subscriptions/timers; prevents memory leaks +- **Conditional hooks** — Hooks can't be in conditions/loops; breaks React's hook order tracking +- **Context rerenders** — Every consumer rerenders when context value changes; memoize or split contexts + +## Next.js (App Router) + +- **Server vs Client Components** — Default is server; add `"use client"` for hooks, browser APIs, events +- **`fetch` in Server Components** — Automatically deduped and cached; use `{cache: 'no-store'}` for fresh +- **Middleware runs on edge** — No Node APIs; limited to Web APIs and edge-compatible packages +- **Route handlers** — Export `GET`, `POST` functions from `route.ts`; not `page.tsx` +- **`revalidatePath`/`revalidateTag`** — Call after mutations to bust cache; ISR invalidation +- **Parallel routes** — Use `@folder` convention for loading multiple routes in same layout +- **`NEXT_PUBLIC_` prefix** — Required for env vars in client code; others are server-only + +## General SPA + +- **Hydration mismatch** — Server and client must render identically on first pass; use `useEffect` for client-only +- **Bundle size** — Tree-shaking needs ES modules; named imports from lodash don't tree-shake without lodash-es +- **Code splitting** — Use `lazy()` or `next/dynamic` for below-fold components; improves LCP +- **SSR data fetching** — Fetch on server to avoid waterfalls; don't fetch in useEffect for initial data diff --git a/html-css.md b/html-css.md new file mode 100644 index 0000000..f9161f4 --- /dev/null +++ b/html-css.md @@ -0,0 +1,24 @@ +# HTML/CSS Patterns and Traps + +## HTML + +- **Semantic elements for SEO/a11y** — Use `
`, `
`, `