packwise-skills 1.0.0

package/sub-skills/web/spa.md

@@ -0,0 +1,266 @@
+# SPA (Single Page Application) Build Sub-Skill
+
+Build and package pure frontend projects (React/Vue/Angular/Svelte/Solid).
+
+**Current versions**: Vite 8.x / Webpack 5 / Angular 19 / Svelte 5 (2025-2026)
+
+> ⚠️ **Vite 8.x**: If upgrading from Vite 6, check the [Vite migration guide](https://vitejs.dev/guide/migration) for breaking changes in plugin API and configuration format. Verify `vite-plugin-pwa`, `vite-plugin-wasm`, and other plugins are compatible with v8.
+
+## When to Use
+
+- Pure frontend project (no backend in the same repo)
+- Data from external API or localStorage
+- University course work, graduation project, portfolio
+- Enterprise website, showcase application
+- Admin dashboards, internal tools
+
+## Build Tools Comparison
+
+| Tool | Speed | Config | HMR | Best For |
+|------|-------|--------|-----|---------|
+| **Vite 8** | Fastest | Minimal | Instant | New projects (default for Vue/React/Svelte) |
+| **Webpack 5** | Moderate | Complex | Good | Legacy projects, complex builds |
+| **esbuild** | Ultra fast | Minimal | N/A | Libraries, simple apps |
+| **Turbopack** | Very fast | Next.js only | Fast | Next.js projects |
+
+## Framework Builds
+
+### Vite (React / Vue / Svelte / Solid)
+
+```bash
+# Create project
+npm create vite@latest my-app -- --template react-ts   # React + TypeScript
+npm create vite@latest my-app -- --template vue-ts     # Vue + TypeScript
+npm create vite@latest my-app -- --template svelte-ts  # Svelte + TypeScript
+
+# Build
+npm run build
+# Output: dist/ directory
+
+# Preview production build locally
+npm run preview
+```
+
+```javascript
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+
+export default defineConfig({
+  plugins: [react()],
+  base: '/',                    // Set for sub-directory deployment
+  build: {
+    outDir: 'dist',
+    sourcemap: false,           // Disable for production
+    rolldownOptions: {           // ⚠️ Vite 8: renamed from rollupOptions
+      output: {
+        // Vite 8: manualChunks object form removed. Use function form or codeSplitting.
+        manualChunks(id) {
+          if (id.includes('node_modules')) {
+            return 'vendor';
+          }
+        },
+      },
+    },
+  },
+  server: {
+    proxy: {                     // Dev proxy to avoid CORS
+      '/api': 'http://localhost:3000',
+    },
+  },
+});
+```
+
+### Angular
+
+```bash
+# Build
+ng build --configuration=production
+# Output: dist/my-app/
+
+# With SSR
+ng build --configuration=production
+ng run my-app:server:production
+```
+
+### React (Create React App — Legacy)
+
+```bash
+# CRA is no longer recommended for new projects; use Vite instead
+npx create-react-app my-app  # Legacy
+npm run build
+# Output: build/ directory
+```
+
+## Production Optimization Checklist
+
+```javascript
+// vite.config.ts — production optimizations (Vite 8)
+export default defineConfig({
+  build: {
+    // Vite 8: esbuild minification replaced by Oxc minifier
+    // To use terser for advanced control, install terser and set:
+    // minify: 'terser',
+    // terserOptions: { ... },
+    chunkSizeWarningLimit: 500,          // Warn if chunk > 500KB
+    rolldownOptions: {                   // ⚠️ Vite 8: was rollupOptions
+      output: {
+        manualChunks(id) {               // ⚠️ Vite 8: object form removed, use function
+          if (id.includes('node_modules')) {
+            return 'vendor';
+          }
+        },
+      },
+    },
+  },
+  // Vite 8: esbuild option deprecated, use oxc for JSX/define transforms
+  // esbuild: { drop: ['console', 'debugger'] },  // deprecated
+  // Use rolldownOptions.output.minify.compress.drop instead
+  css: {
+    modules: {
+      localsConvention: 'camelCase',
+    },
+  },
+});
+```
+
+| Optimization | How | Impact |
+|-------------|-----|--------|
+| Tree shaking | Rolldown does this automatically (Vite 8) | Remove unused code |
+| Code splitting | `manualChunks` function in Vite 8; `codeSplitting` in Rolldown | Smaller initial load |
+| Lazy loading | `React.lazy()` / `defineAsyncComponent()` | On-demand loading |
+| Asset compression | Brotli (`.br`) or Gzip (`.gz`) | 70-80% transfer size reduction |
+| Image optimization | Use WebP/AVIF; `vite-plugin-imagemin` | 30-50% image size reduction |
+| CSS purging | `purgecss` or built into Tailwind | Remove unused CSS |
+| Preload/prefetch | `<link rel="preload">` for critical assets | Faster initial paint |
+
+## Deployment Targets
+
+| Platform | Method | Cost | Best For |
+|----------|--------|------|----------|
+| Vercel | Git push auto-deploy | Free tier | Personal/small team |
+| Netlify | Git push auto-deploy | Free tier | Personal/small team |
+| GitHub Pages | Git Actions auto-deploy | Free | Open source projects |
+| Cloudflare Pages | Git push auto-deploy | Free tier | Global CDN, fast |
+| Aliyun OSS + CDN | Upload dist/ | Pay-per-use | China access |
+| Tencent COS + CDN | Upload dist/ | Pay-per-use | China access |
+| AWS S3 + CloudFront | Upload dist/ | Pay-per-use | AWS ecosystem |
+| Nginx | Manual deploy | Server cost | Self-hosted |
+| Docker (nginx) | Containerize | Server cost | Containerized infrastructure |
+
+### Vercel
+
+```bash
+npm i -g vercel
+vercel --prod
+```
+
+### Netlify
+
+```bash
+npm i -g netlify-cli
+netlify deploy --prod --dir=dist
+```
+
+### GitHub Pages
+
+```yaml
+# .github/workflows/deploy.yml
+name: Deploy
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+      - run: npm ci && npm run build
+      - uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./dist
+```
+
+### Nginx
+
+```nginx
+server {
+    listen 80;
+    server_name example.com;
+    root /var/www/myapp/dist;
+    index index.html;
+
+    # SPA routing (all routes → index.html)
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    # Cache static assets
+    location /assets/ {
+        expires 1y;
+        add_header Cache-Control "public, immutable";
+    }
+
+    # Gzip compression
+    gzip on;
+    gzip_types text/css application/javascript application/json image/svg+xml;
+    gzip_min_length 1000;
+}
+```
+
+### Docker
+
+```dockerfile
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM nginx:alpine
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+COPY --from=builder /app/dist /usr/share/nginx/html
+COPY nginx.conf /etc/nginx/conf.d/default.conf
+RUN chown -R appuser:appgroup /usr/share/nginx/html
+USER appuser
+EXPOSE 80
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:80/ || exit 1
+```
+
+## Environment Variables
+
+```bash
+# Vite: only VITE_ prefixed vars are exposed to client
+VITE_API_URL=https://api.example.com
+VITE_APP_TITLE=My App
+
+# In code:
+const apiUrl = import.meta.env.VITE_API_URL;
+```
+
+```bash
+# Angular: use environment.ts files
+# Webpack: use process.env.REACT_APP_* (CRA) or DefinePlugin
+```
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Refresh 404 on deploy | Nginx: `try_files $uri /index.html`; all hosting: configure SPA fallback |
+| Path error after deploy | `vite.config.ts` set `base: '/subpath/'` for non-root deployment |
+| CORS error in dev | Vite: `server.proxy`; Angular: `proxy.conf.json` |
+| Env var not working | Vite: only `VITE_` prefix vars are bundled; Angular: use `environment.ts` |
+| Large bundle (> 1MB) | Enable code splitting; lazy load routes; analyze with `rollup-plugin-visualizer` |
+| White screen on deploy | Check browser console for errors; verify `base` path in config |
+| CSS not loading | Check if CSS import path is correct; verify build output structure |
+| Images not showing | Use `import` for images (Vite/Webpack process them); don't use string paths |
+| Vite 8: `rollupOptions` not working | Renamed to `rolldownOptions` in Vite 8; see migration guide |
+| Vite 8: esbuild options ignored | esbuild deprecated; use `oxc` for transforms, `rolldownOptions` for minification |
+| Vite 8: `manualChunks` object form error | Object form removed; use function form or Rolldown `codeSplitting` |
+| Vite 8: ES5 output fails | ES5 transformation no longer supported; target modern browsers only |

package/sub-skills/web/ssr.md

@@ -0,0 +1,228 @@
+# SSR (Server-Side Rendering) Build Sub-Skill
+
+Build and package SSR frameworks (Next.js / Nuxt / Remix / SvelteKit / Astro).
+
+**Current versions**: Next.js 16 / Nuxt 3.x / Remix 2.x / SvelteKit 2.x / Astro 5.x (2025-2026)
+
+> ⚠️ **Next.js 16 Breaking Changes** (released Oct 2025):
+> - **Turbopack is default bundler** — custom `webpack` configs will fail. Use `next build --webpack` to opt out.
+> - `params` and `searchParams` must be `await`ed (synchronous access removed).
+> - `cookies()` and `headers()` must be `await`ed.
+> - **`middleware.ts` deprecated** → rename to `proxy.ts`, export `proxy` function (runs on Node.js, not Edge).
+> - AMP support fully removed. `next lint` command removed.
+> - `serverRuntimeConfig`/`publicRuntimeConfig` removed (use env vars).
+> - `experimental.ppr` removed → use `cacheComponents: true`.
+> - `next/image`: `minimumCacheTTL` default 60s→14400s, `qualities` default changed to `[75]` only.
+> - Node.js 20.9+ required (Node 18 dropped). React 19.2.
+> - Run `npx @next/codemod@canary upgrade latest` for automated migration.
+
+## When to Use
+
+- SEO-required websites (blogs, e-commerce, news, marketing)
+- Dynamic pages needing server-side rendering
+- Full-stack applications with API Routes
+- Content-heavy sites with fast initial load
+- Hybrid rendering (SSR + SSG + ISR)
+
+## Framework Comparison
+
+| Feature | Next.js 16 | Nuxt 3.x | Remix 2.x | SvelteKit 2.x | Astro 5.x |
+|---------|-----------|---------|----------|--------------|----------|
+| Base | React | Vue | React | Svelte | Any (React/Vue/Svelte/Solid) |
+| Rendering | SSR/SSG/ISR/RSC | SSR/SSG/ISR | SSR | SSR/SSG | SSG + Islands |
+| API Routes | App Router | Nitro server | Loaders/Actions | Server routes | Endpoints |
+| Edge support | Yes (Vercel/CF) | Yes (Nitro) | Yes | Yes | Yes |
+| Best for | Full-stack React | Full-stack Vue | Data-heavy apps | Lightweight full-stack | Content sites |
+
+## Build
+
+### Next.js
+
+```bash
+# Build
+npm run build
+# Output: .next/ directory
+
+# Start production server
+npm run start
+
+# Static export (no server needed)
+# next.config.js: output: 'export'
+npm run build
+# Output: out/ directory (can be deployed to any static host)
+```
+
+```javascript
+// next.config.js
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  output: 'standalone',          // Self-contained build with Node.js server
+  // output: 'export',           // Static HTML export (no server)
+  images: {
+    unoptimized: true,           // Required for static export
+  },
+};
+module.exports = nextConfig;
+```
+
+### Nuxt
+
+```bash
+# Build
+npm run build
+# Output: .output/ directory (includes server)
+
+# Static generation
+npm run generate
+# Output: .output/public/ directory
+
+# Start production
+node .output/server/index.mjs
+```
+
+### Remix
+
+```bash
+# Build
+npm run build
+# Output: build/ directory
+
+# Start production
+npm run start
+```
+
+### SvelteKit
+
+```bash
+# Build (requires adapter)
+npm run build
+# Output depends on adapter (node/static/cloudflare/vercel)
+```
+
+```javascript
+// svelte.config.js
+import adapter from '@sveltejs/adapter-node';    // For Node.js server
+// import adapter from '@sveltejs/adapter-static'; // For static export
+// import adapter from '@sveltejs/adapter-vercel'; // For Vercel
+```
+
+### Astro
+
+```bash
+# Build (SSG by default)
+npm run build
+# Output: dist/ directory
+
+# Build with SSR
+# astro.config.mjs: output: 'server'
+npm run build
+# Output: dist/server/ + dist/client/
+```
+
+```javascript
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+
+export default defineConfig({
+  output: 'server',              // 'static' (default) or 'server'
+  adapter: node({ mode: 'standalone' }),
+});
+```
+
+## Deployment Targets
+
+| Platform | Next.js | Nuxt | Remix | SvelteKit | Astro |
+|----------|---------|------|-------|----------|-------|
+| Vercel | Native | Adapter | Native | Adapter | Adapter |
+| Netlify | Adapter | Adapter | Adapter | Adapter | Adapter |
+| Cloudflare Workers | Adapter | Nitro | Adapter | Adapter | Adapter |
+| Docker (Node.js) | Standalone | Standard | Standard | Node adapter | Node adapter |
+| Static hosting | `output: 'export'` | `generate` | N/A | Static adapter | Default |
+| AWS Lambda | OpenNext | Nitro | Remix adapter | Adapter | Adapter |
+
+## Docker (Next.js Standalone)
+
+> ⚠️ **Next.js 16**: Turbopack is now the default bundler. If your project has custom `webpack` config, pass `--webpack` flag to `next build`. `serverRuntimeConfig`/`publicRuntimeConfig` removed — use env variables instead.
+
+```dockerfile
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+# Standalone output includes minimal node_modules
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup && \
+    chown -R appuser:appgroup /app
+USER appuser
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/ || exit 1
+ENV NODE_ENV=production
+CMD ["node", "server.js"]
+```
+
+## Docker (Nuxt / Generic Node SSR)
+
+```dockerfile
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine
+WORKDIR /app
+COPY --from=builder /app/.output ./.output
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup && \
+    chown -R appuser:appgroup /app
+USER appuser
+EXPOSE 3000
+HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/ || exit 1
+CMD ["node", ".output/server/index.mjs"]
+```
+
+## PM2 (Process Manager)
+
+```bash
+npm run build
+pm2 start npm --name "myapp" -- start
+pm2 save && pm2 startup
+# Cluster mode:
+pm2 start npm --name "myapp" -i max -- start
+```
+
+## Rendering Modes
+
+| Mode | Description | Use Case |
+|------|-------------|---------|
+| **SSR** | Render on every request | Dynamic content, user-specific pages |
+| **SSG** | Pre-render at build time | Static content, documentation |
+| **ISR** | Re-render on interval (e.g., every 60s) | Blog posts, product pages |
+| **Streaming SSR** | Stream HTML as it renders | Large pages, slow data sources |
+| **Partial Prerender** | Static shell + dynamic holes | Mixed content (Next.js 14+) |
+
+## Common Pitfalls
+
+| Issue | Fix |
+|-------|-----|
+| Static resource 404 | Next.js: check `assetPrefix`; Nuxt: check `app.baseURL` |
+| API Routes not working | Ensure Node.js >= 20.9; check runtime config for serverless |
+| Env var leakage | Server vars should NOT have `NEXT_PUBLIC_` prefix (Next.js) |
+| Memory leak in long-running | PM2: set `--max-memory-restart 500M`; check for event listener leaks |
+| SSR hydration mismatch | Ensure server and client render identical HTML; avoid `Date.now()` in SSR |
+| `getServerSideProps` slow | Add caching headers; use ISR; optimize database queries |
+| Build fails with "out of memory" | Increase Node.js heap: `NODE_OPTIONS=--max-old-space-size=4096` |
+| CSS flash on load (FOUC) | Extract CSS to files (default in most frameworks); avoid inline styles |
+| Images not optimized | Next.js: use `<Image>` component; Nuxt: use `<NuxtImg>` |
+| Next.js 16: Turbopack breaks build | Custom webpack config fails with Turbopack default; use `next build --webpack` |
+| Next.js 16: params not awaited | `params`/`searchParams`/`cookies()`/`headers()` must be `await`ed |
+| Next.js 16: middleware not found | Renamed to `proxy.ts`; export `proxy` function instead of `middleware` |
+| Next.js 16: parallel route error | All parallel route slots now require explicit `default.js` files |