@ssheleg/sheleg-dev 0.4.0

package/plugins/sheleg-dev/skills/frontend-performance/references/nextjs.md

@@ -0,0 +1,271 @@
+# Next.js Performance Patterns
+
+
+## Contents
+
+- [Font Optimization with `next/font`](#font-optimization-with-nextfont)
+- [Code Splitting with `next/dynamic`](#code-splitting-with-nextdynamic)
+- [Cache Headers in `next.config.ts`](#cache-headers-in-nextconfigts)
+- [Content Security Policy](#content-security-policy)
+- [Script Loading Strategy](#script-loading-strategy)
+- [Image Optimization](#image-optimization)
+- [Bundle Analysis](#bundle-analysis)
+- [Browserslist Configuration](#browserslist-configuration)
+
+## Font Optimization with `next/font`
+
+### Migration from `<link>` to `next/font/google`
+
+Replace external Google Fonts links with `next/font/google` imports. This:
+- Inlines font CSS at build time (no render-blocking request)
+- Self-hosts font files from `/_next/static/` (no external dependency)
+- Eliminates need for `preconnect` hints and Google Fonts CSP entries
+- Enables automatic subsetting
+
+**Before (bad):**
+```tsx
+// layout.tsx
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossOrigin="anonymous" />
+<link href="https://fonts.googleapis.com/css2?family=DM+Sans&family=Outfit&display=swap" rel="stylesheet" />
+```
+
+**After (good):**
+```tsx
+// layout.tsx
+import { DM_Sans, Outfit } from "next/font/google";
+
+const dmSans = DM_Sans({
+  subsets: ["latin"],
+  variable: "--font-dm-sans",
+  weight: ["400", "500", "600", "700"],
+  display: "swap",
+});
+
+const outfit = Outfit({
+  subsets: ["latin"],
+  variable: "--font-outfit",
+  weight: ["400", "500", "600", "700", "800"],
+  display: "swap",
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="en" className={`${dmSans.variable} ${outfit.variable}`}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+Then reference via CSS variables in `globals.css`:
+```css
+body { font-family: var(--font-dm-sans), system-ui, sans-serif; }
+h1, h2, h3 { font-family: var(--font-outfit), system-ui, sans-serif; }
+```
+
+### Multiple Font Families
+
+Load only fonts actually used. Each family adds ~20-50KB. Three families is a practical maximum for landing pages.
+
+If using variable fonts (weight ranges), specify the range:
+```tsx
+const dmSans = DM_Sans({
+  subsets: ["latin"],
+  variable: "--font-dm-sans",
+  weight: ["400", "500", "600", "700"],  // or omit for variable font full range
+  display: "swap",
+});
+```
+
+## Code Splitting with `next/dynamic`
+
+Lazy-load below-the-fold sections to reduce initial JavaScript bundle:
+
+```tsx
+import dynamic from "next/dynamic";
+
+// Above-the-fold: import normally
+import { HeroSection } from "@/components/hero";
+import { Navbar } from "@/components/navbar";
+
+// Below-the-fold: lazy load
+const Testimonials = dynamic(() =>
+  import("@/components/testimonials").then((m) => m.TestimonialsSection)
+);
+const FAQ = dynamic(() =>
+  import("@/components/faq").then((m) => m.FAQSection)
+);
+const Pricing = dynamic(() =>
+  import("@/components/pricing").then((m) => m.PricingSection)
+);
+```
+
+Only use `next/dynamic` for components that are:
+- Below the initial viewport (not visible without scrolling)
+- Heavy (> 10KB compressed)
+- Not critical for SEO (search engines execute JS but slower)
+
+Do NOT dynamically import the hero, navbar, or footer -- these must render immediately.
+
+## Cache Headers in `next.config.ts`
+
+Add cache headers for static assets:
+
+```typescript
+// next.config.ts
+const nextConfig = {
+  async headers() {
+    return [
+      {
+        source: "/:path*.:ext(svg|png|jpg|jpeg|gif|webp|ico|woff|woff2)",
+        headers: [
+          {
+            key: "Cache-Control",
+            value: "public, max-age=31536000, immutable",
+          },
+        ],
+      },
+    ];
+  },
+};
+```
+
+**Critical:** Next.js uses `path-to-regexp` for route matching. Common pattern mistakes:
+
+| Pattern | Works? | Why |
+|---------|--------|-----|
+| `/:path*{.svg,.png}` | No | Braces are literal in path-to-regexp |
+| `/:path*.(svg\|png)` | No | Pipe needs to be inside a named param |
+| `/:path*.:ext(svg\|png\|jpg)` | Yes | Regex parameter syntax |
+
+Test patterns before deploying:
+```javascript
+const { match } = require("path-to-regexp");
+const fn = match("/:path*.:ext(svg|png|jpg)");
+console.log(fn("/logo.svg"));    // { params: { path: ["logo"], ext: "svg" } }
+console.log(fn("/page"));        // false
+```
+
+## Content Security Policy
+
+Configure CSP in `next.config.ts` security headers:
+
+```typescript
+{
+  source: "/(.*)",
+  headers: [
+    {
+      key: "Content-Security-Policy",
+      value: [
+        "default-src 'self'",
+        "script-src 'self' 'unsafe-inline' 'unsafe-eval' https://www.googletagmanager.com https://www.google-analytics.com https://static.cloudflareinsights.com",
+        "style-src 'self' 'unsafe-inline'",
+        "img-src 'self' data: blob: https:",
+        "font-src 'self'",
+        "connect-src 'self' https://www.google-analytics.com https://vitals.vercel-insights.com",
+      ].join("; "),
+    },
+  ],
+}
+```
+
+**Rules:**
+- After migrating fonts to `next/font`, remove `fonts.googleapis.com` from `style-src` and `fonts.gstatic.com` from `font-src` -- self-hosted fonts are covered by `'self'`.
+- Every new third-party script/style requires a CSP update.
+- CSP violations show as console errors and directly lower the Best Practices score.
+
+## Script Loading Strategy
+
+Use `next/script` for third-party scripts:
+
+```tsx
+import Script from "next/script";
+
+// Google Analytics -- load after page is interactive
+<Script
+  src={`https://www.googletagmanager.com/gtag/js?id=${GA_ID}`}
+  strategy="afterInteractive"
+/>
+```
+
+| Strategy | When | Use For |
+|----------|------|---------|
+| `beforeInteractive` | Before hydration | Critical polyfills, A/B test scripts |
+| `afterInteractive` | After hydration (default) | Analytics, tracking |
+| `lazyOnload` | After everything | Chat widgets, social embeds |
+| `worker` | In web worker (experimental) | Heavy non-critical scripts |
+
+Never use raw `<script>` tags in Next.js -- they bypass optimization.
+
+## Image Optimization
+
+```tsx
+import Image from "next/image";
+
+// LCP hero image -- priority load
+<Image
+  src="/hero.webp"
+  alt="Product dashboard showing analytics"
+  width={1200}
+  height={630}
+  priority
+  sizes="100vw"
+/>
+
+// Below-fold image -- lazy load (default)
+<Image
+  src="/feature.webp"
+  alt="Feature screenshot"
+  width={600}
+  height={400}
+  sizes="(max-width: 768px) 100vw, 50vw"
+/>
+```
+
+**Rules:**
+- Always set `priority` on the LCP image (usually the hero).
+- Always provide `sizes` for responsive images.
+- Always provide `width` and `height` to prevent CLS.
+- Use `alt=""` for decorative images (logos next to brand text).
+- Remote images require `remotePatterns` in `next.config.ts`.
+
+## Bundle Analysis
+
+```bash
+# Install analyzer
+npm install -D @next/bundle-analyzer
+
+# Add to next.config.ts
+const withBundleAnalyzer = require("@next/bundle-analyzer")({
+  enabled: process.env.ANALYZE === "true",
+});
+module.exports = withBundleAnalyzer(nextConfig);
+
+# Run analysis
+ANALYZE=true next build
+```
+
+Look for:
+- Large dependencies (lodash, moment.js) that can be replaced
+- Duplicate packages across chunks
+- Server-only code leaking into client bundles
+
+## Browserslist Configuration
+
+Add to `package.json` to reduce polyfill shipping:
+
+```json
+{
+  "browserslist": [
+    "last 2 Chrome versions",
+    "last 2 Firefox versions",
+    "last 2 Safari versions",
+    "last 2 Edge versions"
+  ]
+}
+```
+
+This tells SWC to skip polyfills for `Array.prototype.at`, `Object.fromEntries`, `String.prototype.trimStart`, etc. Saves ~10-15KB on typical bundles.
+
+Note: Some polyfills are bundled by Next.js core and cannot be eliminated via `browserslist`.

package/plugins/sheleg-dev/skills/google-auth/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: google-auth
+description: >-
+  Use when implementing Google authentication in a Node.js or Python web application — Google
+  login, OAuth 2.0 flows, verifying Google ID tokens, service account authentication,
+  Application Default Credentials, Google Identity Services, Workload Identity Federation, API
+  keys, or working with google-auth-library (Node.js) or google-auth (Python). Covers ID token
+  verification and security best practices. Triggers - "google auth", "google login", "google
+  sign in", "OAuth 2.0 Google", "google-auth-library", "Sign In with Google", "Google Identity
+  Services", "GIS", "ADC", "Application Default Credentials", "service account", "Google ID
+  token", "verifyIdToken", "GOOGLE_APPLICATION_CREDENTIALS", "Google SSO", "вход через Google",
+  "авторизация Google", "сервисный аккаунт", "проверить ID-токен", "гугл-логин". For end-user
+  web sign-in only, use the google-signin skill instead.
+---
+
+# Google Authentication for Node.js & Python
+
+## Libraries
+
+### Node.js
+
+- `google-auth-library` — core auth library (OAuth2Client, GoogleAuth, JWT, Compute, Impersonated)
+- `googleapis` — Google API client (wraps google-auth-library)
+
+```bash
+npm install google-auth-library
+npm install googleapis
+```
+
+### Python
+
+- `google-auth` — core auth library (google.oauth2, google.auth, credentials, transport)
+- `google-auth-oauthlib` — OAuth 2.0 user-credential flow helpers (Flow, InstalledAppFlow)
+- `google-api-python-client` — Google API client (wraps google-auth)
+
+```bash
+pip install google-auth
+pip install google-auth-oauthlib
+pip install google-api-python-client
+```
+
+## Authentication Methods Overview
+
+| Method | Use Case | Node.js Key Class | Python Key Module / Class |
+|--------|----------|-------------------|---------------------------|
+| **ADC** | Same identity for all users, server-to-server | `GoogleAuth` | `google.auth.default()` |
+| **OAuth 2.0** | Actions on behalf of end users | `OAuth2Client` | `google_auth_oauthlib.flow.Flow` |
+| **Sign In with Google (GIS)** | User sign-in/sign-up on websites | GIS JS SDK + `verifyIdToken()` | GIS JS SDK + `id_token.verify_oauth2_token()` |
+| **JWT / Service Account** | Server-to-server, single identity | `JWT` | `service_account.Credentials` |
+| **API Key** | Public data, no user context | `OAuth2Client({ apiKey })` | passed to `googleapiclient.discovery.build(developerKey=)` |
+| **Compute** | On GCP with attached service account | `Compute` | `google.auth.compute_engine.Credentials` |
+| **Workload Identity Federation** | AWS/Azure/OIDC → GCP without SA keys | `ExternalAccountClient` | `google.auth.identity_pool.Credentials` / `google.auth.aws.Credentials` |
+
+## Quick Patterns
+
+### 1. Application Default Credentials (ADC)
+
+**Node.js**
+
+```js
+const {GoogleAuth} = require('google-auth-library');
+
+const auth = new GoogleAuth({
+  scopes: 'https://www.googleapis.com/auth/cloud-platform'
+});
+const client = await auth.getClient();
+const res = await client.fetch('https://dns.googleapis.com/dns/v1/projects/...');
+```
+
+**Python**
+
+```python
+import google.auth
+import google.auth.transport.requests
+
+credentials, project = google.auth.default(
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+request = google.auth.transport.requests.Request()
+credentials.refresh(request)
+```
+
+ADC search order: attached service account → `gcloud auth application-default login` file → `GOOGLE_APPLICATION_CREDENTIALS` env var.
+
+For detailed ADC setup and service account usage, see [references/adc-and-service-accounts.md](references/adc-and-service-accounts.md).
+
+### 2. OAuth 2.0 Web Server Flow
+
+**Node.js**
+
+```js
+const {OAuth2Client} = require('google-auth-library');
+
+const client = new OAuth2Client({
+  clientId: CLIENT_ID,
+  clientSecret: CLIENT_SECRET,
+  redirectUri: REDIRECT_URI
+});
+
+const authUrl = client.generateAuthUrl({
+  access_type: 'offline',
+  scope: ['https://www.googleapis.com/auth/userinfo.profile'],
+  state: crypto.randomBytes(32).toString('hex'),
+  include_granted_scopes: true
+});
+
+// After redirect: exchange code for tokens
+const {tokens} = await client.getToken(code);
+client.setCredentials(tokens);
+```
+
+**Python**
+
+```python
+from google_auth_oauthlib.flow import Flow
+
+flow = Flow.from_client_secrets_file(
+    'client_secret.json',
+    scopes=['https://www.googleapis.com/auth/userinfo.profile'],
+    redirect_uri=REDIRECT_URI
+)
+
+authorization_url, state = flow.authorization_url(
+    access_type='offline',
+    include_granted_scopes='true'
+)
+
+# After redirect: exchange code for tokens
+flow.fetch_token(code=code)
+credentials = flow.credentials
+```
+
+`refresh_token` is only returned on the first authorization. Use `prompt: 'consent'` (Node.js) or `prompt='consent'` (Python) to force re-consent.
+
+For the complete OAuth 2.0 flow (parameters, token exchange, refresh, revocation, incremental auth), see [references/oauth2-web-server.md](references/oauth2-web-server.md).
+
+### 3. Sign In with Google — ID Token Verification
+
+**Node.js**
+
+```js
+const {OAuth2Client} = require('google-auth-library');
+const client = new OAuth2Client();
+
+const ticket = await client.verifyIdToken({
+  idToken: token,
+  audience: WEB_CLIENT_ID,
+});
+const payload = ticket.getPayload();
+const userId = payload['sub'];
+const email = payload['email'];
+const name = payload['name'];
+const picture = payload['picture'];
+```
+
+**Python**
+
+```python
+from google.oauth2 import id_token
+from google.auth.transport import requests
+
+request = requests.Request()
+
+payload = id_token.verify_oauth2_token(
+    token,
+    request,
+    WEB_CLIENT_ID
+)
+user_id = payload['sub']
+email = payload['email']
+name = payload.get('name', '')
+picture = payload.get('picture')
+```
+
+Verification checks: JWT signature, `aud`, `exp`, `iss` (accounts.google.com).
+
+For GIS integration, CSRF protection, and hosted domain validation, see [references/sign-in-with-google.md](references/sign-in-with-google.md).
+
+### 4. JWT / Service Account
+
+**Node.js**
+
+```js
+const {JWT} = require('google-auth-library');
+const keys = require('./service-account-key.json');
+
+const client = new JWT({
+  email: keys.client_email,
+  key: keys.private_key,
+  scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+});
+const res = await client.fetch(url);
+```
+
+**Python**
+
+```python
+from google.oauth2 import service_account
+
+credentials = service_account.Credentials.from_service_account_file(
+    'service-account-key.json',
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+
+# Or from a dict already loaded into memory:
+credentials = service_account.Credentials.from_service_account_info(
+    info,
+    scopes=['https://www.googleapis.com/auth/cloud-platform']
+)
+```
+
+### 5. API Key
+
+**Node.js**
+
+```js
+const {OAuth2Client} = require('google-auth-library');
+const client = new OAuth2Client({ apiKey: 'my-api-key' });
+
+// Or via GoogleAuth:
+const {GoogleAuth} = require('google-auth-library');
+const auth = new GoogleAuth({
+  clientOptions: { apiKey: 'my-api-key' }
+});
+```
+
+**Python**
+
+```python
+from googleapiclient.discovery import build
+
+service = build('customsearch', 'v1', developerKey='my-api-key')
+```
+
+### 6. Token Refresh
+
+**Node.js**
+
+```js
+client.on('tokens', (tokens) => {
+  if (tokens.refresh_token) {
+    // Store refresh_token — only sent on first auth
+  }
+  console.log(tokens.access_token);
+});
+```
+
+**Python**
+
+```python
+from google.auth.transport.requests import Request
+
+if credentials.expired and credentials.refresh_token:
+    credentials.refresh(Request())
+    # credentials.token is the new access token
+    # credentials.expiry is the new expiration datetime
+```
+
+## Security Best Practices
+
+- Never expose `client_secret` or service account keys in client-side code
+- Always validate `state` parameter to prevent CSRF in OAuth flows
+- Use `sub` (not `email`) as the unique user identifier from Google ID tokens
+- Store `refresh_token` securely; it's only returned on first authorization
+- Validate external credential configurations before use (check `token_url`, `service_account_impersonation_url` point to googleapis.com)
+- Prefer Workload Identity Federation over service account keys for non-GCP environments
+- For GIS: verify `g_csrf_token` with double-submit-cookie pattern
+- **Python-specific**: reuse a single `google.auth.transport.requests.Request()` instance across verifications for connection pooling; do not create a new one per call in hot paths
+
+## Reference Files
+
+- **[OAuth 2.0 Web Server Flow](references/oauth2-web-server.md)** — Complete OAuth 2.0 flow: parameters, consent, token exchange, refresh, revocation, incremental auth, error handling (Node.js + Python)
+- **[ADC & Service Accounts](references/adc-and-service-accounts.md)** — Application Default Credentials setup, service account keys, JWT, Compute credentials, environment configuration (Node.js + Python)
+- **[Sign In with Google](references/sign-in-with-google.md)** — Google Identity Services (GIS), ID token verification, CSRF protection, One Tap, FedCM (Node.js + Python)
+- **[Workload Identity Federation](references/workload-identity.md)** — AWS, Azure, OIDC/SAML federation, workforce identity, executable-sourced credentials (Node.js + Python)