This commit is contained in:
@@ -1,177 +0,0 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
name: frontend-design
|
||||
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
|
||||
license: Complete terms in LICENSE.txt
|
||||
---
|
||||
|
||||
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
|
||||
|
||||
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
|
||||
|
||||
## Design Thinking
|
||||
|
||||
Before coding, understand the context and commit to a BOLD aesthetic direction:
|
||||
- **Purpose**: What problem does this interface solve? Who uses it?
|
||||
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
|
||||
- **Constraints**: Technical requirements (framework, performance, accessibility).
|
||||
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
|
||||
|
||||
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
|
||||
|
||||
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
|
||||
- Production-grade and functional
|
||||
- Visually striking and memorable
|
||||
- Cohesive with a clear aesthetic point-of-view
|
||||
- Meticulously refined in every detail
|
||||
|
||||
## Frontend Aesthetics Guidelines
|
||||
|
||||
Focus on:
|
||||
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
|
||||
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
|
||||
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
|
||||
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
|
||||
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
|
||||
|
||||
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
|
||||
|
||||
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
|
||||
|
||||
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
|
||||
|
||||
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,136 +0,0 @@
|
||||
---
|
||||
name: vercel-react-best-practices
|
||||
description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
|
||||
license: MIT
|
||||
metadata:
|
||||
author: vercel
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Vercel React Best Practices
|
||||
|
||||
Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 57 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
|
||||
|
||||
## When to Apply
|
||||
|
||||
Reference these guidelines when:
|
||||
- Writing new React components or Next.js pages
|
||||
- Implementing data fetching (client or server-side)
|
||||
- Reviewing code for performance issues
|
||||
- Refactoring existing React/Next.js code
|
||||
- Optimizing bundle size or load times
|
||||
|
||||
## Rule Categories by Priority
|
||||
|
||||
| Priority | Category | Impact | Prefix |
|
||||
|----------|----------|--------|--------|
|
||||
| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
|
||||
| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
|
||||
| 3 | Server-Side Performance | HIGH | `server-` |
|
||||
| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
|
||||
| 5 | Re-render Optimization | MEDIUM | `rerender-` |
|
||||
| 6 | Rendering Performance | MEDIUM | `rendering-` |
|
||||
| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
|
||||
| 8 | Advanced Patterns | LOW | `advanced-` |
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### 1. Eliminating Waterfalls (CRITICAL)
|
||||
|
||||
- `async-defer-await` - Move await into branches where actually used
|
||||
- `async-parallel` - Use Promise.all() for independent operations
|
||||
- `async-dependencies` - Use better-all for partial dependencies
|
||||
- `async-api-routes` - Start promises early, await late in API routes
|
||||
- `async-suspense-boundaries` - Use Suspense to stream content
|
||||
|
||||
### 2. Bundle Size Optimization (CRITICAL)
|
||||
|
||||
- `bundle-barrel-imports` - Import directly, avoid barrel files
|
||||
- `bundle-dynamic-imports` - Use next/dynamic for heavy components
|
||||
- `bundle-defer-third-party` - Load analytics/logging after hydration
|
||||
- `bundle-conditional` - Load modules only when feature is activated
|
||||
- `bundle-preload` - Preload on hover/focus for perceived speed
|
||||
|
||||
### 3. Server-Side Performance (HIGH)
|
||||
|
||||
- `server-auth-actions` - Authenticate server actions like API routes
|
||||
- `server-cache-react` - Use React.cache() for per-request deduplication
|
||||
- `server-cache-lru` - Use LRU cache for cross-request caching
|
||||
- `server-dedup-props` - Avoid duplicate serialization in RSC props
|
||||
- `server-serialization` - Minimize data passed to client components
|
||||
- `server-parallel-fetching` - Restructure components to parallelize fetches
|
||||
- `server-after-nonblocking` - Use after() for non-blocking operations
|
||||
|
||||
### 4. Client-Side Data Fetching (MEDIUM-HIGH)
|
||||
|
||||
- `client-swr-dedup` - Use SWR for automatic request deduplication
|
||||
- `client-event-listeners` - Deduplicate global event listeners
|
||||
- `client-passive-event-listeners` - Use passive listeners for scroll
|
||||
- `client-localstorage-schema` - Version and minimize localStorage data
|
||||
|
||||
### 5. Re-render Optimization (MEDIUM)
|
||||
|
||||
- `rerender-defer-reads` - Don't subscribe to state only used in callbacks
|
||||
- `rerender-memo` - Extract expensive work into memoized components
|
||||
- `rerender-memo-with-default-value` - Hoist default non-primitive props
|
||||
- `rerender-dependencies` - Use primitive dependencies in effects
|
||||
- `rerender-derived-state` - Subscribe to derived booleans, not raw values
|
||||
- `rerender-derived-state-no-effect` - Derive state during render, not effects
|
||||
- `rerender-functional-setstate` - Use functional setState for stable callbacks
|
||||
- `rerender-lazy-state-init` - Pass function to useState for expensive values
|
||||
- `rerender-simple-expression-in-memo` - Avoid memo for simple primitives
|
||||
- `rerender-move-effect-to-event` - Put interaction logic in event handlers
|
||||
- `rerender-transitions` - Use startTransition for non-urgent updates
|
||||
- `rerender-use-ref-transient-values` - Use refs for transient frequent values
|
||||
|
||||
### 6. Rendering Performance (MEDIUM)
|
||||
|
||||
- `rendering-animate-svg-wrapper` - Animate div wrapper, not SVG element
|
||||
- `rendering-content-visibility` - Use content-visibility for long lists
|
||||
- `rendering-hoist-jsx` - Extract static JSX outside components
|
||||
- `rendering-svg-precision` - Reduce SVG coordinate precision
|
||||
- `rendering-hydration-no-flicker` - Use inline script for client-only data
|
||||
- `rendering-hydration-suppress-warning` - Suppress expected mismatches
|
||||
- `rendering-activity` - Use Activity component for show/hide
|
||||
- `rendering-conditional-render` - Use ternary, not && for conditionals
|
||||
- `rendering-usetransition-loading` - Prefer useTransition for loading state
|
||||
|
||||
### 7. JavaScript Performance (LOW-MEDIUM)
|
||||
|
||||
- `js-batch-dom-css` - Group CSS changes via classes or cssText
|
||||
- `js-index-maps` - Build Map for repeated lookups
|
||||
- `js-cache-property-access` - Cache object properties in loops
|
||||
- `js-cache-function-results` - Cache function results in module-level Map
|
||||
- `js-cache-storage` - Cache localStorage/sessionStorage reads
|
||||
- `js-combine-iterations` - Combine multiple filter/map into one loop
|
||||
- `js-length-check-first` - Check array length before expensive comparison
|
||||
- `js-early-exit` - Return early from functions
|
||||
- `js-hoist-regexp` - Hoist RegExp creation outside loops
|
||||
- `js-min-max-loop` - Use loop for min/max instead of sort
|
||||
- `js-set-map-lookups` - Use Set/Map for O(1) lookups
|
||||
- `js-tosorted-immutable` - Use toSorted() for immutability
|
||||
|
||||
### 8. Advanced Patterns (LOW)
|
||||
|
||||
- `advanced-event-handler-refs` - Store event handlers in refs
|
||||
- `advanced-init-once` - Initialize app once per app load
|
||||
- `advanced-use-latest` - useLatest for stable callback refs
|
||||
|
||||
## How to Use
|
||||
|
||||
Read individual rule files for detailed explanations and code examples:
|
||||
|
||||
```
|
||||
rules/async-parallel.md
|
||||
rules/bundle-barrel-imports.md
|
||||
```
|
||||
|
||||
Each rule file contains:
|
||||
- Brief explanation of why it matters
|
||||
- Incorrect code example with explanation
|
||||
- Correct code example with explanation
|
||||
- Additional context and references
|
||||
|
||||
## Full Compiled Document
|
||||
|
||||
For the complete guide with all rules expanded: `AGENTS.md`
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: Store Event Handlers in Refs
|
||||
impact: LOW
|
||||
impactDescription: stable subscriptions
|
||||
tags: advanced, hooks, refs, event-handlers, optimization
|
||||
---
|
||||
|
||||
## Store Event Handlers in Refs
|
||||
|
||||
Store callbacks in refs when used in effects that shouldn't re-subscribe on callback changes.
|
||||
|
||||
**Incorrect (re-subscribes on every render):**
|
||||
|
||||
```tsx
|
||||
function useWindowEvent(event: string, handler: (e) => void) {
|
||||
useEffect(() => {
|
||||
window.addEventListener(event, handler)
|
||||
return () => window.removeEventListener(event, handler)
|
||||
}, [event, handler])
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (stable subscription):**
|
||||
|
||||
```tsx
|
||||
function useWindowEvent(event: string, handler: (e) => void) {
|
||||
const handlerRef = useRef(handler)
|
||||
useEffect(() => {
|
||||
handlerRef.current = handler
|
||||
}, [handler])
|
||||
|
||||
useEffect(() => {
|
||||
const listener = (e) => handlerRef.current(e)
|
||||
window.addEventListener(event, listener)
|
||||
return () => window.removeEventListener(event, listener)
|
||||
}, [event])
|
||||
}
|
||||
```
|
||||
|
||||
**Alternative: use `useEffectEvent` if you're on latest React:**
|
||||
|
||||
```tsx
|
||||
import { useEffectEvent } from 'react'
|
||||
|
||||
function useWindowEvent(event: string, handler: (e) => void) {
|
||||
const onEvent = useEffectEvent(handler)
|
||||
|
||||
useEffect(() => {
|
||||
window.addEventListener(event, onEvent)
|
||||
return () => window.removeEventListener(event, onEvent)
|
||||
}, [event])
|
||||
}
|
||||
```
|
||||
|
||||
`useEffectEvent` provides a cleaner API for the same pattern: it creates a stable function reference that always calls the latest version of the handler.
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
title: Initialize App Once, Not Per Mount
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: avoids duplicate init in development
|
||||
tags: initialization, useEffect, app-startup, side-effects
|
||||
---
|
||||
|
||||
## Initialize App Once, Not Per Mount
|
||||
|
||||
Do not put app-wide initialization that must run once per app load inside `useEffect([])` of a component. Components can remount and effects will re-run. Use a module-level guard or top-level init in the entry module instead.
|
||||
|
||||
**Incorrect (runs twice in dev, re-runs on remount):**
|
||||
|
||||
```tsx
|
||||
function Comp() {
|
||||
useEffect(() => {
|
||||
loadFromStorage()
|
||||
checkAuthToken()
|
||||
}, [])
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (once per app load):**
|
||||
|
||||
```tsx
|
||||
let didInit = false
|
||||
|
||||
function Comp() {
|
||||
useEffect(() => {
|
||||
if (didInit) return
|
||||
didInit = true
|
||||
loadFromStorage()
|
||||
checkAuthToken()
|
||||
}, [])
|
||||
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
Reference: [Initializing the application](https://react.dev/learn/you-might-not-need-an-effect#initializing-the-application)
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: useEffectEvent for Stable Callback Refs
|
||||
impact: LOW
|
||||
impactDescription: prevents effect re-runs
|
||||
tags: advanced, hooks, useEffectEvent, refs, optimization
|
||||
---
|
||||
|
||||
## useEffectEvent for Stable Callback Refs
|
||||
|
||||
Access latest values in callbacks without adding them to dependency arrays. Prevents effect re-runs while avoiding stale closures.
|
||||
|
||||
**Incorrect (effect re-runs on every callback change):**
|
||||
|
||||
```tsx
|
||||
function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
|
||||
const [query, setQuery] = useState('')
|
||||
|
||||
useEffect(() => {
|
||||
const timeout = setTimeout(() => onSearch(query), 300)
|
||||
return () => clearTimeout(timeout)
|
||||
}, [query, onSearch])
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (using React's useEffectEvent):**
|
||||
|
||||
```tsx
|
||||
import { useEffectEvent } from 'react';
|
||||
|
||||
function SearchInput({ onSearch }: { onSearch: (q: string) => void }) {
|
||||
const [query, setQuery] = useState('')
|
||||
const onSearchEvent = useEffectEvent(onSearch)
|
||||
|
||||
useEffect(() => {
|
||||
const timeout = setTimeout(() => onSearchEvent(query), 300)
|
||||
return () => clearTimeout(timeout)
|
||||
}, [query])
|
||||
}
|
||||
```
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: Prevent Waterfall Chains in API Routes
|
||||
impact: CRITICAL
|
||||
impactDescription: 2-10× improvement
|
||||
tags: api-routes, server-actions, waterfalls, parallelization
|
||||
---
|
||||
|
||||
## Prevent Waterfall Chains in API Routes
|
||||
|
||||
In API routes and Server Actions, start independent operations immediately, even if you don't await them yet.
|
||||
|
||||
**Incorrect (config waits for auth, data waits for both):**
|
||||
|
||||
```typescript
|
||||
export async function GET(request: Request) {
|
||||
const session = await auth()
|
||||
const config = await fetchConfig()
|
||||
const data = await fetchData(session.user.id)
|
||||
return Response.json({ data, config })
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (auth and config start immediately):**
|
||||
|
||||
```typescript
|
||||
export async function GET(request: Request) {
|
||||
const sessionPromise = auth()
|
||||
const configPromise = fetchConfig()
|
||||
const session = await sessionPromise
|
||||
const [config, data] = await Promise.all([
|
||||
configPromise,
|
||||
fetchData(session.user.id)
|
||||
])
|
||||
return Response.json({ data, config })
|
||||
}
|
||||
```
|
||||
|
||||
For operations with more complex dependency chains, use `better-all` to automatically maximize parallelism (see Dependency-Based Parallelization).
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
title: Defer Await Until Needed
|
||||
impact: HIGH
|
||||
impactDescription: avoids blocking unused code paths
|
||||
tags: async, await, conditional, optimization
|
||||
---
|
||||
|
||||
## Defer Await Until Needed
|
||||
|
||||
Move `await` operations into the branches where they're actually used to avoid blocking code paths that don't need them.
|
||||
|
||||
**Incorrect (blocks both branches):**
|
||||
|
||||
```typescript
|
||||
async function handleRequest(userId: string, skipProcessing: boolean) {
|
||||
const userData = await fetchUserData(userId)
|
||||
|
||||
if (skipProcessing) {
|
||||
// Returns immediately but still waited for userData
|
||||
return { skipped: true }
|
||||
}
|
||||
|
||||
// Only this branch uses userData
|
||||
return processUserData(userData)
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (only blocks when needed):**
|
||||
|
||||
```typescript
|
||||
async function handleRequest(userId: string, skipProcessing: boolean) {
|
||||
if (skipProcessing) {
|
||||
// Returns immediately without waiting
|
||||
return { skipped: true }
|
||||
}
|
||||
|
||||
// Fetch only when needed
|
||||
const userData = await fetchUserData(userId)
|
||||
return processUserData(userData)
|
||||
}
|
||||
```
|
||||
|
||||
**Another example (early return optimization):**
|
||||
|
||||
```typescript
|
||||
// Incorrect: always fetches permissions
|
||||
async function updateResource(resourceId: string, userId: string) {
|
||||
const permissions = await fetchPermissions(userId)
|
||||
const resource = await getResource(resourceId)
|
||||
|
||||
if (!resource) {
|
||||
return { error: 'Not found' }
|
||||
}
|
||||
|
||||
if (!permissions.canEdit) {
|
||||
return { error: 'Forbidden' }
|
||||
}
|
||||
|
||||
return await updateResourceData(resource, permissions)
|
||||
}
|
||||
|
||||
// Correct: fetches only when needed
|
||||
async function updateResource(resourceId: string, userId: string) {
|
||||
const resource = await getResource(resourceId)
|
||||
|
||||
if (!resource) {
|
||||
return { error: 'Not found' }
|
||||
}
|
||||
|
||||
const permissions = await fetchPermissions(userId)
|
||||
|
||||
if (!permissions.canEdit) {
|
||||
return { error: 'Forbidden' }
|
||||
}
|
||||
|
||||
return await updateResourceData(resource, permissions)
|
||||
}
|
||||
```
|
||||
|
||||
This optimization is especially valuable when the skipped branch is frequently taken, or when the deferred operation is expensive.
|
||||
@@ -1,51 +0,0 @@
|
||||
---
|
||||
title: Dependency-Based Parallelization
|
||||
impact: CRITICAL
|
||||
impactDescription: 2-10× improvement
|
||||
tags: async, parallelization, dependencies, better-all
|
||||
---
|
||||
|
||||
## Dependency-Based Parallelization
|
||||
|
||||
For operations with partial dependencies, use `better-all` to maximize parallelism. It automatically starts each task at the earliest possible moment.
|
||||
|
||||
**Incorrect (profile waits for config unnecessarily):**
|
||||
|
||||
```typescript
|
||||
const [user, config] = await Promise.all([
|
||||
fetchUser(),
|
||||
fetchConfig()
|
||||
])
|
||||
const profile = await fetchProfile(user.id)
|
||||
```
|
||||
|
||||
**Correct (config and profile run in parallel):**
|
||||
|
||||
```typescript
|
||||
import { all } from 'better-all'
|
||||
|
||||
const { user, config, profile } = await all({
|
||||
async user() { return fetchUser() },
|
||||
async config() { return fetchConfig() },
|
||||
async profile() {
|
||||
return fetchProfile((await this.$.user).id)
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
**Alternative without extra dependencies:**
|
||||
|
||||
We can also create all the promises first, and do `Promise.all()` at the end.
|
||||
|
||||
```typescript
|
||||
const userPromise = fetchUser()
|
||||
const profilePromise = userPromise.then(user => fetchProfile(user.id))
|
||||
|
||||
const [user, config, profile] = await Promise.all([
|
||||
userPromise,
|
||||
fetchConfig(),
|
||||
profilePromise
|
||||
])
|
||||
```
|
||||
|
||||
Reference: [https://github.com/shuding/better-all](https://github.com/shuding/better-all)
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
title: Promise.all() for Independent Operations
|
||||
impact: CRITICAL
|
||||
impactDescription: 2-10× improvement
|
||||
tags: async, parallelization, promises, waterfalls
|
||||
---
|
||||
|
||||
## Promise.all() for Independent Operations
|
||||
|
||||
When async operations have no interdependencies, execute them concurrently using `Promise.all()`.
|
||||
|
||||
**Incorrect (sequential execution, 3 round trips):**
|
||||
|
||||
```typescript
|
||||
const user = await fetchUser()
|
||||
const posts = await fetchPosts()
|
||||
const comments = await fetchComments()
|
||||
```
|
||||
|
||||
**Correct (parallel execution, 1 round trip):**
|
||||
|
||||
```typescript
|
||||
const [user, posts, comments] = await Promise.all([
|
||||
fetchUser(),
|
||||
fetchPosts(),
|
||||
fetchComments()
|
||||
])
|
||||
```
|
||||
@@ -1,99 +0,0 @@
|
||||
---
|
||||
title: Strategic Suspense Boundaries
|
||||
impact: HIGH
|
||||
impactDescription: faster initial paint
|
||||
tags: async, suspense, streaming, layout-shift
|
||||
---
|
||||
|
||||
## Strategic Suspense Boundaries
|
||||
|
||||
Instead of awaiting data in async components before returning JSX, use Suspense boundaries to show the wrapper UI faster while data loads.
|
||||
|
||||
**Incorrect (wrapper blocked by data fetching):**
|
||||
|
||||
```tsx
|
||||
async function Page() {
|
||||
const data = await fetchData() // Blocks entire page
|
||||
|
||||
return (
|
||||
<div>
|
||||
<div>Sidebar</div>
|
||||
<div>Header</div>
|
||||
<div>
|
||||
<DataDisplay data={data} />
|
||||
</div>
|
||||
<div>Footer</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
The entire layout waits for data even though only the middle section needs it.
|
||||
|
||||
**Correct (wrapper shows immediately, data streams in):**
|
||||
|
||||
```tsx
|
||||
function Page() {
|
||||
return (
|
||||
<div>
|
||||
<div>Sidebar</div>
|
||||
<div>Header</div>
|
||||
<div>
|
||||
<Suspense fallback={<Skeleton />}>
|
||||
<DataDisplay />
|
||||
</Suspense>
|
||||
</div>
|
||||
<div>Footer</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
async function DataDisplay() {
|
||||
const data = await fetchData() // Only blocks this component
|
||||
return <div>{data.content}</div>
|
||||
}
|
||||
```
|
||||
|
||||
Sidebar, Header, and Footer render immediately. Only DataDisplay waits for data.
|
||||
|
||||
**Alternative (share promise across components):**
|
||||
|
||||
```tsx
|
||||
function Page() {
|
||||
// Start fetch immediately, but don't await
|
||||
const dataPromise = fetchData()
|
||||
|
||||
return (
|
||||
<div>
|
||||
<div>Sidebar</div>
|
||||
<div>Header</div>
|
||||
<Suspense fallback={<Skeleton />}>
|
||||
<DataDisplay dataPromise={dataPromise} />
|
||||
<DataSummary dataPromise={dataPromise} />
|
||||
</Suspense>
|
||||
<div>Footer</div>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
function DataDisplay({ dataPromise }: { dataPromise: Promise<Data> }) {
|
||||
const data = use(dataPromise) // Unwraps the promise
|
||||
return <div>{data.content}</div>
|
||||
}
|
||||
|
||||
function DataSummary({ dataPromise }: { dataPromise: Promise<Data> }) {
|
||||
const data = use(dataPromise) // Reuses the same promise
|
||||
return <div>{data.summary}</div>
|
||||
}
|
||||
```
|
||||
|
||||
Both components share the same promise, so only one fetch occurs. Layout renders immediately while both components wait together.
|
||||
|
||||
**When NOT to use this pattern:**
|
||||
|
||||
- Critical data needed for layout decisions (affects positioning)
|
||||
- SEO-critical content above the fold
|
||||
- Small, fast queries where suspense overhead isn't worth it
|
||||
- When you want to avoid layout shift (loading → content jump)
|
||||
|
||||
**Trade-off:** Faster initial paint vs potential layout shift. Choose based on your UX priorities.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
title: Avoid Barrel File Imports
|
||||
impact: CRITICAL
|
||||
impactDescription: 200-800ms import cost, slow builds
|
||||
tags: bundle, imports, tree-shaking, barrel-files, performance
|
||||
---
|
||||
|
||||
## Avoid Barrel File Imports
|
||||
|
||||
Import directly from source files instead of barrel files to avoid loading thousands of unused modules. **Barrel files** are entry points that re-export multiple modules (e.g., `index.js` that does `export * from './module'`).
|
||||
|
||||
Popular icon and component libraries can have **up to 10,000 re-exports** in their entry file. For many React packages, **it takes 200-800ms just to import them**, affecting both development speed and production cold starts.
|
||||
|
||||
**Why tree-shaking doesn't help:** When a library is marked as external (not bundled), the bundler can't optimize it. If you bundle it to enable tree-shaking, builds become substantially slower analyzing the entire module graph.
|
||||
|
||||
**Incorrect (imports entire library):**
|
||||
|
||||
```tsx
|
||||
import { Check, X, Menu } from 'lucide-react'
|
||||
// Loads 1,583 modules, takes ~2.8s extra in dev
|
||||
// Runtime cost: 200-800ms on every cold start
|
||||
|
||||
import { Button, TextField } from '@mui/material'
|
||||
// Loads 2,225 modules, takes ~4.2s extra in dev
|
||||
```
|
||||
|
||||
**Correct (imports only what you need):**
|
||||
|
||||
```tsx
|
||||
import Check from 'lucide-react/dist/esm/icons/check'
|
||||
import X from 'lucide-react/dist/esm/icons/x'
|
||||
import Menu from 'lucide-react/dist/esm/icons/menu'
|
||||
// Loads only 3 modules (~2KB vs ~1MB)
|
||||
|
||||
import Button from '@mui/material/Button'
|
||||
import TextField from '@mui/material/TextField'
|
||||
// Loads only what you use
|
||||
```
|
||||
|
||||
**Alternative (Next.js 13.5+):**
|
||||
|
||||
```js
|
||||
// next.config.js - use optimizePackageImports
|
||||
module.exports = {
|
||||
experimental: {
|
||||
optimizePackageImports: ['lucide-react', '@mui/material']
|
||||
}
|
||||
}
|
||||
|
||||
// Then you can keep the ergonomic barrel imports:
|
||||
import { Check, X, Menu } from 'lucide-react'
|
||||
// Automatically transformed to direct imports at build time
|
||||
```
|
||||
|
||||
Direct imports provide 15-70% faster dev boot, 28% faster builds, 40% faster cold starts, and significantly faster HMR.
|
||||
|
||||
Libraries commonly affected: `lucide-react`, `@mui/material`, `@mui/icons-material`, `@tabler/icons-react`, `react-icons`, `@headlessui/react`, `@radix-ui/react-*`, `lodash`, `ramda`, `date-fns`, `rxjs`, `react-use`.
|
||||
|
||||
Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
|
||||
@@ -1,31 +0,0 @@
|
||||
---
|
||||
title: Conditional Module Loading
|
||||
impact: HIGH
|
||||
impactDescription: loads large data only when needed
|
||||
tags: bundle, conditional-loading, lazy-loading
|
||||
---
|
||||
|
||||
## Conditional Module Loading
|
||||
|
||||
Load large data or modules only when a feature is activated.
|
||||
|
||||
**Example (lazy-load animation frames):**
|
||||
|
||||
```tsx
|
||||
function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) {
|
||||
const [frames, setFrames] = useState<Frame[] | null>(null)
|
||||
|
||||
useEffect(() => {
|
||||
if (enabled && !frames && typeof window !== 'undefined') {
|
||||
import('./animation-frames.js')
|
||||
.then(mod => setFrames(mod.frames))
|
||||
.catch(() => setEnabled(false))
|
||||
}
|
||||
}, [enabled, frames, setEnabled])
|
||||
|
||||
if (!frames) return <Skeleton />
|
||||
return <Canvas frames={frames} />
|
||||
}
|
||||
```
|
||||
|
||||
The `typeof window !== 'undefined'` check prevents bundling this module for SSR, optimizing server bundle size and build speed.
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Defer Non-Critical Third-Party Libraries
|
||||
impact: MEDIUM
|
||||
impactDescription: loads after hydration
|
||||
tags: bundle, third-party, analytics, defer
|
||||
---
|
||||
|
||||
## Defer Non-Critical Third-Party Libraries
|
||||
|
||||
Analytics, logging, and error tracking don't block user interaction. Load them after hydration.
|
||||
|
||||
**Incorrect (blocks initial bundle):**
|
||||
|
||||
```tsx
|
||||
import { Analytics } from '@vercel/analytics/react'
|
||||
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html>
|
||||
<body>
|
||||
{children}
|
||||
<Analytics />
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (loads after hydration):**
|
||||
|
||||
```tsx
|
||||
import dynamic from 'next/dynamic'
|
||||
|
||||
const Analytics = dynamic(
|
||||
() => import('@vercel/analytics/react').then(m => m.Analytics),
|
||||
{ ssr: false }
|
||||
)
|
||||
|
||||
export default function RootLayout({ children }) {
|
||||
return (
|
||||
<html>
|
||||
<body>
|
||||
{children}
|
||||
<Analytics />
|
||||
</body>
|
||||
</html>
|
||||
)
|
||||
}
|
||||
```
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Dynamic Imports for Heavy Components
|
||||
impact: CRITICAL
|
||||
impactDescription: directly affects TTI and LCP
|
||||
tags: bundle, dynamic-import, code-splitting, next-dynamic
|
||||
---
|
||||
|
||||
## Dynamic Imports for Heavy Components
|
||||
|
||||
Use `next/dynamic` to lazy-load large components not needed on initial render.
|
||||
|
||||
**Incorrect (Monaco bundles with main chunk ~300KB):**
|
||||
|
||||
```tsx
|
||||
import { MonacoEditor } from './monaco-editor'
|
||||
|
||||
function CodePanel({ code }: { code: string }) {
|
||||
return <MonacoEditor value={code} />
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (Monaco loads on demand):**
|
||||
|
||||
```tsx
|
||||
import dynamic from 'next/dynamic'
|
||||
|
||||
const MonacoEditor = dynamic(
|
||||
() => import('./monaco-editor').then(m => m.MonacoEditor),
|
||||
{ ssr: false }
|
||||
)
|
||||
|
||||
function CodePanel({ code }: { code: string }) {
|
||||
return <MonacoEditor value={code} />
|
||||
}
|
||||
```
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: Preload Based on User Intent
|
||||
impact: MEDIUM
|
||||
impactDescription: reduces perceived latency
|
||||
tags: bundle, preload, user-intent, hover
|
||||
---
|
||||
|
||||
## Preload Based on User Intent
|
||||
|
||||
Preload heavy bundles before they're needed to reduce perceived latency.
|
||||
|
||||
**Example (preload on hover/focus):**
|
||||
|
||||
```tsx
|
||||
function EditorButton({ onClick }: { onClick: () => void }) {
|
||||
const preload = () => {
|
||||
if (typeof window !== 'undefined') {
|
||||
void import('./monaco-editor')
|
||||
}
|
||||
}
|
||||
|
||||
return (
|
||||
<button
|
||||
onMouseEnter={preload}
|
||||
onFocus={preload}
|
||||
onClick={onClick}
|
||||
>
|
||||
Open Editor
|
||||
</button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Example (preload when feature flag is enabled):**
|
||||
|
||||
```tsx
|
||||
function FlagsProvider({ children, flags }: Props) {
|
||||
useEffect(() => {
|
||||
if (flags.editorEnabled && typeof window !== 'undefined') {
|
||||
void import('./monaco-editor').then(mod => mod.init())
|
||||
}
|
||||
}, [flags.editorEnabled])
|
||||
|
||||
return <FlagsContext.Provider value={flags}>
|
||||
{children}
|
||||
</FlagsContext.Provider>
|
||||
}
|
||||
```
|
||||
|
||||
The `typeof window !== 'undefined'` check prevents bundling preloaded modules for SSR, optimizing server bundle size and build speed.
|
||||
@@ -1,74 +0,0 @@
|
||||
---
|
||||
title: Deduplicate Global Event Listeners
|
||||
impact: LOW
|
||||
impactDescription: single listener for N components
|
||||
tags: client, swr, event-listeners, subscription
|
||||
---
|
||||
|
||||
## Deduplicate Global Event Listeners
|
||||
|
||||
Use `useSWRSubscription()` to share global event listeners across component instances.
|
||||
|
||||
**Incorrect (N instances = N listeners):**
|
||||
|
||||
```tsx
|
||||
function useKeyboardShortcut(key: string, callback: () => void) {
|
||||
useEffect(() => {
|
||||
const handler = (e: KeyboardEvent) => {
|
||||
if (e.metaKey && e.key === key) {
|
||||
callback()
|
||||
}
|
||||
}
|
||||
window.addEventListener('keydown', handler)
|
||||
return () => window.removeEventListener('keydown', handler)
|
||||
}, [key, callback])
|
||||
}
|
||||
```
|
||||
|
||||
When using the `useKeyboardShortcut` hook multiple times, each instance will register a new listener.
|
||||
|
||||
**Correct (N instances = 1 listener):**
|
||||
|
||||
```tsx
|
||||
import useSWRSubscription from 'swr/subscription'
|
||||
|
||||
// Module-level Map to track callbacks per key
|
||||
const keyCallbacks = new Map<string, Set<() => void>>()
|
||||
|
||||
function useKeyboardShortcut(key: string, callback: () => void) {
|
||||
// Register this callback in the Map
|
||||
useEffect(() => {
|
||||
if (!keyCallbacks.has(key)) {
|
||||
keyCallbacks.set(key, new Set())
|
||||
}
|
||||
keyCallbacks.get(key)!.add(callback)
|
||||
|
||||
return () => {
|
||||
const set = keyCallbacks.get(key)
|
||||
if (set) {
|
||||
set.delete(callback)
|
||||
if (set.size === 0) {
|
||||
keyCallbacks.delete(key)
|
||||
}
|
||||
}
|
||||
}
|
||||
}, [key, callback])
|
||||
|
||||
useSWRSubscription('global-keydown', () => {
|
||||
const handler = (e: KeyboardEvent) => {
|
||||
if (e.metaKey && keyCallbacks.has(e.key)) {
|
||||
keyCallbacks.get(e.key)!.forEach(cb => cb())
|
||||
}
|
||||
}
|
||||
window.addEventListener('keydown', handler)
|
||||
return () => window.removeEventListener('keydown', handler)
|
||||
})
|
||||
}
|
||||
|
||||
function Profile() {
|
||||
// Multiple shortcuts will share the same listener
|
||||
useKeyboardShortcut('p', () => { /* ... */ })
|
||||
useKeyboardShortcut('k', () => { /* ... */ })
|
||||
// ...
|
||||
}
|
||||
```
|
||||
@@ -1,71 +0,0 @@
|
||||
---
|
||||
title: Version and Minimize localStorage Data
|
||||
impact: MEDIUM
|
||||
impactDescription: prevents schema conflicts, reduces storage size
|
||||
tags: client, localStorage, storage, versioning, data-minimization
|
||||
---
|
||||
|
||||
## Version and Minimize localStorage Data
|
||||
|
||||
Add version prefix to keys and store only needed fields. Prevents schema conflicts and accidental storage of sensitive data.
|
||||
|
||||
**Incorrect:**
|
||||
|
||||
```typescript
|
||||
// No version, stores everything, no error handling
|
||||
localStorage.setItem('userConfig', JSON.stringify(fullUserObject))
|
||||
const data = localStorage.getItem('userConfig')
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```typescript
|
||||
const VERSION = 'v2'
|
||||
|
||||
function saveConfig(config: { theme: string; language: string }) {
|
||||
try {
|
||||
localStorage.setItem(`userConfig:${VERSION}`, JSON.stringify(config))
|
||||
} catch {
|
||||
// Throws in incognito/private browsing, quota exceeded, or disabled
|
||||
}
|
||||
}
|
||||
|
||||
function loadConfig() {
|
||||
try {
|
||||
const data = localStorage.getItem(`userConfig:${VERSION}`)
|
||||
return data ? JSON.parse(data) : null
|
||||
} catch {
|
||||
return null
|
||||
}
|
||||
}
|
||||
|
||||
// Migration from v1 to v2
|
||||
function migrate() {
|
||||
try {
|
||||
const v1 = localStorage.getItem('userConfig:v1')
|
||||
if (v1) {
|
||||
const old = JSON.parse(v1)
|
||||
saveConfig({ theme: old.darkMode ? 'dark' : 'light', language: old.lang })
|
||||
localStorage.removeItem('userConfig:v1')
|
||||
}
|
||||
} catch {}
|
||||
}
|
||||
```
|
||||
|
||||
**Store minimal fields from server responses:**
|
||||
|
||||
```typescript
|
||||
// User object has 20+ fields, only store what UI needs
|
||||
function cachePrefs(user: FullUser) {
|
||||
try {
|
||||
localStorage.setItem('prefs:v1', JSON.stringify({
|
||||
theme: user.preferences.theme,
|
||||
notifications: user.preferences.notifications
|
||||
}))
|
||||
} catch {}
|
||||
}
|
||||
```
|
||||
|
||||
**Always wrap in try-catch:** `getItem()` and `setItem()` throw in incognito/private browsing (Safari, Firefox), when quota exceeded, or when disabled.
|
||||
|
||||
**Benefits:** Schema evolution via versioning, reduced storage size, prevents storing tokens/PII/internal flags.
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
title: Use Passive Event Listeners for Scrolling Performance
|
||||
impact: MEDIUM
|
||||
impactDescription: eliminates scroll delay caused by event listeners
|
||||
tags: client, event-listeners, scrolling, performance, touch, wheel
|
||||
---
|
||||
|
||||
## Use Passive Event Listeners for Scrolling Performance
|
||||
|
||||
Add `{ passive: true }` to touch and wheel event listeners to enable immediate scrolling. Browsers normally wait for listeners to finish to check if `preventDefault()` is called, causing scroll delay.
|
||||
|
||||
**Incorrect:**
|
||||
|
||||
```typescript
|
||||
useEffect(() => {
|
||||
const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
|
||||
const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
|
||||
|
||||
document.addEventListener('touchstart', handleTouch)
|
||||
document.addEventListener('wheel', handleWheel)
|
||||
|
||||
return () => {
|
||||
document.removeEventListener('touchstart', handleTouch)
|
||||
document.removeEventListener('wheel', handleWheel)
|
||||
}
|
||||
}, [])
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```typescript
|
||||
useEffect(() => {
|
||||
const handleTouch = (e: TouchEvent) => console.log(e.touches[0].clientX)
|
||||
const handleWheel = (e: WheelEvent) => console.log(e.deltaY)
|
||||
|
||||
document.addEventListener('touchstart', handleTouch, { passive: true })
|
||||
document.addEventListener('wheel', handleWheel, { passive: true })
|
||||
|
||||
return () => {
|
||||
document.removeEventListener('touchstart', handleTouch)
|
||||
document.removeEventListener('wheel', handleWheel)
|
||||
}
|
||||
}, [])
|
||||
```
|
||||
|
||||
**Use passive when:** tracking/analytics, logging, any listener that doesn't call `preventDefault()`.
|
||||
|
||||
**Don't use passive when:** implementing custom swipe gestures, custom zoom controls, or any listener that needs `preventDefault()`.
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
title: Use SWR for Automatic Deduplication
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: automatic deduplication
|
||||
tags: client, swr, deduplication, data-fetching
|
||||
---
|
||||
|
||||
## Use SWR for Automatic Deduplication
|
||||
|
||||
SWR enables request deduplication, caching, and revalidation across component instances.
|
||||
|
||||
**Incorrect (no deduplication, each instance fetches):**
|
||||
|
||||
```tsx
|
||||
function UserList() {
|
||||
const [users, setUsers] = useState([])
|
||||
useEffect(() => {
|
||||
fetch('/api/users')
|
||||
.then(r => r.json())
|
||||
.then(setUsers)
|
||||
}, [])
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (multiple instances share one request):**
|
||||
|
||||
```tsx
|
||||
import useSWR from 'swr'
|
||||
|
||||
function UserList() {
|
||||
const { data: users } = useSWR('/api/users', fetcher)
|
||||
}
|
||||
```
|
||||
|
||||
**For immutable data:**
|
||||
|
||||
```tsx
|
||||
import { useImmutableSWR } from '@/lib/swr'
|
||||
|
||||
function StaticContent() {
|
||||
const { data } = useImmutableSWR('/api/config', fetcher)
|
||||
}
|
||||
```
|
||||
|
||||
**For mutations:**
|
||||
|
||||
```tsx
|
||||
import { useSWRMutation } from 'swr/mutation'
|
||||
|
||||
function UpdateButton() {
|
||||
const { trigger } = useSWRMutation('/api/user', updateUser)
|
||||
return <button onClick={() => trigger()}>Update</button>
|
||||
}
|
||||
```
|
||||
|
||||
Reference: [https://swr.vercel.app](https://swr.vercel.app)
|
||||
@@ -1,107 +0,0 @@
|
||||
---
|
||||
title: Avoid Layout Thrashing
|
||||
impact: MEDIUM
|
||||
impactDescription: prevents forced synchronous layouts and reduces performance bottlenecks
|
||||
tags: javascript, dom, css, performance, reflow, layout-thrashing
|
||||
---
|
||||
|
||||
## Avoid Layout Thrashing
|
||||
|
||||
Avoid interleaving style writes with layout reads. When you read a layout property (like `offsetWidth`, `getBoundingClientRect()`, or `getComputedStyle()`) between style changes, the browser is forced to trigger a synchronous reflow.
|
||||
|
||||
**This is OK (browser batches style changes):**
|
||||
```typescript
|
||||
function updateElementStyles(element: HTMLElement) {
|
||||
// Each line invalidates style, but browser batches the recalculation
|
||||
element.style.width = '100px'
|
||||
element.style.height = '200px'
|
||||
element.style.backgroundColor = 'blue'
|
||||
element.style.border = '1px solid black'
|
||||
}
|
||||
```
|
||||
|
||||
**Incorrect (interleaved reads and writes force reflows):**
|
||||
```typescript
|
||||
function layoutThrashing(element: HTMLElement) {
|
||||
element.style.width = '100px'
|
||||
const width = element.offsetWidth // Forces reflow
|
||||
element.style.height = '200px'
|
||||
const height = element.offsetHeight // Forces another reflow
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (batch writes, then read once):**
|
||||
```typescript
|
||||
function updateElementStyles(element: HTMLElement) {
|
||||
// Batch all writes together
|
||||
element.style.width = '100px'
|
||||
element.style.height = '200px'
|
||||
element.style.backgroundColor = 'blue'
|
||||
element.style.border = '1px solid black'
|
||||
|
||||
// Read after all writes are done (single reflow)
|
||||
const { width, height } = element.getBoundingClientRect()
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (batch reads, then writes):**
|
||||
```typescript
|
||||
function avoidThrashing(element: HTMLElement) {
|
||||
// Read phase - all layout queries first
|
||||
const rect1 = element.getBoundingClientRect()
|
||||
const offsetWidth = element.offsetWidth
|
||||
const offsetHeight = element.offsetHeight
|
||||
|
||||
// Write phase - all style changes after
|
||||
element.style.width = '100px'
|
||||
element.style.height = '200px'
|
||||
}
|
||||
```
|
||||
|
||||
**Better: use CSS classes**
|
||||
```css
|
||||
.highlighted-box {
|
||||
width: 100px;
|
||||
height: 200px;
|
||||
background-color: blue;
|
||||
border: 1px solid black;
|
||||
}
|
||||
```
|
||||
```typescript
|
||||
function updateElementStyles(element: HTMLElement) {
|
||||
element.classList.add('highlighted-box')
|
||||
|
||||
const { width, height } = element.getBoundingClientRect()
|
||||
}
|
||||
```
|
||||
|
||||
**React example:**
|
||||
```tsx
|
||||
// Incorrect: interleaving style changes with layout queries
|
||||
function Box({ isHighlighted }: { isHighlighted: boolean }) {
|
||||
const ref = useRef<HTMLDivElement>(null)
|
||||
|
||||
useEffect(() => {
|
||||
if (ref.current && isHighlighted) {
|
||||
ref.current.style.width = '100px'
|
||||
const width = ref.current.offsetWidth // Forces layout
|
||||
ref.current.style.height = '200px'
|
||||
}
|
||||
}, [isHighlighted])
|
||||
|
||||
return <div ref={ref}>Content</div>
|
||||
}
|
||||
|
||||
// Correct: toggle class
|
||||
function Box({ isHighlighted }: { isHighlighted: boolean }) {
|
||||
return (
|
||||
<div className={isHighlighted ? 'highlighted-box' : ''}>
|
||||
Content
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Prefer CSS classes over inline styles when possible. CSS files are cached by the browser, and classes provide better separation of concerns and are easier to maintain.
|
||||
|
||||
See [this gist](https://gist.github.com/paulirish/5d52fb081b3570c81e3a) and [CSS Triggers](https://csstriggers.com/) for more information on layout-forcing operations.
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
title: Cache Repeated Function Calls
|
||||
impact: MEDIUM
|
||||
impactDescription: avoid redundant computation
|
||||
tags: javascript, cache, memoization, performance
|
||||
---
|
||||
|
||||
## Cache Repeated Function Calls
|
||||
|
||||
Use a module-level Map to cache function results when the same function is called repeatedly with the same inputs during render.
|
||||
|
||||
**Incorrect (redundant computation):**
|
||||
|
||||
```typescript
|
||||
function ProjectList({ projects }: { projects: Project[] }) {
|
||||
return (
|
||||
<div>
|
||||
{projects.map(project => {
|
||||
// slugify() called 100+ times for same project names
|
||||
const slug = slugify(project.name)
|
||||
|
||||
return <ProjectCard key={project.id} slug={slug} />
|
||||
})}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (cached results):**
|
||||
|
||||
```typescript
|
||||
// Module-level cache
|
||||
const slugifyCache = new Map<string, string>()
|
||||
|
||||
function cachedSlugify(text: string): string {
|
||||
if (slugifyCache.has(text)) {
|
||||
return slugifyCache.get(text)!
|
||||
}
|
||||
const result = slugify(text)
|
||||
slugifyCache.set(text, result)
|
||||
return result
|
||||
}
|
||||
|
||||
function ProjectList({ projects }: { projects: Project[] }) {
|
||||
return (
|
||||
<div>
|
||||
{projects.map(project => {
|
||||
// Computed only once per unique project name
|
||||
const slug = cachedSlugify(project.name)
|
||||
|
||||
return <ProjectCard key={project.id} slug={slug} />
|
||||
})}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Simpler pattern for single-value functions:**
|
||||
|
||||
```typescript
|
||||
let isLoggedInCache: boolean | null = null
|
||||
|
||||
function isLoggedIn(): boolean {
|
||||
if (isLoggedInCache !== null) {
|
||||
return isLoggedInCache
|
||||
}
|
||||
|
||||
isLoggedInCache = document.cookie.includes('auth=')
|
||||
return isLoggedInCache
|
||||
}
|
||||
|
||||
// Clear cache when auth changes
|
||||
function onAuthChange() {
|
||||
isLoggedInCache = null
|
||||
}
|
||||
```
|
||||
|
||||
Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
|
||||
|
||||
Reference: [How we made the Vercel Dashboard twice as fast](https://vercel.com/blog/how-we-made-the-vercel-dashboard-twice-as-fast)
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
title: Cache Property Access in Loops
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: reduces lookups
|
||||
tags: javascript, loops, optimization, caching
|
||||
---
|
||||
|
||||
## Cache Property Access in Loops
|
||||
|
||||
Cache object property lookups in hot paths.
|
||||
|
||||
**Incorrect (3 lookups × N iterations):**
|
||||
|
||||
```typescript
|
||||
for (let i = 0; i < arr.length; i++) {
|
||||
process(obj.config.settings.value)
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (1 lookup total):**
|
||||
|
||||
```typescript
|
||||
const value = obj.config.settings.value
|
||||
const len = arr.length
|
||||
for (let i = 0; i < len; i++) {
|
||||
process(value)
|
||||
}
|
||||
```
|
||||
@@ -1,70 +0,0 @@
|
||||
---
|
||||
title: Cache Storage API Calls
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: reduces expensive I/O
|
||||
tags: javascript, localStorage, storage, caching, performance
|
||||
---
|
||||
|
||||
## Cache Storage API Calls
|
||||
|
||||
`localStorage`, `sessionStorage`, and `document.cookie` are synchronous and expensive. Cache reads in memory.
|
||||
|
||||
**Incorrect (reads storage on every call):**
|
||||
|
||||
```typescript
|
||||
function getTheme() {
|
||||
return localStorage.getItem('theme') ?? 'light'
|
||||
}
|
||||
// Called 10 times = 10 storage reads
|
||||
```
|
||||
|
||||
**Correct (Map cache):**
|
||||
|
||||
```typescript
|
||||
const storageCache = new Map<string, string | null>()
|
||||
|
||||
function getLocalStorage(key: string) {
|
||||
if (!storageCache.has(key)) {
|
||||
storageCache.set(key, localStorage.getItem(key))
|
||||
}
|
||||
return storageCache.get(key)
|
||||
}
|
||||
|
||||
function setLocalStorage(key: string, value: string) {
|
||||
localStorage.setItem(key, value)
|
||||
storageCache.set(key, value) // keep cache in sync
|
||||
}
|
||||
```
|
||||
|
||||
Use a Map (not a hook) so it works everywhere: utilities, event handlers, not just React components.
|
||||
|
||||
**Cookie caching:**
|
||||
|
||||
```typescript
|
||||
let cookieCache: Record<string, string> | null = null
|
||||
|
||||
function getCookie(name: string) {
|
||||
if (!cookieCache) {
|
||||
cookieCache = Object.fromEntries(
|
||||
document.cookie.split('; ').map(c => c.split('='))
|
||||
)
|
||||
}
|
||||
return cookieCache[name]
|
||||
}
|
||||
```
|
||||
|
||||
**Important (invalidate on external changes):**
|
||||
|
||||
If storage can change externally (another tab, server-set cookies), invalidate cache:
|
||||
|
||||
```typescript
|
||||
window.addEventListener('storage', (e) => {
|
||||
if (e.key) storageCache.delete(e.key)
|
||||
})
|
||||
|
||||
document.addEventListener('visibilitychange', () => {
|
||||
if (document.visibilityState === 'visible') {
|
||||
storageCache.clear()
|
||||
}
|
||||
})
|
||||
```
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: Combine Multiple Array Iterations
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: reduces iterations
|
||||
tags: javascript, arrays, loops, performance
|
||||
---
|
||||
|
||||
## Combine Multiple Array Iterations
|
||||
|
||||
Multiple `.filter()` or `.map()` calls iterate the array multiple times. Combine into one loop.
|
||||
|
||||
**Incorrect (3 iterations):**
|
||||
|
||||
```typescript
|
||||
const admins = users.filter(u => u.isAdmin)
|
||||
const testers = users.filter(u => u.isTester)
|
||||
const inactive = users.filter(u => !u.isActive)
|
||||
```
|
||||
|
||||
**Correct (1 iteration):**
|
||||
|
||||
```typescript
|
||||
const admins: User[] = []
|
||||
const testers: User[] = []
|
||||
const inactive: User[] = []
|
||||
|
||||
for (const user of users) {
|
||||
if (user.isAdmin) admins.push(user)
|
||||
if (user.isTester) testers.push(user)
|
||||
if (!user.isActive) inactive.push(user)
|
||||
}
|
||||
```
|
||||
@@ -1,50 +0,0 @@
|
||||
---
|
||||
title: Early Return from Functions
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: avoids unnecessary computation
|
||||
tags: javascript, functions, optimization, early-return
|
||||
---
|
||||
|
||||
## Early Return from Functions
|
||||
|
||||
Return early when result is determined to skip unnecessary processing.
|
||||
|
||||
**Incorrect (processes all items even after finding answer):**
|
||||
|
||||
```typescript
|
||||
function validateUsers(users: User[]) {
|
||||
let hasError = false
|
||||
let errorMessage = ''
|
||||
|
||||
for (const user of users) {
|
||||
if (!user.email) {
|
||||
hasError = true
|
||||
errorMessage = 'Email required'
|
||||
}
|
||||
if (!user.name) {
|
||||
hasError = true
|
||||
errorMessage = 'Name required'
|
||||
}
|
||||
// Continues checking all users even after error found
|
||||
}
|
||||
|
||||
return hasError ? { valid: false, error: errorMessage } : { valid: true }
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (returns immediately on first error):**
|
||||
|
||||
```typescript
|
||||
function validateUsers(users: User[]) {
|
||||
for (const user of users) {
|
||||
if (!user.email) {
|
||||
return { valid: false, error: 'Email required' }
|
||||
}
|
||||
if (!user.name) {
|
||||
return { valid: false, error: 'Name required' }
|
||||
}
|
||||
}
|
||||
|
||||
return { valid: true }
|
||||
}
|
||||
```
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
title: Hoist RegExp Creation
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: avoids recreation
|
||||
tags: javascript, regexp, optimization, memoization
|
||||
---
|
||||
|
||||
## Hoist RegExp Creation
|
||||
|
||||
Don't create RegExp inside render. Hoist to module scope or memoize with `useMemo()`.
|
||||
|
||||
**Incorrect (new RegExp every render):**
|
||||
|
||||
```tsx
|
||||
function Highlighter({ text, query }: Props) {
|
||||
const regex = new RegExp(`(${query})`, 'gi')
|
||||
const parts = text.split(regex)
|
||||
return <>{parts.map((part, i) => ...)}</>
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (memoize or hoist):**
|
||||
|
||||
```tsx
|
||||
const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
|
||||
|
||||
function Highlighter({ text, query }: Props) {
|
||||
const regex = useMemo(
|
||||
() => new RegExp(`(${escapeRegex(query)})`, 'gi'),
|
||||
[query]
|
||||
)
|
||||
const parts = text.split(regex)
|
||||
return <>{parts.map((part, i) => ...)}</>
|
||||
}
|
||||
```
|
||||
|
||||
**Warning (global regex has mutable state):**
|
||||
|
||||
Global regex (`/g`) has mutable `lastIndex` state:
|
||||
|
||||
```typescript
|
||||
const regex = /foo/g
|
||||
regex.test('foo') // true, lastIndex = 3
|
||||
regex.test('foo') // false, lastIndex = 0
|
||||
```
|
||||
@@ -1,37 +0,0 @@
|
||||
---
|
||||
title: Build Index Maps for Repeated Lookups
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: 1M ops to 2K ops
|
||||
tags: javascript, map, indexing, optimization, performance
|
||||
---
|
||||
|
||||
## Build Index Maps for Repeated Lookups
|
||||
|
||||
Multiple `.find()` calls by the same key should use a Map.
|
||||
|
||||
**Incorrect (O(n) per lookup):**
|
||||
|
||||
```typescript
|
||||
function processOrders(orders: Order[], users: User[]) {
|
||||
return orders.map(order => ({
|
||||
...order,
|
||||
user: users.find(u => u.id === order.userId)
|
||||
}))
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (O(1) per lookup):**
|
||||
|
||||
```typescript
|
||||
function processOrders(orders: Order[], users: User[]) {
|
||||
const userById = new Map(users.map(u => [u.id, u]))
|
||||
|
||||
return orders.map(order => ({
|
||||
...order,
|
||||
user: userById.get(order.userId)
|
||||
}))
|
||||
}
|
||||
```
|
||||
|
||||
Build map once (O(n)), then all lookups are O(1).
|
||||
For 1000 orders × 1000 users: 1M ops → 2K ops.
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
title: Early Length Check for Array Comparisons
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: avoids expensive operations when lengths differ
|
||||
tags: javascript, arrays, performance, optimization, comparison
|
||||
---
|
||||
|
||||
## Early Length Check for Array Comparisons
|
||||
|
||||
When comparing arrays with expensive operations (sorting, deep equality, serialization), check lengths first. If lengths differ, the arrays cannot be equal.
|
||||
|
||||
In real-world applications, this optimization is especially valuable when the comparison runs in hot paths (event handlers, render loops).
|
||||
|
||||
**Incorrect (always runs expensive comparison):**
|
||||
|
||||
```typescript
|
||||
function hasChanges(current: string[], original: string[]) {
|
||||
// Always sorts and joins, even when lengths differ
|
||||
return current.sort().join() !== original.sort().join()
|
||||
}
|
||||
```
|
||||
|
||||
Two O(n log n) sorts run even when `current.length` is 5 and `original.length` is 100. There is also overhead of joining the arrays and comparing the strings.
|
||||
|
||||
**Correct (O(1) length check first):**
|
||||
|
||||
```typescript
|
||||
function hasChanges(current: string[], original: string[]) {
|
||||
// Early return if lengths differ
|
||||
if (current.length !== original.length) {
|
||||
return true
|
||||
}
|
||||
// Only sort when lengths match
|
||||
const currentSorted = current.toSorted()
|
||||
const originalSorted = original.toSorted()
|
||||
for (let i = 0; i < currentSorted.length; i++) {
|
||||
if (currentSorted[i] !== originalSorted[i]) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
```
|
||||
|
||||
This new approach is more efficient because:
|
||||
- It avoids the overhead of sorting and joining the arrays when lengths differ
|
||||
- It avoids consuming memory for the joined strings (especially important for large arrays)
|
||||
- It avoids mutating the original arrays
|
||||
- It returns early when a difference is found
|
||||
@@ -1,82 +0,0 @@
|
||||
---
|
||||
title: Use Loop for Min/Max Instead of Sort
|
||||
impact: LOW
|
||||
impactDescription: O(n) instead of O(n log n)
|
||||
tags: javascript, arrays, performance, sorting, algorithms
|
||||
---
|
||||
|
||||
## Use Loop for Min/Max Instead of Sort
|
||||
|
||||
Finding the smallest or largest element only requires a single pass through the array. Sorting is wasteful and slower.
|
||||
|
||||
**Incorrect (O(n log n) - sort to find latest):**
|
||||
|
||||
```typescript
|
||||
interface Project {
|
||||
id: string
|
||||
name: string
|
||||
updatedAt: number
|
||||
}
|
||||
|
||||
function getLatestProject(projects: Project[]) {
|
||||
const sorted = [...projects].sort((a, b) => b.updatedAt - a.updatedAt)
|
||||
return sorted[0]
|
||||
}
|
||||
```
|
||||
|
||||
Sorts the entire array just to find the maximum value.
|
||||
|
||||
**Incorrect (O(n log n) - sort for oldest and newest):**
|
||||
|
||||
```typescript
|
||||
function getOldestAndNewest(projects: Project[]) {
|
||||
const sorted = [...projects].sort((a, b) => a.updatedAt - b.updatedAt)
|
||||
return { oldest: sorted[0], newest: sorted[sorted.length - 1] }
|
||||
}
|
||||
```
|
||||
|
||||
Still sorts unnecessarily when only min/max are needed.
|
||||
|
||||
**Correct (O(n) - single loop):**
|
||||
|
||||
```typescript
|
||||
function getLatestProject(projects: Project[]) {
|
||||
if (projects.length === 0) return null
|
||||
|
||||
let latest = projects[0]
|
||||
|
||||
for (let i = 1; i < projects.length; i++) {
|
||||
if (projects[i].updatedAt > latest.updatedAt) {
|
||||
latest = projects[i]
|
||||
}
|
||||
}
|
||||
|
||||
return latest
|
||||
}
|
||||
|
||||
function getOldestAndNewest(projects: Project[]) {
|
||||
if (projects.length === 0) return { oldest: null, newest: null }
|
||||
|
||||
let oldest = projects[0]
|
||||
let newest = projects[0]
|
||||
|
||||
for (let i = 1; i < projects.length; i++) {
|
||||
if (projects[i].updatedAt < oldest.updatedAt) oldest = projects[i]
|
||||
if (projects[i].updatedAt > newest.updatedAt) newest = projects[i]
|
||||
}
|
||||
|
||||
return { oldest, newest }
|
||||
}
|
||||
```
|
||||
|
||||
Single pass through the array, no copying, no sorting.
|
||||
|
||||
**Alternative (Math.min/Math.max for small arrays):**
|
||||
|
||||
```typescript
|
||||
const numbers = [5, 2, 8, 1, 9]
|
||||
const min = Math.min(...numbers)
|
||||
const max = Math.max(...numbers)
|
||||
```
|
||||
|
||||
This works for small arrays, but can be slower or just throw an error for very large arrays due to spread operator limitations. Maximal array length is approximately 124000 in Chrome 143 and 638000 in Safari 18; exact numbers may vary - see [the fiddle](https://jsfiddle.net/qw1jabsx/4/). Use the loop approach for reliability.
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
title: Use Set/Map for O(1) Lookups
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: O(n) to O(1)
|
||||
tags: javascript, set, map, data-structures, performance
|
||||
---
|
||||
|
||||
## Use Set/Map for O(1) Lookups
|
||||
|
||||
Convert arrays to Set/Map for repeated membership checks.
|
||||
|
||||
**Incorrect (O(n) per check):**
|
||||
|
||||
```typescript
|
||||
const allowedIds = ['a', 'b', 'c', ...]
|
||||
items.filter(item => allowedIds.includes(item.id))
|
||||
```
|
||||
|
||||
**Correct (O(1) per check):**
|
||||
|
||||
```typescript
|
||||
const allowedIds = new Set(['a', 'b', 'c', ...])
|
||||
items.filter(item => allowedIds.has(item.id))
|
||||
```
|
||||
@@ -1,57 +0,0 @@
|
||||
---
|
||||
title: Use toSorted() Instead of sort() for Immutability
|
||||
impact: MEDIUM-HIGH
|
||||
impactDescription: prevents mutation bugs in React state
|
||||
tags: javascript, arrays, immutability, react, state, mutation
|
||||
---
|
||||
|
||||
## Use toSorted() Instead of sort() for Immutability
|
||||
|
||||
`.sort()` mutates the array in place, which can cause bugs with React state and props. Use `.toSorted()` to create a new sorted array without mutation.
|
||||
|
||||
**Incorrect (mutates original array):**
|
||||
|
||||
```typescript
|
||||
function UserList({ users }: { users: User[] }) {
|
||||
// Mutates the users prop array!
|
||||
const sorted = useMemo(
|
||||
() => users.sort((a, b) => a.name.localeCompare(b.name)),
|
||||
[users]
|
||||
)
|
||||
return <div>{sorted.map(renderUser)}</div>
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (creates new array):**
|
||||
|
||||
```typescript
|
||||
function UserList({ users }: { users: User[] }) {
|
||||
// Creates new sorted array, original unchanged
|
||||
const sorted = useMemo(
|
||||
() => users.toSorted((a, b) => a.name.localeCompare(b.name)),
|
||||
[users]
|
||||
)
|
||||
return <div>{sorted.map(renderUser)}</div>
|
||||
}
|
||||
```
|
||||
|
||||
**Why this matters in React:**
|
||||
|
||||
1. Props/state mutations break React's immutability model - React expects props and state to be treated as read-only
|
||||
2. Causes stale closure bugs - Mutating arrays inside closures (callbacks, effects) can lead to unexpected behavior
|
||||
|
||||
**Browser support (fallback for older browsers):**
|
||||
|
||||
`.toSorted()` is available in all modern browsers (Chrome 110+, Safari 16+, Firefox 115+, Node.js 20+). For older environments, use spread operator:
|
||||
|
||||
```typescript
|
||||
// Fallback for older browsers
|
||||
const sorted = [...items].sort((a, b) => a.value - b.value)
|
||||
```
|
||||
|
||||
**Other immutable array methods:**
|
||||
|
||||
- `.toSorted()` - immutable sort
|
||||
- `.toReversed()` - immutable reverse
|
||||
- `.toSpliced()` - immutable splice
|
||||
- `.with()` - immutable element replacement
|
||||
@@ -1,26 +0,0 @@
|
||||
---
|
||||
title: Use Activity Component for Show/Hide
|
||||
impact: MEDIUM
|
||||
impactDescription: preserves state/DOM
|
||||
tags: rendering, activity, visibility, state-preservation
|
||||
---
|
||||
|
||||
## Use Activity Component for Show/Hide
|
||||
|
||||
Use React's `<Activity>` to preserve state/DOM for expensive components that frequently toggle visibility.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```tsx
|
||||
import { Activity } from 'react'
|
||||
|
||||
function Dropdown({ isOpen }: Props) {
|
||||
return (
|
||||
<Activity mode={isOpen ? 'visible' : 'hidden'}>
|
||||
<ExpensiveMenu />
|
||||
</Activity>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Avoids expensive re-renders and state loss.
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
title: Animate SVG Wrapper Instead of SVG Element
|
||||
impact: LOW
|
||||
impactDescription: enables hardware acceleration
|
||||
tags: rendering, svg, css, animation, performance
|
||||
---
|
||||
|
||||
## Animate SVG Wrapper Instead of SVG Element
|
||||
|
||||
Many browsers don't have hardware acceleration for CSS3 animations on SVG elements. Wrap SVG in a `<div>` and animate the wrapper instead.
|
||||
|
||||
**Incorrect (animating SVG directly - no hardware acceleration):**
|
||||
|
||||
```tsx
|
||||
function LoadingSpinner() {
|
||||
return (
|
||||
<svg
|
||||
className="animate-spin"
|
||||
width="24"
|
||||
height="24"
|
||||
viewBox="0 0 24 24"
|
||||
>
|
||||
<circle cx="12" cy="12" r="10" stroke="currentColor" />
|
||||
</svg>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (animating wrapper div - hardware accelerated):**
|
||||
|
||||
```tsx
|
||||
function LoadingSpinner() {
|
||||
return (
|
||||
<div className="animate-spin">
|
||||
<svg
|
||||
width="24"
|
||||
height="24"
|
||||
viewBox="0 0 24 24"
|
||||
>
|
||||
<circle cx="12" cy="12" r="10" stroke="currentColor" />
|
||||
</svg>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
This applies to all CSS transforms and transitions (`transform`, `opacity`, `translate`, `scale`, `rotate`). The wrapper div allows browsers to use GPU acceleration for smoother animations.
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Use Explicit Conditional Rendering
|
||||
impact: LOW
|
||||
impactDescription: prevents rendering 0 or NaN
|
||||
tags: rendering, conditional, jsx, falsy-values
|
||||
---
|
||||
|
||||
## Use Explicit Conditional Rendering
|
||||
|
||||
Use explicit ternary operators (`? :`) instead of `&&` for conditional rendering when the condition can be `0`, `NaN`, or other falsy values that render.
|
||||
|
||||
**Incorrect (renders "0" when count is 0):**
|
||||
|
||||
```tsx
|
||||
function Badge({ count }: { count: number }) {
|
||||
return (
|
||||
<div>
|
||||
{count && <span className="badge">{count}</span>}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// When count = 0, renders: <div>0</div>
|
||||
// When count = 5, renders: <div><span class="badge">5</span></div>
|
||||
```
|
||||
|
||||
**Correct (renders nothing when count is 0):**
|
||||
|
||||
```tsx
|
||||
function Badge({ count }: { count: number }) {
|
||||
return (
|
||||
<div>
|
||||
{count > 0 ? <span className="badge">{count}</span> : null}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// When count = 0, renders: <div></div>
|
||||
// When count = 5, renders: <div><span class="badge">5</span></div>
|
||||
```
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: CSS content-visibility for Long Lists
|
||||
impact: HIGH
|
||||
impactDescription: faster initial render
|
||||
tags: rendering, css, content-visibility, long-lists
|
||||
---
|
||||
|
||||
## CSS content-visibility for Long Lists
|
||||
|
||||
Apply `content-visibility: auto` to defer off-screen rendering.
|
||||
|
||||
**CSS:**
|
||||
|
||||
```css
|
||||
.message-item {
|
||||
content-visibility: auto;
|
||||
contain-intrinsic-size: 0 80px;
|
||||
}
|
||||
```
|
||||
|
||||
**Example:**
|
||||
|
||||
```tsx
|
||||
function MessageList({ messages }: { messages: Message[] }) {
|
||||
return (
|
||||
<div className="overflow-y-auto h-screen">
|
||||
{messages.map(msg => (
|
||||
<div key={msg.id} className="message-item">
|
||||
<Avatar user={msg.author} />
|
||||
<div>{msg.content}</div>
|
||||
</div>
|
||||
))}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
For 1000 messages, browser skips layout/paint for ~990 off-screen items (10× faster initial render).
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
title: Hoist Static JSX Elements
|
||||
impact: LOW
|
||||
impactDescription: avoids re-creation
|
||||
tags: rendering, jsx, static, optimization
|
||||
---
|
||||
|
||||
## Hoist Static JSX Elements
|
||||
|
||||
Extract static JSX outside components to avoid re-creation.
|
||||
|
||||
**Incorrect (recreates element every render):**
|
||||
|
||||
```tsx
|
||||
function LoadingSkeleton() {
|
||||
return <div className="animate-pulse h-20 bg-gray-200" />
|
||||
}
|
||||
|
||||
function Container() {
|
||||
return (
|
||||
<div>
|
||||
{loading && <LoadingSkeleton />}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (reuses same element):**
|
||||
|
||||
```tsx
|
||||
const loadingSkeleton = (
|
||||
<div className="animate-pulse h-20 bg-gray-200" />
|
||||
)
|
||||
|
||||
function Container() {
|
||||
return (
|
||||
<div>
|
||||
{loading && loadingSkeleton}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
This is especially helpful for large and static SVG nodes, which can be expensive to recreate on every render.
|
||||
|
||||
**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler automatically hoists static JSX elements and optimizes component re-renders, making manual hoisting unnecessary.
|
||||
@@ -1,82 +0,0 @@
|
||||
---
|
||||
title: Prevent Hydration Mismatch Without Flickering
|
||||
impact: MEDIUM
|
||||
impactDescription: avoids visual flicker and hydration errors
|
||||
tags: rendering, ssr, hydration, localStorage, flicker
|
||||
---
|
||||
|
||||
## Prevent Hydration Mismatch Without Flickering
|
||||
|
||||
When rendering content that depends on client-side storage (localStorage, cookies), avoid both SSR breakage and post-hydration flickering by injecting a synchronous script that updates the DOM before React hydrates.
|
||||
|
||||
**Incorrect (breaks SSR):**
|
||||
|
||||
```tsx
|
||||
function ThemeWrapper({ children }: { children: ReactNode }) {
|
||||
// localStorage is not available on server - throws error
|
||||
const theme = localStorage.getItem('theme') || 'light'
|
||||
|
||||
return (
|
||||
<div className={theme}>
|
||||
{children}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Server-side rendering will fail because `localStorage` is undefined.
|
||||
|
||||
**Incorrect (visual flickering):**
|
||||
|
||||
```tsx
|
||||
function ThemeWrapper({ children }: { children: ReactNode }) {
|
||||
const [theme, setTheme] = useState('light')
|
||||
|
||||
useEffect(() => {
|
||||
// Runs after hydration - causes visible flash
|
||||
const stored = localStorage.getItem('theme')
|
||||
if (stored) {
|
||||
setTheme(stored)
|
||||
}
|
||||
}, [])
|
||||
|
||||
return (
|
||||
<div className={theme}>
|
||||
{children}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
Component first renders with default value (`light`), then updates after hydration, causing a visible flash of incorrect content.
|
||||
|
||||
**Correct (no flicker, no hydration mismatch):**
|
||||
|
||||
```tsx
|
||||
function ThemeWrapper({ children }: { children: ReactNode }) {
|
||||
return (
|
||||
<>
|
||||
<div id="theme-wrapper">
|
||||
{children}
|
||||
</div>
|
||||
<script
|
||||
dangerouslySetInnerHTML={{
|
||||
__html: `
|
||||
(function() {
|
||||
try {
|
||||
var theme = localStorage.getItem('theme') || 'light';
|
||||
var el = document.getElementById('theme-wrapper');
|
||||
if (el) el.className = theme;
|
||||
} catch (e) {}
|
||||
})();
|
||||
`,
|
||||
}}
|
||||
/>
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
The inline script executes synchronously before showing the element, ensuring the DOM already has the correct value. No flickering, no hydration mismatch.
|
||||
|
||||
This pattern is especially useful for theme toggles, user preferences, authentication states, and any client-only data that should render immediately without flashing default values.
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: Suppress Expected Hydration Mismatches
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: avoids noisy hydration warnings for known differences
|
||||
tags: rendering, hydration, ssr, nextjs
|
||||
---
|
||||
|
||||
## Suppress Expected Hydration Mismatches
|
||||
|
||||
In SSR frameworks (e.g., Next.js), some values are intentionally different on server vs client (random IDs, dates, locale/timezone formatting). For these *expected* mismatches, wrap the dynamic text in an element with `suppressHydrationWarning` to prevent noisy warnings. Do not use this to hide real bugs. Don’t overuse it.
|
||||
|
||||
**Incorrect (known mismatch warnings):**
|
||||
|
||||
```tsx
|
||||
function Timestamp() {
|
||||
return <span>{new Date().toLocaleString()}</span>
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (suppress expected mismatch only):**
|
||||
|
||||
```tsx
|
||||
function Timestamp() {
|
||||
return (
|
||||
<span suppressHydrationWarning>
|
||||
{new Date().toLocaleString()}
|
||||
</span>
|
||||
)
|
||||
}
|
||||
```
|
||||
@@ -1,28 +0,0 @@
|
||||
---
|
||||
title: Optimize SVG Precision
|
||||
impact: LOW
|
||||
impactDescription: reduces file size
|
||||
tags: rendering, svg, optimization, svgo
|
||||
---
|
||||
|
||||
## Optimize SVG Precision
|
||||
|
||||
Reduce SVG coordinate precision to decrease file size. The optimal precision depends on the viewBox size, but in general reducing precision should be considered.
|
||||
|
||||
**Incorrect (excessive precision):**
|
||||
|
||||
```svg
|
||||
<path d="M 10.293847 20.847362 L 30.938472 40.192837" />
|
||||
```
|
||||
|
||||
**Correct (1 decimal place):**
|
||||
|
||||
```svg
|
||||
<path d="M 10.3 20.8 L 30.9 40.2" />
|
||||
```
|
||||
|
||||
**Automate with SVGO:**
|
||||
|
||||
```bash
|
||||
npx svgo --precision=1 --multipass icon.svg
|
||||
```
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
title: Use useTransition Over Manual Loading States
|
||||
impact: LOW
|
||||
impactDescription: reduces re-renders and improves code clarity
|
||||
tags: rendering, transitions, useTransition, loading, state
|
||||
---
|
||||
|
||||
## Use useTransition Over Manual Loading States
|
||||
|
||||
Use `useTransition` instead of manual `useState` for loading states. This provides built-in `isPending` state and automatically manages transitions.
|
||||
|
||||
**Incorrect (manual loading state):**
|
||||
|
||||
```tsx
|
||||
function SearchResults() {
|
||||
const [query, setQuery] = useState('')
|
||||
const [results, setResults] = useState([])
|
||||
const [isLoading, setIsLoading] = useState(false)
|
||||
|
||||
const handleSearch = async (value: string) => {
|
||||
setIsLoading(true)
|
||||
setQuery(value)
|
||||
const data = await fetchResults(value)
|
||||
setResults(data)
|
||||
setIsLoading(false)
|
||||
}
|
||||
|
||||
return (
|
||||
<>
|
||||
<input onChange={(e) => handleSearch(e.target.value)} />
|
||||
{isLoading && <Spinner />}
|
||||
<ResultsList results={results} />
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (useTransition with built-in pending state):**
|
||||
|
||||
```tsx
|
||||
import { useTransition, useState } from 'react'
|
||||
|
||||
function SearchResults() {
|
||||
const [query, setQuery] = useState('')
|
||||
const [results, setResults] = useState([])
|
||||
const [isPending, startTransition] = useTransition()
|
||||
|
||||
const handleSearch = (value: string) => {
|
||||
setQuery(value) // Update input immediately
|
||||
|
||||
startTransition(async () => {
|
||||
// Fetch and update results
|
||||
const data = await fetchResults(value)
|
||||
setResults(data)
|
||||
})
|
||||
}
|
||||
|
||||
return (
|
||||
<>
|
||||
<input onChange={(e) => handleSearch(e.target.value)} />
|
||||
{isPending && <Spinner />}
|
||||
<ResultsList results={results} />
|
||||
</>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- **Automatic pending state**: No need to manually manage `setIsLoading(true/false)`
|
||||
- **Error resilience**: Pending state correctly resets even if the transition throws
|
||||
- **Better responsiveness**: Keeps the UI responsive during updates
|
||||
- **Interrupt handling**: New transitions automatically cancel pending ones
|
||||
|
||||
Reference: [useTransition](https://react.dev/reference/react/useTransition)
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: Defer State Reads to Usage Point
|
||||
impact: MEDIUM
|
||||
impactDescription: avoids unnecessary subscriptions
|
||||
tags: rerender, searchParams, localStorage, optimization
|
||||
---
|
||||
|
||||
## Defer State Reads to Usage Point
|
||||
|
||||
Don't subscribe to dynamic state (searchParams, localStorage) if you only read it inside callbacks.
|
||||
|
||||
**Incorrect (subscribes to all searchParams changes):**
|
||||
|
||||
```tsx
|
||||
function ShareButton({ chatId }: { chatId: string }) {
|
||||
const searchParams = useSearchParams()
|
||||
|
||||
const handleShare = () => {
|
||||
const ref = searchParams.get('ref')
|
||||
shareChat(chatId, { ref })
|
||||
}
|
||||
|
||||
return <button onClick={handleShare}>Share</button>
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (reads on demand, no subscription):**
|
||||
|
||||
```tsx
|
||||
function ShareButton({ chatId }: { chatId: string }) {
|
||||
const handleShare = () => {
|
||||
const params = new URLSearchParams(window.location.search)
|
||||
const ref = params.get('ref')
|
||||
shareChat(chatId, { ref })
|
||||
}
|
||||
|
||||
return <button onClick={handleShare}>Share</button>
|
||||
}
|
||||
```
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
title: Narrow Effect Dependencies
|
||||
impact: LOW
|
||||
impactDescription: minimizes effect re-runs
|
||||
tags: rerender, useEffect, dependencies, optimization
|
||||
---
|
||||
|
||||
## Narrow Effect Dependencies
|
||||
|
||||
Specify primitive dependencies instead of objects to minimize effect re-runs.
|
||||
|
||||
**Incorrect (re-runs on any user field change):**
|
||||
|
||||
```tsx
|
||||
useEffect(() => {
|
||||
console.log(user.id)
|
||||
}, [user])
|
||||
```
|
||||
|
||||
**Correct (re-runs only when id changes):**
|
||||
|
||||
```tsx
|
||||
useEffect(() => {
|
||||
console.log(user.id)
|
||||
}, [user.id])
|
||||
```
|
||||
|
||||
**For derived state, compute outside effect:**
|
||||
|
||||
```tsx
|
||||
// Incorrect: runs on width=767, 766, 765...
|
||||
useEffect(() => {
|
||||
if (width < 768) {
|
||||
enableMobileMode()
|
||||
}
|
||||
}, [width])
|
||||
|
||||
// Correct: runs only on boolean transition
|
||||
const isMobile = width < 768
|
||||
useEffect(() => {
|
||||
if (isMobile) {
|
||||
enableMobileMode()
|
||||
}
|
||||
}, [isMobile])
|
||||
```
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Calculate Derived State During Rendering
|
||||
impact: MEDIUM
|
||||
impactDescription: avoids redundant renders and state drift
|
||||
tags: rerender, derived-state, useEffect, state
|
||||
---
|
||||
|
||||
## Calculate Derived State During Rendering
|
||||
|
||||
If a value can be computed from current props/state, do not store it in state or update it in an effect. Derive it during render to avoid extra renders and state drift. Do not set state in effects solely in response to prop changes; prefer derived values or keyed resets instead.
|
||||
|
||||
**Incorrect (redundant state and effect):**
|
||||
|
||||
```tsx
|
||||
function Form() {
|
||||
const [firstName, setFirstName] = useState('First')
|
||||
const [lastName, setLastName] = useState('Last')
|
||||
const [fullName, setFullName] = useState('')
|
||||
|
||||
useEffect(() => {
|
||||
setFullName(firstName + ' ' + lastName)
|
||||
}, [firstName, lastName])
|
||||
|
||||
return <p>{fullName}</p>
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (derive during render):**
|
||||
|
||||
```tsx
|
||||
function Form() {
|
||||
const [firstName, setFirstName] = useState('First')
|
||||
const [lastName, setLastName] = useState('Last')
|
||||
const fullName = firstName + ' ' + lastName
|
||||
|
||||
return <p>{fullName}</p>
|
||||
}
|
||||
```
|
||||
|
||||
References: [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect)
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
title: Subscribe to Derived State
|
||||
impact: MEDIUM
|
||||
impactDescription: reduces re-render frequency
|
||||
tags: rerender, derived-state, media-query, optimization
|
||||
---
|
||||
|
||||
## Subscribe to Derived State
|
||||
|
||||
Subscribe to derived boolean state instead of continuous values to reduce re-render frequency.
|
||||
|
||||
**Incorrect (re-renders on every pixel change):**
|
||||
|
||||
```tsx
|
||||
function Sidebar() {
|
||||
const width = useWindowWidth() // updates continuously
|
||||
const isMobile = width < 768
|
||||
return <nav className={isMobile ? 'mobile' : 'desktop'} />
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (re-renders only when boolean changes):**
|
||||
|
||||
```tsx
|
||||
function Sidebar() {
|
||||
const isMobile = useMediaQuery('(max-width: 767px)')
|
||||
return <nav className={isMobile ? 'mobile' : 'desktop'} />
|
||||
}
|
||||
```
|
||||
@@ -1,74 +0,0 @@
|
||||
---
|
||||
title: Use Functional setState Updates
|
||||
impact: MEDIUM
|
||||
impactDescription: prevents stale closures and unnecessary callback recreations
|
||||
tags: react, hooks, useState, useCallback, callbacks, closures
|
||||
---
|
||||
|
||||
## Use Functional setState Updates
|
||||
|
||||
When updating state based on the current state value, use the functional update form of setState instead of directly referencing the state variable. This prevents stale closures, eliminates unnecessary dependencies, and creates stable callback references.
|
||||
|
||||
**Incorrect (requires state as dependency):**
|
||||
|
||||
```tsx
|
||||
function TodoList() {
|
||||
const [items, setItems] = useState(initialItems)
|
||||
|
||||
// Callback must depend on items, recreated on every items change
|
||||
const addItems = useCallback((newItems: Item[]) => {
|
||||
setItems([...items, ...newItems])
|
||||
}, [items]) // ❌ items dependency causes recreations
|
||||
|
||||
// Risk of stale closure if dependency is forgotten
|
||||
const removeItem = useCallback((id: string) => {
|
||||
setItems(items.filter(item => item.id !== id))
|
||||
}, []) // ❌ Missing items dependency - will use stale items!
|
||||
|
||||
return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
|
||||
}
|
||||
```
|
||||
|
||||
The first callback is recreated every time `items` changes, which can cause child components to re-render unnecessarily. The second callback has a stale closure bug—it will always reference the initial `items` value.
|
||||
|
||||
**Correct (stable callbacks, no stale closures):**
|
||||
|
||||
```tsx
|
||||
function TodoList() {
|
||||
const [items, setItems] = useState(initialItems)
|
||||
|
||||
// Stable callback, never recreated
|
||||
const addItems = useCallback((newItems: Item[]) => {
|
||||
setItems(curr => [...curr, ...newItems])
|
||||
}, []) // ✅ No dependencies needed
|
||||
|
||||
// Always uses latest state, no stale closure risk
|
||||
const removeItem = useCallback((id: string) => {
|
||||
setItems(curr => curr.filter(item => item.id !== id))
|
||||
}, []) // ✅ Safe and stable
|
||||
|
||||
return <ItemsEditor items={items} onAdd={addItems} onRemove={removeItem} />
|
||||
}
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
1. **Stable callback references** - Callbacks don't need to be recreated when state changes
|
||||
2. **No stale closures** - Always operates on the latest state value
|
||||
3. **Fewer dependencies** - Simplifies dependency arrays and reduces memory leaks
|
||||
4. **Prevents bugs** - Eliminates the most common source of React closure bugs
|
||||
|
||||
**When to use functional updates:**
|
||||
|
||||
- Any setState that depends on the current state value
|
||||
- Inside useCallback/useMemo when state is needed
|
||||
- Event handlers that reference state
|
||||
- Async operations that update state
|
||||
|
||||
**When direct updates are fine:**
|
||||
|
||||
- Setting state to a static value: `setCount(0)`
|
||||
- Setting state from props/arguments only: `setName(newName)`
|
||||
- State doesn't depend on previous value
|
||||
|
||||
**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, the compiler can automatically optimize some cases, but functional updates are still recommended for correctness and to prevent stale closure bugs.
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
title: Use Lazy State Initialization
|
||||
impact: MEDIUM
|
||||
impactDescription: wasted computation on every render
|
||||
tags: react, hooks, useState, performance, initialization
|
||||
---
|
||||
|
||||
## Use Lazy State Initialization
|
||||
|
||||
Pass a function to `useState` for expensive initial values. Without the function form, the initializer runs on every render even though the value is only used once.
|
||||
|
||||
**Incorrect (runs on every render):**
|
||||
|
||||
```tsx
|
||||
function FilteredList({ items }: { items: Item[] }) {
|
||||
// buildSearchIndex() runs on EVERY render, even after initialization
|
||||
const [searchIndex, setSearchIndex] = useState(buildSearchIndex(items))
|
||||
const [query, setQuery] = useState('')
|
||||
|
||||
// When query changes, buildSearchIndex runs again unnecessarily
|
||||
return <SearchResults index={searchIndex} query={query} />
|
||||
}
|
||||
|
||||
function UserProfile() {
|
||||
// JSON.parse runs on every render
|
||||
const [settings, setSettings] = useState(
|
||||
JSON.parse(localStorage.getItem('settings') || '{}')
|
||||
)
|
||||
|
||||
return <SettingsForm settings={settings} onChange={setSettings} />
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (runs only once):**
|
||||
|
||||
```tsx
|
||||
function FilteredList({ items }: { items: Item[] }) {
|
||||
// buildSearchIndex() runs ONLY on initial render
|
||||
const [searchIndex, setSearchIndex] = useState(() => buildSearchIndex(items))
|
||||
const [query, setQuery] = useState('')
|
||||
|
||||
return <SearchResults index={searchIndex} query={query} />
|
||||
}
|
||||
|
||||
function UserProfile() {
|
||||
// JSON.parse runs only on initial render
|
||||
const [settings, setSettings] = useState(() => {
|
||||
const stored = localStorage.getItem('settings')
|
||||
return stored ? JSON.parse(stored) : {}
|
||||
})
|
||||
|
||||
return <SettingsForm settings={settings} onChange={setSettings} />
|
||||
}
|
||||
```
|
||||
|
||||
Use lazy initialization when computing initial values from localStorage/sessionStorage, building data structures (indexes, maps), reading from the DOM, or performing heavy transformations.
|
||||
|
||||
For simple primitives (`useState(0)`), direct references (`useState(props.value)`), or cheap literals (`useState({})`), the function form is unnecessary.
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
|
||||
title: Extract Default Non-primitive Parameter Value from Memoized Component to Constant
|
||||
impact: MEDIUM
|
||||
impactDescription: restores memoization by using a constant for default value
|
||||
tags: rerender, memo, optimization
|
||||
|
||||
---
|
||||
|
||||
## Extract Default Non-primitive Parameter Value from Memoized Component to Constant
|
||||
|
||||
When memoized component has a default value for some non-primitive optional parameter, such as an array, function, or object, calling the component without that parameter results in broken memoization. This is because new value instances are created on every rerender, and they do not pass strict equality comparison in `memo()`.
|
||||
|
||||
To address this issue, extract the default value into a constant.
|
||||
|
||||
**Incorrect (`onClick` has different values on every rerender):**
|
||||
|
||||
```tsx
|
||||
const UserAvatar = memo(function UserAvatar({ onClick = () => {} }: { onClick?: () => void }) {
|
||||
// ...
|
||||
})
|
||||
|
||||
// Used without optional onClick
|
||||
<UserAvatar />
|
||||
```
|
||||
|
||||
**Correct (stable default value):**
|
||||
|
||||
```tsx
|
||||
const NOOP = () => {};
|
||||
|
||||
const UserAvatar = memo(function UserAvatar({ onClick = NOOP }: { onClick?: () => void }) {
|
||||
// ...
|
||||
})
|
||||
|
||||
// Used without optional onClick
|
||||
<UserAvatar />
|
||||
```
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
title: Extract to Memoized Components
|
||||
impact: MEDIUM
|
||||
impactDescription: enables early returns
|
||||
tags: rerender, memo, useMemo, optimization
|
||||
---
|
||||
|
||||
## Extract to Memoized Components
|
||||
|
||||
Extract expensive work into memoized components to enable early returns before computation.
|
||||
|
||||
**Incorrect (computes avatar even when loading):**
|
||||
|
||||
```tsx
|
||||
function Profile({ user, loading }: Props) {
|
||||
const avatar = useMemo(() => {
|
||||
const id = computeAvatarId(user)
|
||||
return <Avatar id={id} />
|
||||
}, [user])
|
||||
|
||||
if (loading) return <Skeleton />
|
||||
return <div>{avatar}</div>
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (skips computation when loading):**
|
||||
|
||||
```tsx
|
||||
const UserAvatar = memo(function UserAvatar({ user }: { user: User }) {
|
||||
const id = useMemo(() => computeAvatarId(user), [user])
|
||||
return <Avatar id={id} />
|
||||
})
|
||||
|
||||
function Profile({ user, loading }: Props) {
|
||||
if (loading) return <Skeleton />
|
||||
return (
|
||||
<div>
|
||||
<UserAvatar user={user} />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** If your project has [React Compiler](https://react.dev/learn/react-compiler) enabled, manual memoization with `memo()` and `useMemo()` is not necessary. The compiler automatically optimizes re-renders.
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
title: Put Interaction Logic in Event Handlers
|
||||
impact: MEDIUM
|
||||
impactDescription: avoids effect re-runs and duplicate side effects
|
||||
tags: rerender, useEffect, events, side-effects, dependencies
|
||||
---
|
||||
|
||||
## Put Interaction Logic in Event Handlers
|
||||
|
||||
If a side effect is triggered by a specific user action (submit, click, drag), run it in that event handler. Do not model the action as state + effect; it makes effects re-run on unrelated changes and can duplicate the action.
|
||||
|
||||
**Incorrect (event modeled as state + effect):**
|
||||
|
||||
```tsx
|
||||
function Form() {
|
||||
const [submitted, setSubmitted] = useState(false)
|
||||
const theme = useContext(ThemeContext)
|
||||
|
||||
useEffect(() => {
|
||||
if (submitted) {
|
||||
post('/api/register')
|
||||
showToast('Registered', theme)
|
||||
}
|
||||
}, [submitted, theme])
|
||||
|
||||
return <button onClick={() => setSubmitted(true)}>Submit</button>
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (do it in the handler):**
|
||||
|
||||
```tsx
|
||||
function Form() {
|
||||
const theme = useContext(ThemeContext)
|
||||
|
||||
function handleSubmit() {
|
||||
post('/api/register')
|
||||
showToast('Registered', theme)
|
||||
}
|
||||
|
||||
return <button onClick={handleSubmit}>Submit</button>
|
||||
}
|
||||
```
|
||||
|
||||
Reference: [Should this code move to an event handler?](https://react.dev/learn/removing-effect-dependencies#should-this-code-move-to-an-event-handler)
|
||||
@@ -1,35 +0,0 @@
|
||||
---
|
||||
title: Do not wrap a simple expression with a primitive result type in useMemo
|
||||
impact: LOW-MEDIUM
|
||||
impactDescription: wasted computation on every render
|
||||
tags: rerender, useMemo, optimization
|
||||
---
|
||||
|
||||
## Do not wrap a simple expression with a primitive result type in useMemo
|
||||
|
||||
When an expression is simple (few logical or arithmetical operators) and has a primitive result type (boolean, number, string), do not wrap it in `useMemo`.
|
||||
Calling `useMemo` and comparing hook dependencies may consume more resources than the expression itself.
|
||||
|
||||
**Incorrect:**
|
||||
|
||||
```tsx
|
||||
function Header({ user, notifications }: Props) {
|
||||
const isLoading = useMemo(() => {
|
||||
return user.isLoading || notifications.isLoading
|
||||
}, [user.isLoading, notifications.isLoading])
|
||||
|
||||
if (isLoading) return <Skeleton />
|
||||
// return some markup
|
||||
}
|
||||
```
|
||||
|
||||
**Correct:**
|
||||
|
||||
```tsx
|
||||
function Header({ user, notifications }: Props) {
|
||||
const isLoading = user.isLoading || notifications.isLoading
|
||||
|
||||
if (isLoading) return <Skeleton />
|
||||
// return some markup
|
||||
}
|
||||
```
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
title: Use Transitions for Non-Urgent Updates
|
||||
impact: MEDIUM
|
||||
impactDescription: maintains UI responsiveness
|
||||
tags: rerender, transitions, startTransition, performance
|
||||
---
|
||||
|
||||
## Use Transitions for Non-Urgent Updates
|
||||
|
||||
Mark frequent, non-urgent state updates as transitions to maintain UI responsiveness.
|
||||
|
||||
**Incorrect (blocks UI on every scroll):**
|
||||
|
||||
```tsx
|
||||
function ScrollTracker() {
|
||||
const [scrollY, setScrollY] = useState(0)
|
||||
useEffect(() => {
|
||||
const handler = () => setScrollY(window.scrollY)
|
||||
window.addEventListener('scroll', handler, { passive: true })
|
||||
return () => window.removeEventListener('scroll', handler)
|
||||
}, [])
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (non-blocking updates):**
|
||||
|
||||
```tsx
|
||||
import { startTransition } from 'react'
|
||||
|
||||
function ScrollTracker() {
|
||||
const [scrollY, setScrollY] = useState(0)
|
||||
useEffect(() => {
|
||||
const handler = () => {
|
||||
startTransition(() => setScrollY(window.scrollY))
|
||||
}
|
||||
window.addEventListener('scroll', handler, { passive: true })
|
||||
return () => window.removeEventListener('scroll', handler)
|
||||
}, [])
|
||||
}
|
||||
```
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
title: Use useRef for Transient Values
|
||||
impact: MEDIUM
|
||||
impactDescription: avoids unnecessary re-renders on frequent updates
|
||||
tags: rerender, useref, state, performance
|
||||
---
|
||||
|
||||
## Use useRef for Transient Values
|
||||
|
||||
When a value changes frequently and you don't want a re-render on every update (e.g., mouse trackers, intervals, transient flags), store it in `useRef` instead of `useState`. Keep component state for UI; use refs for temporary DOM-adjacent values. Updating a ref does not trigger a re-render.
|
||||
|
||||
**Incorrect (renders every update):**
|
||||
|
||||
```tsx
|
||||
function Tracker() {
|
||||
const [lastX, setLastX] = useState(0)
|
||||
|
||||
useEffect(() => {
|
||||
const onMove = (e: MouseEvent) => setLastX(e.clientX)
|
||||
window.addEventListener('mousemove', onMove)
|
||||
return () => window.removeEventListener('mousemove', onMove)
|
||||
}, [])
|
||||
|
||||
return (
|
||||
<div
|
||||
style={{
|
||||
position: 'fixed',
|
||||
top: 0,
|
||||
left: lastX,
|
||||
width: 8,
|
||||
height: 8,
|
||||
background: 'black',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (no re-render for tracking):**
|
||||
|
||||
```tsx
|
||||
function Tracker() {
|
||||
const lastXRef = useRef(0)
|
||||
const dotRef = useRef<HTMLDivElement>(null)
|
||||
|
||||
useEffect(() => {
|
||||
const onMove = (e: MouseEvent) => {
|
||||
lastXRef.current = e.clientX
|
||||
const node = dotRef.current
|
||||
if (node) {
|
||||
node.style.transform = `translateX(${e.clientX}px)`
|
||||
}
|
||||
}
|
||||
window.addEventListener('mousemove', onMove)
|
||||
return () => window.removeEventListener('mousemove', onMove)
|
||||
}, [])
|
||||
|
||||
return (
|
||||
<div
|
||||
ref={dotRef}
|
||||
style={{
|
||||
position: 'fixed',
|
||||
top: 0,
|
||||
left: 0,
|
||||
width: 8,
|
||||
height: 8,
|
||||
background: 'black',
|
||||
transform: 'translateX(0px)',
|
||||
}}
|
||||
/>
|
||||
)
|
||||
}
|
||||
```
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
title: Use after() for Non-Blocking Operations
|
||||
impact: MEDIUM
|
||||
impactDescription: faster response times
|
||||
tags: server, async, logging, analytics, side-effects
|
||||
---
|
||||
|
||||
## Use after() for Non-Blocking Operations
|
||||
|
||||
Use Next.js's `after()` to schedule work that should execute after a response is sent. This prevents logging, analytics, and other side effects from blocking the response.
|
||||
|
||||
**Incorrect (blocks response):**
|
||||
|
||||
```tsx
|
||||
import { logUserAction } from '@/app/utils'
|
||||
|
||||
export async function POST(request: Request) {
|
||||
// Perform mutation
|
||||
await updateDatabase(request)
|
||||
|
||||
// Logging blocks the response
|
||||
const userAgent = request.headers.get('user-agent') || 'unknown'
|
||||
await logUserAction({ userAgent })
|
||||
|
||||
return new Response(JSON.stringify({ status: 'success' }), {
|
||||
status: 200,
|
||||
headers: { 'Content-Type': 'application/json' }
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (non-blocking):**
|
||||
|
||||
```tsx
|
||||
import { after } from 'next/server'
|
||||
import { headers, cookies } from 'next/headers'
|
||||
import { logUserAction } from '@/app/utils'
|
||||
|
||||
export async function POST(request: Request) {
|
||||
// Perform mutation
|
||||
await updateDatabase(request)
|
||||
|
||||
// Log after response is sent
|
||||
after(async () => {
|
||||
const userAgent = (await headers()).get('user-agent') || 'unknown'
|
||||
const sessionCookie = (await cookies()).get('session-id')?.value || 'anonymous'
|
||||
|
||||
logUserAction({ sessionCookie, userAgent })
|
||||
})
|
||||
|
||||
return new Response(JSON.stringify({ status: 'success' }), {
|
||||
status: 200,
|
||||
headers: { 'Content-Type': 'application/json' }
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
The response is sent immediately while logging happens in the background.
|
||||
|
||||
**Common use cases:**
|
||||
|
||||
- Analytics tracking
|
||||
- Audit logging
|
||||
- Sending notifications
|
||||
- Cache invalidation
|
||||
- Cleanup tasks
|
||||
|
||||
**Important notes:**
|
||||
|
||||
- `after()` runs even if the response fails or redirects
|
||||
- Works in Server Actions, Route Handlers, and Server Components
|
||||
|
||||
Reference: [https://nextjs.org/docs/app/api-reference/functions/after](https://nextjs.org/docs/app/api-reference/functions/after)
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
title: Authenticate Server Actions Like API Routes
|
||||
impact: CRITICAL
|
||||
impactDescription: prevents unauthorized access to server mutations
|
||||
tags: server, server-actions, authentication, security, authorization
|
||||
---
|
||||
|
||||
## Authenticate Server Actions Like API Routes
|
||||
|
||||
**Impact: CRITICAL (prevents unauthorized access to server mutations)**
|
||||
|
||||
Server Actions (functions with `"use server"`) are exposed as public endpoints, just like API routes. Always verify authentication and authorization **inside** each Server Action—do not rely solely on middleware, layout guards, or page-level checks, as Server Actions can be invoked directly.
|
||||
|
||||
Next.js documentation explicitly states: "Treat Server Actions with the same security considerations as public-facing API endpoints, and verify if the user is allowed to perform a mutation."
|
||||
|
||||
**Incorrect (no authentication check):**
|
||||
|
||||
```typescript
|
||||
'use server'
|
||||
|
||||
export async function deleteUser(userId: string) {
|
||||
// Anyone can call this! No auth check
|
||||
await db.user.delete({ where: { id: userId } })
|
||||
return { success: true }
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (authentication inside the action):**
|
||||
|
||||
```typescript
|
||||
'use server'
|
||||
|
||||
import { verifySession } from '@/lib/auth'
|
||||
import { unauthorized } from '@/lib/errors'
|
||||
|
||||
export async function deleteUser(userId: string) {
|
||||
// Always check auth inside the action
|
||||
const session = await verifySession()
|
||||
|
||||
if (!session) {
|
||||
throw unauthorized('Must be logged in')
|
||||
}
|
||||
|
||||
// Check authorization too
|
||||
if (session.user.role !== 'admin' && session.user.id !== userId) {
|
||||
throw unauthorized('Cannot delete other users')
|
||||
}
|
||||
|
||||
await db.user.delete({ where: { id: userId } })
|
||||
return { success: true }
|
||||
}
|
||||
```
|
||||
|
||||
**With input validation:**
|
||||
|
||||
```typescript
|
||||
'use server'
|
||||
|
||||
import { verifySession } from '@/lib/auth'
|
||||
import { z } from 'zod'
|
||||
|
||||
const updateProfileSchema = z.object({
|
||||
userId: z.string().uuid(),
|
||||
name: z.string().min(1).max(100),
|
||||
email: z.string().email()
|
||||
})
|
||||
|
||||
export async function updateProfile(data: unknown) {
|
||||
// Validate input first
|
||||
const validated = updateProfileSchema.parse(data)
|
||||
|
||||
// Then authenticate
|
||||
const session = await verifySession()
|
||||
if (!session) {
|
||||
throw new Error('Unauthorized')
|
||||
}
|
||||
|
||||
// Then authorize
|
||||
if (session.user.id !== validated.userId) {
|
||||
throw new Error('Can only update own profile')
|
||||
}
|
||||
|
||||
// Finally perform the mutation
|
||||
await db.user.update({
|
||||
where: { id: validated.userId },
|
||||
data: {
|
||||
name: validated.name,
|
||||
email: validated.email
|
||||
}
|
||||
})
|
||||
|
||||
return { success: true }
|
||||
}
|
||||
```
|
||||
|
||||
Reference: [https://nextjs.org/docs/app/guides/authentication](https://nextjs.org/docs/app/guides/authentication)
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
title: Cross-Request LRU Caching
|
||||
impact: HIGH
|
||||
impactDescription: caches across requests
|
||||
tags: server, cache, lru, cross-request
|
||||
---
|
||||
|
||||
## Cross-Request LRU Caching
|
||||
|
||||
`React.cache()` only works within one request. For data shared across sequential requests (user clicks button A then button B), use an LRU cache.
|
||||
|
||||
**Implementation:**
|
||||
|
||||
```typescript
|
||||
import { LRUCache } from 'lru-cache'
|
||||
|
||||
const cache = new LRUCache<string, any>({
|
||||
max: 1000,
|
||||
ttl: 5 * 60 * 1000 // 5 minutes
|
||||
})
|
||||
|
||||
export async function getUser(id: string) {
|
||||
const cached = cache.get(id)
|
||||
if (cached) return cached
|
||||
|
||||
const user = await db.user.findUnique({ where: { id } })
|
||||
cache.set(id, user)
|
||||
return user
|
||||
}
|
||||
|
||||
// Request 1: DB query, result cached
|
||||
// Request 2: cache hit, no DB query
|
||||
```
|
||||
|
||||
Use when sequential user actions hit multiple endpoints needing the same data within seconds.
|
||||
|
||||
**With Vercel's [Fluid Compute](https://vercel.com/docs/fluid-compute):** LRU caching is especially effective because multiple concurrent requests can share the same function instance and cache. This means the cache persists across requests without needing external storage like Redis.
|
||||
|
||||
**In traditional serverless:** Each invocation runs in isolation, so consider Redis for cross-process caching.
|
||||
|
||||
Reference: [https://github.com/isaacs/node-lru-cache](https://github.com/isaacs/node-lru-cache)
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
title: Per-Request Deduplication with React.cache()
|
||||
impact: MEDIUM
|
||||
impactDescription: deduplicates within request
|
||||
tags: server, cache, react-cache, deduplication
|
||||
---
|
||||
|
||||
## Per-Request Deduplication with React.cache()
|
||||
|
||||
Use `React.cache()` for server-side request deduplication. Authentication and database queries benefit most.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```typescript
|
||||
import { cache } from 'react'
|
||||
|
||||
export const getCurrentUser = cache(async () => {
|
||||
const session = await auth()
|
||||
if (!session?.user?.id) return null
|
||||
return await db.user.findUnique({
|
||||
where: { id: session.user.id }
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
Within a single request, multiple calls to `getCurrentUser()` execute the query only once.
|
||||
|
||||
**Avoid inline objects as arguments:**
|
||||
|
||||
`React.cache()` uses shallow equality (`Object.is`) to determine cache hits. Inline objects create new references each call, preventing cache hits.
|
||||
|
||||
**Incorrect (always cache miss):**
|
||||
|
||||
```typescript
|
||||
const getUser = cache(async (params: { uid: number }) => {
|
||||
return await db.user.findUnique({ where: { id: params.uid } })
|
||||
})
|
||||
|
||||
// Each call creates new object, never hits cache
|
||||
getUser({ uid: 1 })
|
||||
getUser({ uid: 1 }) // Cache miss, runs query again
|
||||
```
|
||||
|
||||
**Correct (cache hit):**
|
||||
|
||||
```typescript
|
||||
const getUser = cache(async (uid: number) => {
|
||||
return await db.user.findUnique({ where: { id: uid } })
|
||||
})
|
||||
|
||||
// Primitive args use value equality
|
||||
getUser(1)
|
||||
getUser(1) // Cache hit, returns cached result
|
||||
```
|
||||
|
||||
If you must pass objects, pass the same reference:
|
||||
|
||||
```typescript
|
||||
const params = { uid: 1 }
|
||||
getUser(params) // Query runs
|
||||
getUser(params) // Cache hit (same reference)
|
||||
```
|
||||
|
||||
**Next.js-Specific Note:**
|
||||
|
||||
In Next.js, the `fetch` API is automatically extended with request memoization. Requests with the same URL and options are automatically deduplicated within a single request, so you don't need `React.cache()` for `fetch` calls. However, `React.cache()` is still essential for other async tasks:
|
||||
|
||||
- Database queries (Prisma, Drizzle, etc.)
|
||||
- Heavy computations
|
||||
- Authentication checks
|
||||
- File system operations
|
||||
- Any non-fetch async work
|
||||
|
||||
Use `React.cache()` to deduplicate these operations across your component tree.
|
||||
|
||||
Reference: [React.cache documentation](https://react.dev/reference/react/cache)
|
||||
@@ -1,65 +0,0 @@
|
||||
---
|
||||
title: Avoid Duplicate Serialization in RSC Props
|
||||
impact: LOW
|
||||
impactDescription: reduces network payload by avoiding duplicate serialization
|
||||
tags: server, rsc, serialization, props, client-components
|
||||
---
|
||||
|
||||
## Avoid Duplicate Serialization in RSC Props
|
||||
|
||||
**Impact: LOW (reduces network payload by avoiding duplicate serialization)**
|
||||
|
||||
RSC→client serialization deduplicates by object reference, not value. Same reference = serialized once; new reference = serialized again. Do transformations (`.toSorted()`, `.filter()`, `.map()`) in client, not server.
|
||||
|
||||
**Incorrect (duplicates array):**
|
||||
|
||||
```tsx
|
||||
// RSC: sends 6 strings (2 arrays × 3 items)
|
||||
<ClientList usernames={usernames} usernamesOrdered={usernames.toSorted()} />
|
||||
```
|
||||
|
||||
**Correct (sends 3 strings):**
|
||||
|
||||
```tsx
|
||||
// RSC: send once
|
||||
<ClientList usernames={usernames} />
|
||||
|
||||
// Client: transform there
|
||||
'use client'
|
||||
const sorted = useMemo(() => [...usernames].sort(), [usernames])
|
||||
```
|
||||
|
||||
**Nested deduplication behavior:**
|
||||
|
||||
Deduplication works recursively. Impact varies by data type:
|
||||
|
||||
- `string[]`, `number[]`, `boolean[]`: **HIGH impact** - array + all primitives fully duplicated
|
||||
- `object[]`: **LOW impact** - array duplicated, but nested objects deduplicated by reference
|
||||
|
||||
```tsx
|
||||
// string[] - duplicates everything
|
||||
usernames={['a','b']} sorted={usernames.toSorted()} // sends 4 strings
|
||||
|
||||
// object[] - duplicates array structure only
|
||||
users={[{id:1},{id:2}]} sorted={users.toSorted()} // sends 2 arrays + 2 unique objects (not 4)
|
||||
```
|
||||
|
||||
**Operations breaking deduplication (create new references):**
|
||||
|
||||
- Arrays: `.toSorted()`, `.filter()`, `.map()`, `.slice()`, `[...arr]`
|
||||
- Objects: `{...obj}`, `Object.assign()`, `structuredClone()`, `JSON.parse(JSON.stringify())`
|
||||
|
||||
**More examples:**
|
||||
|
||||
```tsx
|
||||
// ❌ Bad
|
||||
<C users={users} active={users.filter(u => u.active)} />
|
||||
<C product={product} productName={product.name} />
|
||||
|
||||
// ✅ Good
|
||||
<C users={users} />
|
||||
<C product={product} />
|
||||
// Do filtering/destructuring in client
|
||||
```
|
||||
|
||||
**Exception:** Pass derived data when transformation is expensive or client doesn't need original.
|
||||
@@ -1,83 +0,0 @@
|
||||
---
|
||||
title: Parallel Data Fetching with Component Composition
|
||||
impact: CRITICAL
|
||||
impactDescription: eliminates server-side waterfalls
|
||||
tags: server, rsc, parallel-fetching, composition
|
||||
---
|
||||
|
||||
## Parallel Data Fetching with Component Composition
|
||||
|
||||
React Server Components execute sequentially within a tree. Restructure with composition to parallelize data fetching.
|
||||
|
||||
**Incorrect (Sidebar waits for Page's fetch to complete):**
|
||||
|
||||
```tsx
|
||||
export default async function Page() {
|
||||
const header = await fetchHeader()
|
||||
return (
|
||||
<div>
|
||||
<div>{header}</div>
|
||||
<Sidebar />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
async function Sidebar() {
|
||||
const items = await fetchSidebarItems()
|
||||
return <nav>{items.map(renderItem)}</nav>
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (both fetch simultaneously):**
|
||||
|
||||
```tsx
|
||||
async function Header() {
|
||||
const data = await fetchHeader()
|
||||
return <div>{data}</div>
|
||||
}
|
||||
|
||||
async function Sidebar() {
|
||||
const items = await fetchSidebarItems()
|
||||
return <nav>{items.map(renderItem)}</nav>
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<div>
|
||||
<Header />
|
||||
<Sidebar />
|
||||
</div>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
**Alternative with children prop:**
|
||||
|
||||
```tsx
|
||||
async function Header() {
|
||||
const data = await fetchHeader()
|
||||
return <div>{data}</div>
|
||||
}
|
||||
|
||||
async function Sidebar() {
|
||||
const items = await fetchSidebarItems()
|
||||
return <nav>{items.map(renderItem)}</nav>
|
||||
}
|
||||
|
||||
function Layout({ children }: { children: ReactNode }) {
|
||||
return (
|
||||
<div>
|
||||
<Header />
|
||||
{children}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
export default function Page() {
|
||||
return (
|
||||
<Layout>
|
||||
<Sidebar />
|
||||
</Layout>
|
||||
)
|
||||
}
|
||||
```
|
||||
@@ -1,38 +0,0 @@
|
||||
---
|
||||
title: Minimize Serialization at RSC Boundaries
|
||||
impact: HIGH
|
||||
impactDescription: reduces data transfer size
|
||||
tags: server, rsc, serialization, props
|
||||
---
|
||||
|
||||
## Minimize Serialization at RSC Boundaries
|
||||
|
||||
The React Server/Client boundary serializes all object properties into strings and embeds them in the HTML response and subsequent RSC requests. This serialized data directly impacts page weight and load time, so **size matters a lot**. Only pass fields that the client actually uses.
|
||||
|
||||
**Incorrect (serializes all 50 fields):**
|
||||
|
||||
```tsx
|
||||
async function Page() {
|
||||
const user = await fetchUser() // 50 fields
|
||||
return <Profile user={user} />
|
||||
}
|
||||
|
||||
'use client'
|
||||
function Profile({ user }: { user: User }) {
|
||||
return <div>{user.name}</div> // uses 1 field
|
||||
}
|
||||
```
|
||||
|
||||
**Correct (serializes only 1 field):**
|
||||
|
||||
```tsx
|
||||
async function Page() {
|
||||
const user = await fetchUser()
|
||||
return <Profile name={user.name} />
|
||||
}
|
||||
|
||||
'use client'
|
||||
function Profile({ name }: { name: string }) {
|
||||
return <div>{name}</div>
|
||||
}
|
||||
```
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
name: web-design-guidelines
|
||||
description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
|
||||
metadata:
|
||||
author: vercel
|
||||
version: "1.0.0"
|
||||
argument-hint: <file-or-pattern>
|
||||
---
|
||||
|
||||
# Web Interface Guidelines
|
||||
|
||||
Review files for compliance with Web Interface Guidelines.
|
||||
|
||||
## How It Works
|
||||
|
||||
1. Fetch the latest guidelines from the source URL below
|
||||
2. Read the specified files (or prompt user for files/pattern)
|
||||
3. Check against all rules in the fetched guidelines
|
||||
4. Output findings in the terse `file:line` format
|
||||
|
||||
## Guidelines Source
|
||||
|
||||
Fetch fresh guidelines before each review:
|
||||
|
||||
```
|
||||
https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
|
||||
```
|
||||
|
||||
Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.
|
||||
|
||||
## Usage
|
||||
|
||||
When a user provides a file or pattern argument:
|
||||
1. Fetch guidelines from the source URL above
|
||||
2. Read the specified files
|
||||
3. Apply all rules from the fetched guidelines
|
||||
4. Output findings using the format specified in the guidelines
|
||||
|
||||
If no files specified, ask the user which files to review.
|
||||
@@ -1,107 +0,0 @@
|
||||
---
|
||||
name: personal-site-feature-dev
|
||||
description: "Use this agent when the user wants to build, design, or implement new features for their personal website. This includes adding new pages, components, interactive elements, styling updates, content sections, animations, integrations, or any functional enhancement to the site.\\n\\nExamples:\\n\\n<example>\\nContext: The user wants to add a new section to their personal website.\\nuser: \"I want to add a blog section to my personal website\"\\nassistant: \"Let me launch the personal-site-feature-dev agent to help design and implement a blog section for your site.\"\\n<commentary>\\nSince the user wants to build a new feature for their personal website, use the Task tool to launch the personal-site-feature-dev agent to plan and implement the blog section.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user wants to improve an existing part of their website.\\nuser: \"The contact form on my site looks outdated and doesn't validate inputs properly\"\\nassistant: \"I'll use the personal-site-feature-dev agent to redesign and improve your contact form with proper validation.\"\\n<commentary>\\nSince the user wants to enhance an existing feature on their personal website, use the Task tool to launch the personal-site-feature-dev agent to handle the redesign and validation improvements.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: The user mentions wanting to add interactivity or a visual element.\\nuser: \"Can you add a dark mode toggle to my site?\"\\nassistant: \"Let me launch the personal-site-feature-dev agent to implement a dark mode toggle with proper theme persistence.\"\\n<commentary>\\nSince the user wants a new interactive feature for their personal website, use the Task tool to launch the personal-site-feature-dev agent to implement the dark mode toggle.\\n</commentary>\\n</example>"
|
||||
model: opus
|
||||
color: purple
|
||||
memory: local
|
||||
---
|
||||
|
||||
You are an expert full-stack web developer specializing in personal websites and portfolios. You have deep expertise in modern frontend frameworks, responsive design, accessibility, performance optimization, and creating polished, professional personal sites that stand out. You combine strong engineering skills with an eye for design and UX.
|
||||
|
||||
## Core Responsibilities
|
||||
|
||||
1. **Understand Before Building**: Before writing any code, thoroughly examine the existing codebase to understand:
|
||||
- The framework and tech stack in use (React, Next.js, Astro, plain HTML/CSS, etc.)
|
||||
- Existing design patterns, component structures, and styling approaches
|
||||
- The project's file organization and naming conventions
|
||||
- Any configuration files (package.json, tsconfig, etc.) that inform how to write code
|
||||
- Only look at `.env.example` files for environment variable references — never read active `.env` files
|
||||
|
||||
2. **Think Critically About Features**: When the user proposes a feature:
|
||||
- Clarify what they want to achieve and why
|
||||
- Consider tradeoffs: complexity vs. value, performance implications, maintenance burden, accessibility impact
|
||||
- Suggest alternatives if a simpler approach would achieve the same goal
|
||||
- Don't just agree — push back constructively if something would hurt the site's quality
|
||||
- Present options with clear pros and cons when multiple approaches exist
|
||||
|
||||
3. **Plan Before Implementing**: For each feature:
|
||||
- Outline the components, files, and changes needed
|
||||
- Identify dependencies or packages required
|
||||
- Consider how the feature fits with existing design language
|
||||
- Flag any potential issues (browser compatibility, performance, SEO impact)
|
||||
|
||||
4. **Write Production-Quality Code**:
|
||||
- Follow the existing code style and conventions in the project exactly
|
||||
- Write semantic, accessible HTML (proper heading hierarchy, ARIA labels, keyboard navigation)
|
||||
- Ensure responsive design works across mobile, tablet, and desktop
|
||||
- Add appropriate TypeScript types if the project uses TypeScript
|
||||
- Keep components modular and reusable where sensible
|
||||
- Include meaningful comments only where the code isn't self-explanatory
|
||||
|
||||
## Feature Development Workflow
|
||||
|
||||
1. **Discovery**: Read relevant existing files to understand current state
|
||||
2. **Proposal**: Present the implementation plan with tradeoffs
|
||||
3. **Implementation**: Write the code, matching existing patterns
|
||||
4. **Verification**: Review your own code for bugs, accessibility issues, and edge cases
|
||||
5. **Polish**: Suggest refinements for animations, transitions, or micro-interactions that elevate the feature
|
||||
|
||||
## Quality Standards
|
||||
|
||||
- **Accessibility**: All features must be WCAG 2.1 AA compliant at minimum
|
||||
- **Performance**: Lazy load images, minimize bundle impact, avoid layout shifts
|
||||
- **SEO**: Use proper meta tags, semantic HTML, and structured data where relevant
|
||||
- **Responsive**: Mobile-first approach, test mental model across breakpoints
|
||||
- **Cross-browser**: Note any features that may need polyfills or fallbacks
|
||||
|
||||
## Design Sensibility
|
||||
|
||||
- Maintain visual consistency with the existing site design
|
||||
- Use the site's existing color palette, typography, and spacing system
|
||||
- Suggest subtle animations and transitions that enhance UX without being distracting
|
||||
- Prioritize clean, readable layouts with good whitespace
|
||||
- Consider dark mode compatibility if the site supports it
|
||||
|
||||
## What NOT To Do
|
||||
|
||||
- Don't add unnecessary dependencies when native solutions work
|
||||
- Don't over-engineer simple features
|
||||
- Don't break existing functionality when adding new features
|
||||
- Don't ignore the existing design system or create inconsistent styling
|
||||
- Don't skip error handling or loading states
|
||||
- Never read or access active `.env` files
|
||||
|
||||
## Communication Style
|
||||
|
||||
- Be direct and specific about what you're building and why
|
||||
- When presenting tradeoffs, use concrete terms ("This adds ~50KB to bundle" not "This might be slightly larger")
|
||||
- If you're unsure about a design decision, present 2-3 options with clear recommendations
|
||||
- Proactively mention things the user might not have considered (SEO, accessibility, mobile experience)
|
||||
|
||||
**Update your agent memory** as you discover codebase patterns, design tokens, component conventions, framework-specific idioms, and architectural decisions in this personal website project. This builds up knowledge across conversations so you can maintain consistency. Write concise notes about what you found and where.
|
||||
|
||||
Examples of what to record:
|
||||
- Framework and key libraries used (e.g., "Next.js 14 with App Router, Tailwind CSS, Framer Motion")
|
||||
- Component patterns (e.g., "Components use named exports, co-located styles in .module.css files")
|
||||
- Design tokens (e.g., "Primary color: #3B82F6, font stack: Inter for body, Fira Code for code blocks")
|
||||
- File structure conventions (e.g., "Pages in /app, shared components in /components/ui")
|
||||
- Any custom utilities, hooks, or helpers that should be reused
|
||||
|
||||
# Persistent Agent Memory
|
||||
|
||||
You have a persistent Persistent Agent Memory directory at `/Users/shivampatel/akshay/Webserver/.claude/agent-memory-local/personal-site-feature-dev/`. Its contents persist across conversations.
|
||||
|
||||
As you work, consult your memory files to build on previous experience. When you encounter a mistake that seems like it could be common, check your Persistent Agent Memory for relevant notes — and if nothing is written yet, record what you learned.
|
||||
|
||||
Guidelines:
|
||||
- `MEMORY.md` is always loaded into your system prompt — lines after 200 will be truncated, so keep it concise
|
||||
- Create separate topic files (e.g., `debugging.md`, `patterns.md`) for detailed notes and link to them from MEMORY.md
|
||||
- Record insights about problem constraints, strategies that worked or failed, and lessons learned
|
||||
- Update or remove memories that turn out to be wrong or outdated
|
||||
- Organize memory semantically by topic, not chronologically
|
||||
- Use the Write and Edit tools to update your memory files
|
||||
- Since this memory is local-scope (not checked into version control), tailor your memories to this project and machine
|
||||
|
||||
## MEMORY.md
|
||||
|
||||
Your MEMORY.md is currently empty. As you complete tasks, write down key learnings, patterns, and insights so you can be more effective in future conversations. Anything saved in MEMORY.md will be included in your system prompt next time.
|
||||
19
.dockerignore
Normal file
19
.dockerignore
Normal file
@@ -0,0 +1,19 @@
|
||||
.git
|
||||
.next
|
||||
.vercel
|
||||
.claude
|
||||
.agents
|
||||
.data
|
||||
node_modules
|
||||
coverage
|
||||
*.log
|
||||
*.pem
|
||||
.env
|
||||
.env.*
|
||||
visitors.db*
|
||||
npm-debug.log*
|
||||
yarn-debug.log*
|
||||
yarn-error.log*
|
||||
.pnpm-debug.log*
|
||||
README.md
|
||||
ADMIN_DASH_INTEGRATION.md
|
||||
@@ -27,7 +27,7 @@ jobs:
|
||||
# The bind mount creates /server_storage on the host if missing.
|
||||
# Run a throwaway container to fix ownership so UID 1001 (nextjs) can write.
|
||||
docker run --rm -v /server_storage:/data alpine sh -c \
|
||||
"chown -R 1001:1001 /data && chmod -R 755 /data"
|
||||
"chown -R 1001:1001 /data && chmod -R go-rwx /data"
|
||||
|
||||
- name: Run New Container
|
||||
run: |
|
||||
@@ -35,5 +35,8 @@ jobs:
|
||||
--name website-container \
|
||||
--restart unless-stopped \
|
||||
-p 8080:3000 \
|
||||
-e ANALYTICS_SALT="${{ secrets.ANALYTICS_SALT }}" \
|
||||
-e ADMIN_DASH_URL="${{ secrets.ADMIN_DASH_URL }}" \
|
||||
-e ADMIN_DASH_KEY="${{ secrets.ADMIN_DASH_KEY }}" \
|
||||
-v /server_storage:/server_storage \
|
||||
my-website:latest
|
||||
6
.gitignore
vendored
6
.gitignore
vendored
@@ -23,6 +23,8 @@
|
||||
# misc
|
||||
.DS_Store
|
||||
*.pem
|
||||
.claude/
|
||||
.agents/
|
||||
|
||||
# debug
|
||||
npm-debug.log*
|
||||
@@ -39,3 +41,7 @@ yarn-error.log*
|
||||
# typescript
|
||||
*.tsbuildinfo
|
||||
next-env.d.ts
|
||||
|
||||
# local runtime state
|
||||
.data/
|
||||
visitors.db*
|
||||
|
||||
@@ -38,7 +38,7 @@ docker run -d \
|
||||
```sql
|
||||
CREATE TABLE visits (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
ip_address TEXT NOT NULL, -- e.g. "2600:6c65:6740:..." or "18.199.106.183"
|
||||
visitor_id TEXT NOT NULL, -- daily HMAC; raw IP addresses are not stored
|
||||
path TEXT NOT NULL, -- e.g. "/", "/blog", "/resume"
|
||||
visited_at TEXT NOT NULL -- UTC datetime, e.g. "2026-02-09 05:19:53"
|
||||
);
|
||||
@@ -66,7 +66,7 @@ visits = conn.execute('SELECT * FROM visits ORDER BY visited_at DESC LIMIT 100')
|
||||
|
||||
```sql
|
||||
-- Unique visitors today
|
||||
SELECT COUNT(DISTINCT ip_address) FROM visits
|
||||
SELECT COUNT(DISTINCT visitor_id) FROM visits
|
||||
WHERE visited_at >= date('now');
|
||||
|
||||
-- Page view counts
|
||||
@@ -79,6 +79,16 @@ FROM visits WHERE visited_at >= datetime('now', '-1 day')
|
||||
GROUP BY hour ORDER BY hour;
|
||||
```
|
||||
|
||||
## 3. Optional Event Relay
|
||||
|
||||
Set `ADMIN_DASH_URL` to receive same-origin website events as JSON:
|
||||
|
||||
```json
|
||||
{ "path": "/blog", "visitorId": "daily-hmac-id", "timestamp": 1770000000000 }
|
||||
```
|
||||
|
||||
If `ADMIN_DASH_KEY` is set, the website sends it as a bearer token. The relay is disabled when `ADMIN_DASH_URL` is empty.
|
||||
|
||||
## Docker Compose Example
|
||||
|
||||
```yaml
|
||||
|
||||
@@ -29,6 +29,9 @@ WORKDIR /app
|
||||
|
||||
ENV NODE_ENV production
|
||||
ENV NEXT_TELEMETRY_DISABLED 1
|
||||
ENV VISIT_DB_PATH /server_storage/visitors.db
|
||||
|
||||
RUN apk add --no-cache libc6-compat libstdc++
|
||||
|
||||
RUN addgroup --system --gid 1001 nodejs
|
||||
RUN adduser --system --uid 1001 nextjs
|
||||
@@ -36,7 +39,7 @@ RUN adduser --system --uid 1001 nextjs
|
||||
COPY --from=builder /app/public ./public
|
||||
|
||||
# Create server_storage directory for SQLite DB
|
||||
RUN mkdir -p /server_storage && chown nextjs:nodejs /server_storage
|
||||
RUN mkdir -p /server_storage && chown nextjs:nodejs /server_storage && chmod 700 /server_storage
|
||||
|
||||
# Set the correct permission for prerender cache
|
||||
RUN mkdir .next
|
||||
|
||||
51
README.md
51
README.md
@@ -1,36 +1,47 @@
|
||||
This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
|
||||
# Akshay Kolli Personal Site
|
||||
|
||||
## Getting Started
|
||||
Next.js personal site with MDX writing, a resume page, and local-first visit analytics for a Raspberry Pi deployment.
|
||||
|
||||
First, run the development server:
|
||||
## Development
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
# or
|
||||
yarn dev
|
||||
# or
|
||||
pnpm dev
|
||||
# or
|
||||
bun dev
|
||||
```
|
||||
|
||||
Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
|
||||
|
||||
You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
|
||||
## Environment
|
||||
|
||||
This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
|
||||
```bash
|
||||
ANALYTICS_SALT=replace-with-a-long-random-secret
|
||||
VISIT_DB_PATH=/server_storage/visitors.db
|
||||
ADMIN_DASH_URL=
|
||||
ADMIN_DASH_KEY=
|
||||
REQUEST_LOGS=false
|
||||
```
|
||||
|
||||
## Learn More
|
||||
Analytics does not use a browser-visible secret. The endpoint accepts same-origin JSON only, validates the path, rate-limits requests, and stores a daily HMAC visitor ID instead of raw IP addresses. Set `ANALYTICS_SALT` in production so visitor IDs remain stable across restarts without storing raw addresses.
|
||||
|
||||
To learn more about Next.js, take a look at the following resources:
|
||||
## Docker
|
||||
|
||||
- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
|
||||
- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
|
||||
```bash
|
||||
docker build -t personal-site:latest .
|
||||
docker run -d \
|
||||
--name website-container \
|
||||
--restart unless-stopped \
|
||||
-p 8080:3000 \
|
||||
-e ANALYTICS_SALT="$(openssl rand -hex 32)" \
|
||||
-v /server_storage:/server_storage \
|
||||
personal-site:latest
|
||||
```
|
||||
|
||||
You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
|
||||
`/server_storage` should be owned by the container user and should not be world-readable because it contains analytics data.
|
||||
|
||||
## Deploy on Vercel
|
||||
## Checks
|
||||
|
||||
The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
|
||||
|
||||
Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
|
||||
```bash
|
||||
npm run lint
|
||||
npm run build
|
||||
npm audit --omit=dev
|
||||
```
|
||||
|
||||
@@ -1,41 +1,97 @@
|
||||
import { NextResponse } from 'next/server';
|
||||
import { logVisit } from '@/lib/db';
|
||||
import {
|
||||
getClientAddress,
|
||||
getUserAgent,
|
||||
isSameOriginRequest,
|
||||
normalizeVisitPath,
|
||||
} from '@/lib/request';
|
||||
|
||||
const ANALYTICS_KEY = process.env.ANALYTICS_KEY || 'default-analytics-key';
|
||||
export const runtime = 'nodejs';
|
||||
|
||||
const MAX_BODY_BYTES = 4096;
|
||||
|
||||
function getAdminRelayUrl() {
|
||||
const adminUrl = process.env.ADMIN_DASH_URL;
|
||||
if (!adminUrl) return null;
|
||||
|
||||
try {
|
||||
const url = new URL(adminUrl);
|
||||
if (url.protocol !== 'https:' && url.protocol !== 'http:') return null;
|
||||
return url.toString();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function relayVisit(path: string, visitorId: string | null) {
|
||||
const adminUrl = getAdminRelayUrl();
|
||||
if (!adminUrl) return;
|
||||
|
||||
const headers: Record<string, string> = {
|
||||
'Content-Type': 'application/json',
|
||||
};
|
||||
|
||||
if (process.env.ADMIN_DASH_KEY) {
|
||||
headers.Authorization = `Bearer ${process.env.ADMIN_DASH_KEY}`;
|
||||
}
|
||||
|
||||
fetch(adminUrl, {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({ path, visitorId, timestamp: Date.now() }),
|
||||
headers,
|
||||
signal: AbortSignal.timeout(1500),
|
||||
}).catch((error) => {
|
||||
if (process.env.NODE_ENV !== 'production') {
|
||||
console.error('Analytics relay failed', error);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
export async function POST(req: Request) {
|
||||
try {
|
||||
const analyticsKey = req.headers.get('X-Analytics-Key');
|
||||
if (analyticsKey !== ANALYTICS_KEY) {
|
||||
return NextResponse.json({ success: false, error: 'Unauthorized' }, { status: 401 });
|
||||
if (!isSameOriginRequest(req)) {
|
||||
return NextResponse.json({ success: false, error: 'Forbidden' }, { status: 403 });
|
||||
}
|
||||
|
||||
const body = await req.json();
|
||||
const contentType = req.headers.get('content-type') || '';
|
||||
if (!contentType.toLowerCase().includes('application/json')) {
|
||||
return NextResponse.json({ success: false, error: 'Unsupported media type' }, { status: 415 });
|
||||
}
|
||||
|
||||
if (typeof body.path !== 'string' || typeof body.timestamp !== 'number') {
|
||||
const contentLength = Number(req.headers.get('content-length') || 0);
|
||||
if (contentLength > MAX_BODY_BYTES) {
|
||||
return NextResponse.json({ success: false, error: 'Payload too large' }, { status: 413 });
|
||||
}
|
||||
|
||||
const rawBody = await req.text();
|
||||
if (Buffer.byteLength(rawBody, 'utf8') > MAX_BODY_BYTES) {
|
||||
return NextResponse.json({ success: false, error: 'Payload too large' }, { status: 413 });
|
||||
}
|
||||
|
||||
const body = JSON.parse(rawBody);
|
||||
if (!body || typeof body !== 'object' || Array.isArray(body)) {
|
||||
return NextResponse.json({ success: false, error: 'Invalid input' }, { status: 400 });
|
||||
}
|
||||
|
||||
const visitPath = normalizeVisitPath(body.path);
|
||||
|
||||
if (!visitPath) {
|
||||
return NextResponse.json({ success: false, error: 'Invalid input' }, { status: 400 });
|
||||
}
|
||||
|
||||
const headers = req.headers;
|
||||
const forwarded = headers.get('x-forwarded-for');
|
||||
const ip = forwarded ? forwarded.split(',')[0].trim() : 'unknown';
|
||||
const clientAddress = getClientAddress(headers);
|
||||
const userAgent = getUserAgent(headers);
|
||||
let visitorId: string | null = null;
|
||||
|
||||
try {
|
||||
logVisit(ip, body.path);
|
||||
visitorId = logVisit(clientAddress, userAgent, visitPath);
|
||||
} catch (e) {
|
||||
console.error('Failed to log visit to SQLite', e);
|
||||
}
|
||||
|
||||
const adminUrl = process.env.ADMIN_DASH_URL || 'http://admin_dash:3000/api/track';
|
||||
|
||||
fetch(adminUrl, {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({ path: body.path, timestamp: body.timestamp, ip }),
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'X-Forwarded-For': ip,
|
||||
},
|
||||
}).catch(e => console.error('Relay failed', e));
|
||||
relayVisit(visitPath, visitorId);
|
||||
|
||||
return NextResponse.json({ success: true });
|
||||
} catch {
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
const lineWidths = ['78%', '92%', '85%', '88%', '74%', '96%', '82%', '69%'];
|
||||
const lineWidths = ['w-[78%]', 'w-[92%]', 'w-[85%]', 'w-[88%]', 'w-[74%]', 'w-[96%]', 'w-[82%]', 'w-[69%]'];
|
||||
|
||||
export default function BlogPostLoading() {
|
||||
return (
|
||||
<div className="page-frame py-20 sm:py-24">
|
||||
<div className="mx-auto max-w-[70rem] animate-pulse xl:grid xl:grid-cols-[11rem_minmax(0,44rem)] xl:gap-x-10">
|
||||
<div className="mx-auto max-w-[70rem] motion-safe:animate-pulse xl:grid xl:grid-cols-[11rem_minmax(0,44rem)] xl:gap-x-10">
|
||||
<div className="hidden xl:block" />
|
||||
<div>
|
||||
<div className="mb-8 space-y-4 border-b border-line pb-8">
|
||||
@@ -13,7 +13,7 @@ export default function BlogPostLoading() {
|
||||
</div>
|
||||
<div className="space-y-4">
|
||||
{lineWidths.map((width) => (
|
||||
<div key={width} className="h-4 rounded-full bg-paper-strong" style={{ width }} />
|
||||
<div key={width} className={`h-4 rounded-full bg-paper-strong ${width}`} />
|
||||
))}
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@@ -1,38 +1,186 @@
|
||||
import { getPostBySlug, getPostSlugs } from '@/lib/mdx';
|
||||
import { MDXRemote } from 'next-mdx-remote/rsc';
|
||||
import fs from 'fs';
|
||||
import NextImage, { type ImageProps } from 'next/image';
|
||||
import Link from 'next/link';
|
||||
import path from 'path';
|
||||
import { notFound } from 'next/navigation';
|
||||
import { format } from 'date-fns';
|
||||
import rehypeAutolinkHeadings from 'rehype-autolink-headings';
|
||||
import { isValidElement } from 'react';
|
||||
import type { ComponentPropsWithoutRef, ReactNode } from 'react';
|
||||
import { TableOfContents } from '@/components/mdx/TableOfContents';
|
||||
import { SideNote } from '@/components/mdx/SideNote';
|
||||
import { Citation, Bibliography } from '@/components/mdx/Citation';
|
||||
import { MobileTableOfContents } from '@/components/mdx/MobileTableOfContents';
|
||||
import { formatPostDate } from '@/lib/format';
|
||||
|
||||
const slugify = (text: React.ReactNode): string => {
|
||||
if (!text) return '';
|
||||
const str = typeof text === 'string' ? text : String(text);
|
||||
return str
|
||||
const slugify = (text: string): string => {
|
||||
return text
|
||||
.toLowerCase()
|
||||
.replace(/[^a-z0-9]+/g, '-')
|
||||
.replace(/^-+|-+$/g, '');
|
||||
.replace(/^-+|-+$/g, '') || 'section';
|
||||
};
|
||||
|
||||
const components = {
|
||||
h1: (props: React.ComponentPropsWithoutRef<'h1'>) => <h1 {...props} id={slugify(props.children)} className="mt-12 scroll-mt-24 font-sans text-[2rem] font-medium leading-tight tracking-[-0.05em] text-ink sm:text-[2.5rem]" />,
|
||||
h2: (props: React.ComponentPropsWithoutRef<'h2'>) => <h2 {...props} id={slugify(props.children)} className="mt-14 scroll-mt-24 font-sans text-[1.65rem] font-medium leading-tight tracking-[-0.05em] text-ink sm:text-[2rem]" />,
|
||||
h3: (props: React.ComponentPropsWithoutRef<'h3'>) => <h3 {...props} id={slugify(props.children)} className="mt-10 scroll-mt-24 font-sans text-[1.22rem] font-medium tracking-[-0.03em] text-ink sm:text-[1.42rem]" />,
|
||||
p: (props: React.ComponentPropsWithoutRef<'p'>) => <p {...props} className="mb-6 text-[1.02rem] leading-[1.85] text-ink-soft" />,
|
||||
ul: (props: React.ComponentPropsWithoutRef<'ul'>) => <ul {...props} className="mb-6 list-disc space-y-2 pl-5 text-[0.98rem] leading-8 text-ink-soft marker:text-accent" />,
|
||||
ol: (props: React.ComponentPropsWithoutRef<'ol'>) => <ol {...props} className="mb-6 list-decimal space-y-2 pl-5 text-[0.98rem] leading-8 text-ink-soft marker:text-accent" />,
|
||||
blockquote: (props: React.ComponentPropsWithoutRef<'blockquote'>) => <blockquote {...props} className="my-10 border-l border-line-strong pl-5 text-[1.05rem] italic leading-8 text-ink-soft" />,
|
||||
code: (props: React.ComponentPropsWithoutRef<'code'>) => <code {...props} className="rounded bg-paper-strong px-1.5 py-0.5 font-mono text-[0.9em] text-ink" />,
|
||||
pre: (props: React.ComponentPropsWithoutRef<'pre'>) => <pre {...props} className="my-8 overflow-x-auto rounded-[1rem] border border-line bg-[#161412] p-5 text-sm text-paper shadow-[0_16px_40px_rgba(17,16,15,0.12)]" />,
|
||||
a: (props: React.ComponentPropsWithoutRef<'a'>) => <a {...props} className="font-medium text-ink underline decoration-line-strong underline-offset-4 transition-colors hover:text-accent hover:decoration-accent" />,
|
||||
const publicDirectory = path.join(process.cwd(), 'public');
|
||||
const imageDimensionCache = new Map<string, { width: number; height: number } | null>();
|
||||
const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
|
||||
const JPEG_START_OF_FRAME_MARKERS = new Set([
|
||||
0xc0, 0xc1, 0xc2, 0xc3, 0xc5, 0xc6, 0xc7, 0xc9, 0xca, 0xcb, 0xcd, 0xce, 0xcf,
|
||||
]);
|
||||
|
||||
function normalizeHeadingText(text: string) {
|
||||
return text
|
||||
.replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
|
||||
.replace(/[`*_~]/g, '')
|
||||
.replace(/<[^>]+>/g, '')
|
||||
.trim();
|
||||
}
|
||||
|
||||
function createSlugger() {
|
||||
const counts = new Map<string, number>();
|
||||
|
||||
return (text: string) => {
|
||||
const base = slugify(text);
|
||||
const count = counts.get(base) || 0;
|
||||
counts.set(base, count + 1);
|
||||
return count === 0 ? base : `${base}-${count}`;
|
||||
};
|
||||
}
|
||||
|
||||
function toPlainText(node: ReactNode): string {
|
||||
if (typeof node === 'string' || typeof node === 'number') return String(node);
|
||||
if (Array.isArray(node)) return node.map(toPlainText).join('');
|
||||
if (isValidElement<{ children?: ReactNode }>(node)) return toPlainText(node.props.children);
|
||||
return '';
|
||||
}
|
||||
|
||||
function extractHeadings(content: string) {
|
||||
const slugger = createSlugger();
|
||||
const headingLines = content.match(/^#{1,3}\s+(.+)$/gm) || [];
|
||||
|
||||
return headingLines.flatMap((line) => {
|
||||
const level = line.match(/^#+/)?.[0].length || 2;
|
||||
const text = normalizeHeadingText(line.replace(/^#+\s+/, ''));
|
||||
const id = slugger(text);
|
||||
return level > 1 ? [{ id, text, level }] : [];
|
||||
});
|
||||
}
|
||||
|
||||
function getPngDimensions(buffer: Buffer) {
|
||||
if (buffer.length < 24 || !buffer.subarray(0, 8).equals(PNG_SIGNATURE)) return null;
|
||||
return {
|
||||
width: buffer.readUInt32BE(16),
|
||||
height: buffer.readUInt32BE(20),
|
||||
};
|
||||
}
|
||||
|
||||
function getJpegDimensions(buffer: Buffer) {
|
||||
if (buffer.length < 4 || buffer[0] !== 0xff || buffer[1] !== 0xd8) return null;
|
||||
|
||||
let offset = 2;
|
||||
while (offset < buffer.length - 9) {
|
||||
if (buffer[offset] !== 0xff) {
|
||||
offset += 1;
|
||||
continue;
|
||||
}
|
||||
|
||||
const marker = buffer[offset + 1];
|
||||
offset += 2;
|
||||
|
||||
if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) {
|
||||
continue;
|
||||
}
|
||||
|
||||
const length = buffer.readUInt16BE(offset);
|
||||
if (length < 2 || offset + length > buffer.length) break;
|
||||
|
||||
if (JPEG_START_OF_FRAME_MARKERS.has(marker)) {
|
||||
return {
|
||||
height: buffer.readUInt16BE(offset + 3),
|
||||
width: buffer.readUInt16BE(offset + 5),
|
||||
};
|
||||
}
|
||||
|
||||
offset += length;
|
||||
}
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
function getLocalImageDimensions(src: string) {
|
||||
const pathname = src.split(/[?#]/, 1)[0];
|
||||
if (!pathname.startsWith('/') || pathname.includes('\0') || pathname.includes('..')) return null;
|
||||
|
||||
const imagePath = path.join(publicDirectory, pathname.replace(/^\/+/, ''));
|
||||
if (!imagePath.startsWith(`${publicDirectory}${path.sep}`)) return null;
|
||||
|
||||
if (imageDimensionCache.has(imagePath)) {
|
||||
return imageDimensionCache.get(imagePath) ?? null;
|
||||
}
|
||||
|
||||
try {
|
||||
const buffer = fs.readFileSync(imagePath);
|
||||
const dimensions = getPngDimensions(buffer) ?? getJpegDimensions(buffer);
|
||||
imageDimensionCache.set(imagePath, dimensions);
|
||||
return dimensions;
|
||||
} catch {
|
||||
imageDimensionCache.set(imagePath, null);
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function numericDimension(value: ImageProps['width'] | ImageProps['height']) {
|
||||
if (typeof value === 'number') return value;
|
||||
if (typeof value === 'string') {
|
||||
const parsed = Number(value);
|
||||
return Number.isFinite(parsed) ? parsed : undefined;
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
function MdxImage({ src, alt, width, height, sizes, ...props }: ImageProps) {
|
||||
if (typeof src !== 'string') {
|
||||
return <NextImage {...props} src={src} alt={alt} width={width} height={height} sizes={sizes} />;
|
||||
}
|
||||
|
||||
const localDimensions = getLocalImageDimensions(src);
|
||||
const resolvedWidth = numericDimension(width) ?? localDimensions?.width;
|
||||
const resolvedHeight = numericDimension(height) ?? localDimensions?.height;
|
||||
const displayWidth = Math.min(resolvedWidth ?? 704, 704);
|
||||
const responsiveSizes = sizes ?? `(max-width: 768px) 100vw, ${displayWidth}px`;
|
||||
|
||||
return (
|
||||
<NextImage
|
||||
{...props}
|
||||
src={src}
|
||||
alt={alt}
|
||||
width={resolvedWidth ?? 1200}
|
||||
height={resolvedHeight ?? 675}
|
||||
sizes={responsiveSizes}
|
||||
/>
|
||||
);
|
||||
}
|
||||
|
||||
function createMdxComponents() {
|
||||
const slugger = createSlugger();
|
||||
const getHeadingId = (children: ReactNode) => slugger(toPlainText(children));
|
||||
|
||||
return {
|
||||
h1: ({ children, ...props }: ComponentPropsWithoutRef<'h1'>) => <h1 {...props} id={getHeadingId(children)} className="mt-12 scroll-mt-24 font-sans text-[2rem] font-medium leading-tight text-ink sm:text-[2.5rem]">{children}</h1>,
|
||||
h2: ({ children, ...props }: ComponentPropsWithoutRef<'h2'>) => <h2 {...props} id={getHeadingId(children)} className="mt-14 scroll-mt-24 font-sans text-[1.65rem] font-medium leading-tight text-ink sm:text-[2rem]">{children}</h2>,
|
||||
h3: ({ children, ...props }: ComponentPropsWithoutRef<'h3'>) => <h3 {...props} id={getHeadingId(children)} className="mt-10 scroll-mt-24 font-sans text-[1.22rem] font-medium text-ink sm:text-[1.42rem]">{children}</h3>,
|
||||
p: (props: ComponentPropsWithoutRef<'p'>) => <p {...props} className="mb-6 text-[1.02rem] leading-[1.85] text-ink-soft" />,
|
||||
ul: (props: ComponentPropsWithoutRef<'ul'>) => <ul {...props} className="mb-6 list-disc space-y-2 pl-5 text-[0.98rem] leading-8 text-ink-soft marker:text-accent" />,
|
||||
ol: (props: ComponentPropsWithoutRef<'ol'>) => <ol {...props} className="mb-6 list-decimal space-y-2 pl-5 text-[0.98rem] leading-8 text-ink-soft marker:text-accent" />,
|
||||
blockquote: (props: ComponentPropsWithoutRef<'blockquote'>) => <blockquote {...props} className="my-10 border-l border-line-strong pl-5 text-[1.05rem] italic leading-8 text-ink-soft" />,
|
||||
code: (props: ComponentPropsWithoutRef<'code'>) => <code {...props} className="rounded bg-paper-strong px-1.5 py-0.5 font-mono text-[0.9em] text-ink" />,
|
||||
pre: (props: ComponentPropsWithoutRef<'pre'>) => <pre {...props} className="my-8 overflow-x-auto rounded-[1rem] border border-line bg-[#161412] p-5 text-sm text-paper shadow-[0_16px_40px_rgba(17,16,15,0.12)]" />,
|
||||
a: (props: ComponentPropsWithoutRef<'a'>) => <a {...props} className="font-medium text-ink underline decoration-line-strong underline-offset-4 transition-colors hover:text-accent hover:decoration-accent" />,
|
||||
Image: MdxImage,
|
||||
SideNote,
|
||||
Citation,
|
||||
Bibliography,
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
type Props = {
|
||||
params: Promise<{ slug: string }>;
|
||||
@@ -80,13 +228,8 @@ export default async function BlogPost({ params }: Props) {
|
||||
notFound();
|
||||
}
|
||||
|
||||
const headingLines = post.content.match(/^#{2,3}\s+(.+)$/gm) || [];
|
||||
const headings = headingLines.map((line) => {
|
||||
const level = line.match(/^#+/)?.[0].length || 2;
|
||||
const text = line.replace(/^#+\s+/, '').trim();
|
||||
const id = slugify(text);
|
||||
return { id, text, level };
|
||||
});
|
||||
const headings = extractHeadings(post.content);
|
||||
const mdxComponents = createMdxComponents();
|
||||
const tags = Array.isArray(post.metadata.tags) ? post.metadata.tags : [];
|
||||
|
||||
return (
|
||||
@@ -100,16 +243,16 @@ export default async function BlogPost({ params }: Props) {
|
||||
|
||||
<article className="w-full">
|
||||
<header className="mb-8 space-y-4 border-b border-line pb-8">
|
||||
<div className="flex flex-wrap items-center gap-x-4 gap-y-2 text-[0.72rem] font-mono uppercase tracking-[0.14em] text-muted-strong">
|
||||
<div className="flex flex-wrap items-center gap-x-4 gap-y-2 text-[0.72rem] font-mono uppercase text-muted-strong">
|
||||
<time dateTime={post.metadata.date}>
|
||||
{format(new Date(post.metadata.date), 'MMMM d, yyyy')}
|
||||
{formatPostDate(post.metadata.date)}
|
||||
</time>
|
||||
{tags.map((tag: string) => (
|
||||
<span key={tag}>{tag}</span>
|
||||
))}
|
||||
</div>
|
||||
|
||||
<h1 className="max-w-[38rem] text-balance font-sans text-[clamp(2.7rem,5.8vw,4.4rem)] font-medium leading-[0.94] tracking-[-0.08em] text-ink">
|
||||
<h1 className="max-w-[38rem] text-balance font-sans text-4xl font-medium leading-[0.98] text-ink sm:text-5xl lg:text-6xl">
|
||||
{post.metadata.title}
|
||||
</h1>
|
||||
|
||||
@@ -123,14 +266,7 @@ export default async function BlogPost({ params }: Props) {
|
||||
<div className="essay-prose relative mt-8 max-w-none xl:max-w-[44rem]">
|
||||
<MDXRemote
|
||||
source={post.content}
|
||||
components={components}
|
||||
options={{
|
||||
mdxOptions: {
|
||||
rehypePlugins: [
|
||||
[rehypeAutolinkHeadings, { behavior: 'wrap' }]
|
||||
]
|
||||
}
|
||||
}}
|
||||
components={mdxComponents}
|
||||
/>
|
||||
</div>
|
||||
|
||||
@@ -138,7 +274,7 @@ export default async function BlogPost({ params }: Props) {
|
||||
<Link href="/blog" className="transition-colors hover:text-ink">
|
||||
← Back to all posts
|
||||
</Link>
|
||||
<a href="#" className="transition-colors hover:text-ink">
|
||||
<a href="#main-content" className="transition-colors hover:text-ink">
|
||||
Scroll to top ↑
|
||||
</a>
|
||||
</div>
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
export default function BlogLoading() {
|
||||
return (
|
||||
<div className="page-frame py-20 sm:py-24">
|
||||
<div className="mx-auto max-w-[72rem] animate-pulse space-y-10">
|
||||
<div className="mx-auto max-w-[72rem] space-y-10 motion-safe:animate-pulse">
|
||||
<div className="space-y-4 border-b border-line pb-10">
|
||||
<div className="h-3 w-20 rounded-full bg-accent-soft" />
|
||||
<div className="h-14 w-2/3 rounded-[1rem] bg-paper-strong" />
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import type { Metadata } from 'next';
|
||||
import Link from 'next/link';
|
||||
import { format } from 'date-fns';
|
||||
import { formatPostDate } from '@/lib/format';
|
||||
import { getAllPosts } from '@/lib/mdx';
|
||||
|
||||
export const metadata: Metadata = {
|
||||
@@ -21,7 +21,7 @@ export default function BlogIndex() {
|
||||
<header className="space-y-4 border-b border-line pb-10">
|
||||
<div className="space-y-4">
|
||||
<p className="eyebrow">Writing</p>
|
||||
<h1 className="max-w-[40rem] text-balance font-sans text-[clamp(3rem,6vw,5rem)] font-medium leading-[0.94] tracking-[-0.08em] text-ink">
|
||||
<h1 className="max-w-[40rem] text-balance font-sans text-5xl font-medium leading-[0.96] text-ink sm:text-6xl lg:text-7xl">
|
||||
Notes on software, deep learning, and research.
|
||||
</h1>
|
||||
<p className="max-w-[34rem] text-[1rem] leading-8 text-muted">
|
||||
@@ -34,14 +34,14 @@ export default function BlogIndex() {
|
||||
{posts.map((post) => (
|
||||
<article key={post.slug} className="grid gap-3 py-6 md:grid-cols-[8rem_minmax(0,1fr)] md:gap-6">
|
||||
<div className="pt-1">
|
||||
<time dateTime={post.date} className="block font-mono text-[0.72rem] uppercase tracking-[0.18em] text-muted-strong">
|
||||
{format(new Date(post.date), 'MMMM d, yyyy')}
|
||||
<time dateTime={post.date} className="block font-mono text-[0.72rem] uppercase text-muted-strong">
|
||||
{formatPostDate(post.date)}
|
||||
</time>
|
||||
</div>
|
||||
|
||||
<div className="space-y-3">
|
||||
<Link href={`/blog/${post.slug}`} className="block">
|
||||
<h2 className="max-w-[38rem] font-sans text-[1.8rem] font-medium leading-tight tracking-[-0.05em] text-ink transition-colors hover:text-accent sm:text-[2.1rem]">
|
||||
<h2 className="max-w-[38rem] font-sans text-[1.8rem] font-medium leading-tight text-ink transition-colors hover:text-accent sm:text-[2.1rem]">
|
||||
{post.title}
|
||||
</h2>
|
||||
</Link>
|
||||
@@ -50,7 +50,7 @@ export default function BlogIndex() {
|
||||
{post.description}
|
||||
</p>
|
||||
|
||||
<div className="flex flex-wrap items-center gap-x-4 gap-y-2 pt-1 text-[0.76rem] font-mono uppercase tracking-[0.14em] text-muted-strong">
|
||||
<div className="flex flex-wrap items-center gap-x-4 gap-y-2 pt-1 text-[0.76rem] font-mono uppercase text-muted-strong">
|
||||
{post.tags?.map((tag) => (
|
||||
<span key={tag}>
|
||||
{tag}
|
||||
|
||||
@@ -7,16 +7,16 @@ export default function Error({
|
||||
reset: () => void;
|
||||
}) {
|
||||
return (
|
||||
<div className="min-h-[60vh] flex flex-col items-center justify-center px-6 text-center animate-fade-in">
|
||||
<h1 className="text-4xl font-bold tracking-tight text-zinc-900 dark:text-zinc-50 mb-4">
|
||||
<div className="page-frame flex min-h-[60vh] flex-col items-center justify-center px-6 text-center">
|
||||
<h1 className="mb-4 text-4xl font-medium text-ink">
|
||||
Something went wrong
|
||||
</h1>
|
||||
<p className="text-lg text-zinc-500 dark:text-zinc-400 mb-8">
|
||||
An unexpected error occurred.
|
||||
<p className="mb-8 text-lg text-muted">
|
||||
Refresh the page or try again.
|
||||
</p>
|
||||
<button
|
||||
onClick={reset}
|
||||
className="text-sm font-medium px-4 py-2 rounded bg-zinc-900 dark:bg-zinc-100 text-zinc-50 dark:text-zinc-900 hover:opacity-80 transition-opacity"
|
||||
className="rounded-md border border-line bg-paper-strong px-4 py-2 text-sm font-medium text-ink transition-colors hover:border-line-strong hover:text-accent"
|
||||
>
|
||||
Try again
|
||||
</button>
|
||||
|
||||
104
app/globals.css
104
app/globals.css
@@ -10,17 +10,17 @@
|
||||
--font-sans: var(--font-instrument-sans);
|
||||
--font-mono: var(--font-ibm-plex-mono);
|
||||
|
||||
--color-paper: #f4efe7;
|
||||
--color-paper-strong: #fbf7f0;
|
||||
--color-paper-overlay: rgba(244, 239, 231, 0.92);
|
||||
--color-ink: #171411;
|
||||
--color-ink-soft: #27221d;
|
||||
--color-muted: #5b544b;
|
||||
--color-muted-strong: #7a7166;
|
||||
--color-line: rgba(23, 20, 17, 0.12);
|
||||
--color-line-strong: rgba(23, 20, 17, 0.22);
|
||||
--color-accent: #8d6a42;
|
||||
--color-accent-soft: rgba(141, 106, 66, 0.12);
|
||||
--color-paper: #f6f7f3;
|
||||
--color-paper-strong: #fffefa;
|
||||
--color-paper-overlay: rgba(246, 247, 243, 0.94);
|
||||
--color-ink: #151718;
|
||||
--color-ink-soft: #28302f;
|
||||
--color-muted: #596461;
|
||||
--color-muted-strong: #6f7a76;
|
||||
--color-line: rgba(21, 23, 24, 0.12);
|
||||
--color-line-strong: rgba(21, 23, 24, 0.22);
|
||||
--color-accent: #176b5d;
|
||||
--color-accent-soft: rgba(23, 107, 93, 0.12);
|
||||
|
||||
--animate-fade-in: fade-in 0.7s cubic-bezier(0.16, 1, 0.3, 1);
|
||||
--animate-fade-up: fade-up 0.8s cubic-bezier(0.16, 1, 0.3, 1) both;
|
||||
@@ -54,27 +54,27 @@
|
||||
color-scheme: light;
|
||||
--background: var(--color-paper);
|
||||
--foreground: var(--color-ink);
|
||||
--page-wash: rgba(170, 142, 97, 0.09);
|
||||
--page-wash: rgba(23, 107, 93, 0.08);
|
||||
--page-shadow: rgba(255, 255, 255, 0.24);
|
||||
--grain-opacity: 0.03;
|
||||
}
|
||||
|
||||
:root[data-theme="dark"] {
|
||||
color-scheme: dark;
|
||||
--background: #11100f;
|
||||
--foreground: #f2ede4;
|
||||
--color-paper: #11100f;
|
||||
--color-paper-strong: #171614;
|
||||
--color-paper-overlay: rgba(17, 16, 15, 0.92);
|
||||
--color-ink: #f2ede4;
|
||||
--color-ink-soft: #dfd7cb;
|
||||
--color-muted: #b3a99d;
|
||||
--color-muted-strong: #d0c4b5;
|
||||
--color-line: rgba(242, 237, 228, 0.12);
|
||||
--color-line-strong: rgba(242, 237, 228, 0.22);
|
||||
--color-accent: #d0af80;
|
||||
--color-accent-soft: rgba(208, 175, 128, 0.14);
|
||||
--page-wash: rgba(208, 175, 128, 0.08);
|
||||
--background: #111315;
|
||||
--foreground: #eff4ef;
|
||||
--color-paper: #111315;
|
||||
--color-paper-strong: #181c1d;
|
||||
--color-paper-overlay: rgba(17, 19, 21, 0.94);
|
||||
--color-ink: #eff4ef;
|
||||
--color-ink-soft: #d9e2dc;
|
||||
--color-muted: #aab7b1;
|
||||
--color-muted-strong: #c2d0c9;
|
||||
--color-line: rgba(239, 244, 239, 0.12);
|
||||
--color-line-strong: rgba(239, 244, 239, 0.22);
|
||||
--color-accent: #7bc7b5;
|
||||
--color-accent-soft: rgba(123, 199, 181, 0.16);
|
||||
--page-wash: rgba(88, 161, 172, 0.1);
|
||||
--page-shadow: rgba(255, 255, 255, 0.02);
|
||||
--grain-opacity: 0.055;
|
||||
}
|
||||
@@ -82,20 +82,20 @@
|
||||
@media (prefers-color-scheme: dark) {
|
||||
:root:not([data-theme="light"]) {
|
||||
color-scheme: dark;
|
||||
--background: #11100f;
|
||||
--foreground: #f2ede4;
|
||||
--color-paper: #11100f;
|
||||
--color-paper-strong: #171614;
|
||||
--color-paper-overlay: rgba(17, 16, 15, 0.92);
|
||||
--color-ink: #f2ede4;
|
||||
--color-ink-soft: #dfd7cb;
|
||||
--color-muted: #b3a99d;
|
||||
--color-muted-strong: #d0c4b5;
|
||||
--color-line: rgba(242, 237, 228, 0.12);
|
||||
--color-line-strong: rgba(242, 237, 228, 0.22);
|
||||
--color-accent: #d0af80;
|
||||
--color-accent-soft: rgba(208, 175, 128, 0.14);
|
||||
--page-wash: rgba(208, 175, 128, 0.08);
|
||||
--background: #111315;
|
||||
--foreground: #eff4ef;
|
||||
--color-paper: #111315;
|
||||
--color-paper-strong: #181c1d;
|
||||
--color-paper-overlay: rgba(17, 19, 21, 0.94);
|
||||
--color-ink: #eff4ef;
|
||||
--color-ink-soft: #d9e2dc;
|
||||
--color-muted: #aab7b1;
|
||||
--color-muted-strong: #c2d0c9;
|
||||
--color-line: rgba(239, 244, 239, 0.12);
|
||||
--color-line-strong: rgba(239, 244, 239, 0.22);
|
||||
--color-accent: #7bc7b5;
|
||||
--color-accent-soft: rgba(123, 199, 181, 0.16);
|
||||
--page-wash: rgba(88, 161, 172, 0.1);
|
||||
--page-shadow: rgba(255, 255, 255, 0.02);
|
||||
--grain-opacity: 0.055;
|
||||
}
|
||||
@@ -114,11 +114,11 @@ body {
|
||||
position: relative;
|
||||
background-image: linear-gradient(180deg, var(--page-shadow), transparent 28%);
|
||||
-webkit-font-smoothing: antialiased;
|
||||
letter-spacing: 0.012em;
|
||||
letter-spacing: 0;
|
||||
}
|
||||
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
letter-spacing: 0.005em;
|
||||
letter-spacing: 0;
|
||||
}
|
||||
|
||||
body::before,
|
||||
@@ -138,7 +138,7 @@ body::before {
|
||||
body::after {
|
||||
background:
|
||||
radial-gradient(60rem 24rem at 50% -8%, var(--page-wash), transparent 70%),
|
||||
radial-gradient(24rem 18rem at 0% 0%, rgba(0, 0, 0, 0.02), transparent 74%);
|
||||
radial-gradient(24rem 18rem at 0% 0%, rgba(63, 92, 120, 0.03), transparent 74%);
|
||||
opacity: 1;
|
||||
}
|
||||
|
||||
@@ -171,7 +171,7 @@ a {
|
||||
color: var(--color-muted-strong);
|
||||
font-family: var(--font-mono), monospace;
|
||||
font-size: 0.68rem;
|
||||
letter-spacing: 0.16em;
|
||||
letter-spacing: 0;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
@@ -187,7 +187,7 @@ a {
|
||||
position: absolute;
|
||||
background-image:
|
||||
radial-gradient(68rem 28rem at 50% -10%, var(--page-wash), transparent 72%),
|
||||
radial-gradient(40rem 24rem at 100% 0%, rgba(141, 106, 66, 0.05), transparent 76%);
|
||||
radial-gradient(40rem 24rem at 100% 0%, rgba(63, 92, 120, 0.05), transparent 76%);
|
||||
opacity: 0.9;
|
||||
}
|
||||
|
||||
@@ -233,9 +233,13 @@ a {
|
||||
}
|
||||
|
||||
.essay-prose img {
|
||||
display: block;
|
||||
height: auto;
|
||||
margin-block: 2.25rem;
|
||||
max-width: 100%;
|
||||
border: 1px solid var(--color-line);
|
||||
border-radius: 1rem;
|
||||
border-radius: 0.75rem;
|
||||
background: var(--color-paper-strong);
|
||||
}
|
||||
|
||||
.essay-prose pre code,
|
||||
@@ -277,4 +281,12 @@ a {
|
||||
html {
|
||||
scroll-behavior: auto;
|
||||
}
|
||||
|
||||
*,
|
||||
*::before,
|
||||
*::after {
|
||||
animation-duration: 1ms !important;
|
||||
animation-iteration-count: 1 !important;
|
||||
transition-duration: 1ms !important;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -4,6 +4,7 @@ import {
|
||||
Instrument_Sans,
|
||||
} from "next/font/google";
|
||||
import Script from "next/script";
|
||||
import { Suspense } from "react";
|
||||
import "./globals.css";
|
||||
import { Analytics } from "@/components/Analytics";
|
||||
import { AmbientCanvas } from "@/components/layout/AmbientCanvas";
|
||||
@@ -53,17 +54,7 @@ export default function RootLayout({
|
||||
<body
|
||||
className={`${instrumentSans.variable} ${ibmPlexMono.variable} min-h-screen bg-paper font-sans text-ink antialiased`}
|
||||
>
|
||||
<Script id="theme-init" strategy="beforeInteractive">
|
||||
{`
|
||||
try {
|
||||
const storedTheme = localStorage.getItem("theme-preference");
|
||||
const theme = storedTheme === "light" || storedTheme === "dark"
|
||||
? storedTheme
|
||||
: (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
|
||||
document.documentElement.dataset.theme = theme;
|
||||
} catch {}
|
||||
`}
|
||||
</Script>
|
||||
<Script src="/theme-init.js" strategy="beforeInteractive" />
|
||||
<a
|
||||
href="#main-content"
|
||||
className="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-[100] focus:rounded-full focus:bg-paper-strong focus:px-4 focus:py-2 focus:text-sm focus:font-medium focus:text-ink focus:shadow-[0_12px_30px_rgba(23,28,24,0.08)]"
|
||||
@@ -77,7 +68,9 @@ export default function RootLayout({
|
||||
{children}
|
||||
</main>
|
||||
<Footer />
|
||||
<Suspense fallback={null}>
|
||||
<Analytics />
|
||||
</Suspense>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -2,14 +2,14 @@ import Link from 'next/link';
|
||||
|
||||
export default function NotFound() {
|
||||
return (
|
||||
<div className="min-h-[60vh] flex flex-col items-center justify-center px-6 text-center animate-fade-in">
|
||||
<h1 className="text-6xl font-bold tracking-tight text-zinc-900 dark:text-zinc-50 mb-4">404</h1>
|
||||
<p className="text-lg text-zinc-500 dark:text-zinc-400 mb-8">
|
||||
<div className="page-frame flex min-h-[60vh] flex-col items-center justify-center px-6 text-center">
|
||||
<h1 className="mb-4 text-6xl font-medium text-ink">404</h1>
|
||||
<p className="mb-8 text-lg text-muted">
|
||||
This page doesn't exist.
|
||||
</p>
|
||||
<Link
|
||||
href="/"
|
||||
className="text-sm font-medium text-zinc-900 dark:text-zinc-100 underline decoration-zinc-300 dark:decoration-zinc-700 underline-offset-4 hover:decoration-zinc-900 dark:hover:decoration-zinc-100 transition-all"
|
||||
className="text-sm font-medium text-ink underline decoration-line-strong underline-offset-4 transition-colors hover:text-accent hover:decoration-accent"
|
||||
>
|
||||
← Back to home
|
||||
</Link>
|
||||
|
||||
@@ -15,7 +15,7 @@ export default function Home() {
|
||||
<p className="eyebrow">Akshay Kolli / Research + Writing</p>
|
||||
|
||||
<div className="space-y-4">
|
||||
<h1 className="max-w-[34rem] text-balance font-sans text-[clamp(3.15rem,6vw,5.2rem)] font-medium leading-[0.94] tracking-[-0.085em] text-ink">
|
||||
<h1 className="max-w-[34rem] text-balance font-sans text-5xl font-medium leading-[0.96] text-ink sm:text-6xl lg:text-7xl">
|
||||
World models and reinforcement learning.
|
||||
</h1>
|
||||
|
||||
@@ -49,6 +49,7 @@ export default function Home() {
|
||||
alt="Akshay Kolli"
|
||||
fill
|
||||
priority
|
||||
sizes="(min-width: 1024px) 15rem, 12rem"
|
||||
className="object-cover object-center"
|
||||
/>
|
||||
</div>
|
||||
|
||||
@@ -71,12 +71,20 @@ export default function ResumePage() {
|
||||
<header className="space-y-4 border-b border-line pb-10">
|
||||
<div className="space-y-4">
|
||||
<p className="eyebrow">Resume</p>
|
||||
<h1 className="max-w-[40rem] text-balance font-sans text-[clamp(3rem,6vw,4.8rem)] font-medium leading-[0.94] tracking-[-0.08em] text-ink">
|
||||
<h1 className="max-w-[40rem] text-balance font-sans text-5xl font-medium leading-[0.96] text-ink sm:text-6xl lg:text-7xl">
|
||||
Experience, education, and technical depth.
|
||||
</h1>
|
||||
<p className="max-w-[34rem] text-[1rem] leading-8 text-muted">
|
||||
Research, engineering, and systems work across academia and industry.
|
||||
</p>
|
||||
<div className="flex flex-wrap gap-x-5 gap-y-2 text-[0.92rem] text-ink">
|
||||
<a href="/files/Resume_latest.pdf" className="transition-colors hover:text-accent">
|
||||
Open PDF
|
||||
</a>
|
||||
<a href="/files/Resume_latest.pdf" download className="transition-colors hover:text-accent">
|
||||
Download PDF
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
|
||||
@@ -85,12 +93,12 @@ export default function ResumePage() {
|
||||
<div className="space-y-8">
|
||||
{experience.map((item) => (
|
||||
<article key={`${item.title}-${item.period}`} className="grid gap-2 md:grid-cols-[8rem_minmax(0,1fr)] md:gap-5">
|
||||
<p className="font-mono text-[0.72rem] uppercase tracking-[0.18em] text-muted-strong">
|
||||
<p className="font-mono text-[0.72rem] uppercase text-muted-strong">
|
||||
{item.period}
|
||||
</p>
|
||||
<div className="space-y-2">
|
||||
<div className="space-y-1">
|
||||
<h2 className="font-sans text-[1.35rem] font-medium leading-tight tracking-[-0.04em] text-ink sm:text-[1.55rem]">
|
||||
<h2 className="font-sans text-[1.35rem] font-medium leading-tight text-ink sm:text-[1.55rem]">
|
||||
{item.title}
|
||||
</h2>
|
||||
<p className="text-[0.96rem] leading-7 text-muted">
|
||||
@@ -115,11 +123,11 @@ export default function ResumePage() {
|
||||
<div className="space-y-6">
|
||||
{education.map((item) => (
|
||||
<article key={`${item.title}-${item.period}`} className="grid gap-2 md:grid-cols-[8rem_minmax(0,1fr)] md:gap-5">
|
||||
<p className="font-mono text-[0.72rem] uppercase tracking-[0.18em] text-muted-strong">
|
||||
<p className="font-mono text-[0.72rem] uppercase text-muted-strong">
|
||||
{item.period}
|
||||
</p>
|
||||
<div className="space-y-1">
|
||||
<h2 className="font-sans text-[1.35rem] font-medium leading-tight tracking-[-0.04em] text-ink sm:text-[1.55rem]">
|
||||
<h2 className="font-sans text-[1.35rem] font-medium leading-tight text-ink sm:text-[1.55rem]">
|
||||
{item.title}
|
||||
</h2>
|
||||
<p className="text-[0.96rem] leading-7 text-muted">
|
||||
@@ -136,7 +144,7 @@ export default function ResumePage() {
|
||||
<div className="space-y-4">
|
||||
{skills.map((group) => (
|
||||
<article key={group.label} className="grid gap-2 md:grid-cols-[9rem_minmax(0,1fr)] md:gap-5">
|
||||
<h2 className="font-sans text-[1rem] font-medium tracking-[-0.02em] text-ink">
|
||||
<h2 className="font-sans text-[1rem] font-medium text-ink">
|
||||
{group.label}
|
||||
</h2>
|
||||
<p className="text-[0.96rem] leading-7 text-muted">
|
||||
|
||||
@@ -3,6 +3,7 @@ import { getAllPosts } from '@/lib/mdx';
|
||||
|
||||
export default function sitemap(): MetadataRoute.Sitemap {
|
||||
const posts = getAllPosts();
|
||||
const latestPostDate = posts[0]?.date ? new Date(posts[0].date) : undefined;
|
||||
|
||||
const blogEntries: MetadataRoute.Sitemap = posts.map((post) => ({
|
||||
url: `https://akkolli.net/blog/${post.slug}`,
|
||||
@@ -10,9 +11,9 @@ export default function sitemap(): MetadataRoute.Sitemap {
|
||||
}));
|
||||
|
||||
return [
|
||||
{ url: 'https://akkolli.net', lastModified: new Date() },
|
||||
{ url: 'https://akkolli.net/blog', lastModified: new Date() },
|
||||
{ url: 'https://akkolli.net/resume', lastModified: new Date() },
|
||||
{ url: 'https://akkolli.net', lastModified: latestPostDate },
|
||||
{ url: 'https://akkolli.net/blog', lastModified: latestPostDate },
|
||||
{ url: 'https://akkolli.net/resume' },
|
||||
...blogEntries,
|
||||
];
|
||||
}
|
||||
|
||||
@@ -1,10 +1,13 @@
|
||||
'use client';
|
||||
|
||||
import { useEffect } from 'react';
|
||||
import { usePathname } from 'next/navigation';
|
||||
import { usePathname, useSearchParams } from 'next/navigation';
|
||||
|
||||
export function Analytics() {
|
||||
const pathname = usePathname();
|
||||
const searchParams = useSearchParams();
|
||||
const queryString = searchParams.toString();
|
||||
const visitPath = queryString ? `${pathname}?${queryString}` : pathname;
|
||||
|
||||
useEffect(() => {
|
||||
// Send beacon on mount and path change
|
||||
@@ -13,21 +16,21 @@ export function Analytics() {
|
||||
// Send beacon to THIS website's API, which will relay it to the admin dash
|
||||
await fetch('/api/analytics', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify({ path: pathname, timestamp: Date.now() }),
|
||||
body: JSON.stringify({ path: visitPath }),
|
||||
headers: {
|
||||
'Content-Type': 'application/json',
|
||||
'X-Analytics-Key': process.env.NEXT_PUBLIC_ANALYTICS_KEY || 'default-analytics-key',
|
||||
},
|
||||
keepalive: true,
|
||||
});
|
||||
} catch (e) {
|
||||
// Fail silently
|
||||
if (process.env.NODE_ENV !== 'production') {
|
||||
console.error('Analytics fail', e);
|
||||
}
|
||||
}
|
||||
};
|
||||
|
||||
sendBeacon();
|
||||
}, [pathname]);
|
||||
}, [visitPath]);
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
@@ -2,19 +2,26 @@
|
||||
|
||||
import Link from 'next/link';
|
||||
import { usePathname } from 'next/navigation';
|
||||
import { useEffect, useRef, useState } from 'react';
|
||||
import { useEffect, useId, useRef, useState } from 'react';
|
||||
import { ThemeToggle } from './ThemeToggle';
|
||||
|
||||
const navItems = [
|
||||
{ href: '/', label: 'Home' },
|
||||
{ href: '/blog', label: 'Writing' },
|
||||
{ href: '/resume', label: 'Resume' },
|
||||
];
|
||||
|
||||
export function Navbar() {
|
||||
const pathname = usePathname();
|
||||
const [menuOpen, setMenuOpen] = useState(false);
|
||||
const menuId = useId();
|
||||
const menuRef = useRef<HTMLDivElement | null>(null);
|
||||
|
||||
const isActive = (path: string) => pathname?.startsWith(path);
|
||||
|
||||
useEffect(() => {
|
||||
setMenuOpen(false);
|
||||
}, [pathname]);
|
||||
const isActive = (path: string) => path === '/' ? pathname === '/' : pathname?.startsWith(path);
|
||||
const linkClass = (path: string) => `relative py-1 transition-colors after:absolute after:inset-x-0 after:-bottom-0.5 after:h-px after:origin-left after:bg-accent after:transition-transform ${isActive(path)
|
||||
? 'text-ink after:scale-x-100'
|
||||
: 'hover:text-ink after:scale-x-0 hover:after:scale-x-100'
|
||||
}`;
|
||||
|
||||
useEffect(() => {
|
||||
if (!menuOpen) return;
|
||||
@@ -39,55 +46,48 @@ export function Navbar() {
|
||||
return (
|
||||
<nav
|
||||
aria-label="Main navigation"
|
||||
className="fixed left-0 top-0 z-50 w-full border-b border-line bg-paper-overlay"
|
||||
className="fixed left-0 top-0 z-50 w-full border-b border-line bg-paper-overlay shadow-[0_1px_0_rgba(255,255,255,0.26)] backdrop-blur-xl"
|
||||
>
|
||||
<div className="mx-auto flex h-14 max-w-[72rem] items-center justify-between gap-6 px-5 sm:px-6">
|
||||
<Link href="/" className="flex items-baseline gap-2.5 transition-opacity hover:opacity-75">
|
||||
<span className="text-[0.96rem] font-medium tracking-[-0.03em] text-ink">
|
||||
<div className="mx-auto flex h-14 max-w-[72rem] items-center justify-between gap-4 px-5 sm:px-6">
|
||||
<Link href="/" className="flex min-w-0 items-baseline gap-2.5 transition-opacity hover:opacity-75">
|
||||
<span className="truncate text-[0.96rem] font-medium text-ink">
|
||||
Akshay Kolli
|
||||
</span>
|
||||
<span className="hidden font-mono text-[0.65rem] uppercase tracking-[0.14em] text-muted-strong sm:inline">
|
||||
<span className="hidden font-mono text-[0.65rem] uppercase text-muted-strong sm:inline">
|
||||
Research
|
||||
</span>
|
||||
</Link>
|
||||
|
||||
<div className="flex items-center gap-4 text-[0.68rem] font-mono uppercase tracking-[0.14em] text-muted-strong sm:gap-5">
|
||||
<div className="flex items-center gap-2 text-[0.68rem] font-mono uppercase text-muted-strong sm:gap-5">
|
||||
<div className="hidden items-center gap-5 sm:flex">
|
||||
{navItems.map((item) => (
|
||||
<Link
|
||||
href="/"
|
||||
className={`transition-colors ${pathname === '/' ? 'text-ink' : 'hover:text-ink'}`}
|
||||
key={item.href}
|
||||
href={item.href}
|
||||
aria-current={isActive(item.href) ? 'page' : undefined}
|
||||
className={linkClass(item.href)}
|
||||
>
|
||||
Home
|
||||
</Link>
|
||||
<Link
|
||||
href="/blog"
|
||||
className={`transition-colors ${isActive('/blog') ? 'text-ink' : 'hover:text-ink'}`}
|
||||
>
|
||||
Writing
|
||||
</Link>
|
||||
<Link
|
||||
href="/resume"
|
||||
className={`transition-colors ${isActive('/resume') ? 'text-ink' : 'hover:text-ink'}`}
|
||||
>
|
||||
Resume
|
||||
{item.label}
|
||||
</Link>
|
||||
))}
|
||||
<a
|
||||
href="https://github.com/akkolli"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
aria-label="GitHub profile"
|
||||
className="hidden transition-colors hover:text-ink sm:block"
|
||||
className="transition-colors hover:text-ink"
|
||||
>
|
||||
GitHub
|
||||
</a>
|
||||
|
||||
</div>
|
||||
<div ref={menuRef} className="relative sm:hidden">
|
||||
<button
|
||||
type="button"
|
||||
onClick={() => setMenuOpen((open) => !open)}
|
||||
aria-label="More navigation items"
|
||||
aria-haspopup="menu"
|
||||
aria-expanded={menuOpen}
|
||||
className="inline-flex h-8 w-8 items-center justify-center rounded-full border border-transparent text-muted-strong transition-colors hover:border-line hover:text-ink"
|
||||
aria-controls={menuId}
|
||||
className="inline-flex h-8 w-8 items-center justify-center rounded-full border border-transparent text-muted-strong transition-colors hover:border-line hover:bg-accent-soft hover:text-ink"
|
||||
>
|
||||
<svg
|
||||
aria-hidden="true"
|
||||
@@ -103,18 +103,31 @@ export function Navbar() {
|
||||
</button>
|
||||
{menuOpen && (
|
||||
<div
|
||||
role="menu"
|
||||
className="absolute right-0 top-[calc(100%+0.5rem)] min-w-[9rem] overflow-hidden rounded-md border border-line bg-paper-strong shadow-lg"
|
||||
id={menuId}
|
||||
className="absolute right-0 top-[calc(100%+0.65rem)] min-w-[10.5rem] overflow-hidden rounded-md border border-line bg-paper-strong shadow-[0_18px_46px_rgba(17,19,21,0.13)]"
|
||||
>
|
||||
<nav aria-label="Mobile navigation" className="py-1">
|
||||
{navItems.map((item) => (
|
||||
<Link
|
||||
key={item.href}
|
||||
href={item.href}
|
||||
aria-current={isActive(item.href) ? 'page' : undefined}
|
||||
onClick={() => setMenuOpen(false)}
|
||||
className={`block px-3.5 py-2.5 text-[0.68rem] font-mono uppercase transition-colors hover:bg-accent-soft hover:text-ink ${isActive(item.href) ? 'bg-accent-soft text-ink' : 'text-muted-strong'}`}
|
||||
>
|
||||
{item.label}
|
||||
</Link>
|
||||
))}
|
||||
<a
|
||||
href="https://github.com/akkolli"
|
||||
target="_blank"
|
||||
rel="noopener noreferrer"
|
||||
role="menuitem"
|
||||
className="block px-3.5 py-2.5 text-[0.68rem] font-mono uppercase tracking-[0.14em] text-muted-strong transition-colors hover:bg-accent-soft hover:text-ink"
|
||||
aria-label="GitHub profile"
|
||||
className="block px-3.5 py-2.5 text-[0.68rem] font-mono uppercase text-muted-strong transition-colors hover:bg-accent-soft hover:text-ink"
|
||||
>
|
||||
GitHub
|
||||
</a>
|
||||
</nav>
|
||||
</div>
|
||||
)}
|
||||
</div>
|
||||
|
||||
@@ -1,24 +1,64 @@
|
||||
"use client";
|
||||
|
||||
import { useSyncExternalStore } from "react";
|
||||
|
||||
type Theme = "light" | "dark";
|
||||
|
||||
const STORAGE_KEY = "theme-preference";
|
||||
const THEME_CHANGE_EVENT = "theme-preference-change";
|
||||
|
||||
function getSystemTheme(): Theme {
|
||||
return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
|
||||
}
|
||||
|
||||
function applyTheme(theme: Theme) {
|
||||
document.documentElement.dataset.theme = theme;
|
||||
try {
|
||||
window.localStorage.setItem(STORAGE_KEY, theme);
|
||||
} catch {
|
||||
}
|
||||
window.dispatchEvent(new Event(THEME_CHANGE_EVENT));
|
||||
}
|
||||
|
||||
function getCurrentTheme(): Theme {
|
||||
if (typeof window === "undefined") return "light";
|
||||
|
||||
const currentTheme = document.documentElement.dataset.theme;
|
||||
if (currentTheme === "light" || currentTheme === "dark") {
|
||||
return currentTheme;
|
||||
}
|
||||
|
||||
return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
|
||||
return getSystemTheme();
|
||||
}
|
||||
|
||||
function subscribeToTheme(callback: () => void) {
|
||||
const mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
|
||||
const handleSystemThemeChange = () => {
|
||||
try {
|
||||
if (!window.localStorage.getItem(STORAGE_KEY)) {
|
||||
document.documentElement.dataset.theme = getSystemTheme();
|
||||
}
|
||||
} catch {
|
||||
document.documentElement.dataset.theme = getSystemTheme();
|
||||
}
|
||||
|
||||
callback();
|
||||
};
|
||||
|
||||
mediaQuery.addEventListener("change", handleSystemThemeChange);
|
||||
window.addEventListener("storage", callback);
|
||||
window.addEventListener(THEME_CHANGE_EVENT, callback);
|
||||
|
||||
return () => {
|
||||
mediaQuery.removeEventListener("change", handleSystemThemeChange);
|
||||
window.removeEventListener("storage", callback);
|
||||
window.removeEventListener(THEME_CHANGE_EVENT, callback);
|
||||
};
|
||||
}
|
||||
|
||||
export function ThemeToggle() {
|
||||
const theme = useSyncExternalStore(subscribeToTheme, getCurrentTheme, () => "light");
|
||||
|
||||
const toggleTheme = () => {
|
||||
const nextTheme = getCurrentTheme() === "dark" ? "light" : "dark";
|
||||
applyTheme(nextTheme);
|
||||
@@ -29,8 +69,9 @@ export function ThemeToggle() {
|
||||
type="button"
|
||||
onClick={toggleTheme}
|
||||
title="Toggle color theme"
|
||||
aria-label="Toggle color theme"
|
||||
className="theme-toggle inline-flex h-8 w-8 items-center justify-center rounded-full border border-transparent text-muted-strong transition-colors hover:border-line hover:text-ink"
|
||||
aria-label={`Switch to ${theme === "dark" ? "light" : "dark"} theme`}
|
||||
aria-pressed={theme === "dark"}
|
||||
className="theme-toggle inline-flex h-8 w-8 items-center justify-center rounded-full border border-transparent text-muted-strong transition-colors hover:border-line hover:bg-accent-soft hover:text-ink"
|
||||
>
|
||||
<span className="sr-only">Toggle color theme</span>
|
||||
<svg
|
||||
|
||||
@@ -8,16 +8,16 @@ export function MobileTableOfContents({ headings }: { headings: Heading[] }) {
|
||||
if (headings.length === 0) return null;
|
||||
|
||||
return (
|
||||
<details className="mb-8 border-y border-line py-4">
|
||||
<summary className="eyebrow cursor-pointer list-none">
|
||||
Contents
|
||||
<details className="group mb-8 border-y border-line py-4">
|
||||
<summary className="flex cursor-pointer list-none items-center justify-between gap-4">
|
||||
<span className="eyebrow">Contents</span>
|
||||
<span aria-hidden className="text-base leading-none text-muted-strong transition-transform group-open:rotate-45">
|
||||
+
|
||||
</span>
|
||||
</summary>
|
||||
<ul className="mt-4 space-y-2">
|
||||
{headings.map((heading) => (
|
||||
<li
|
||||
key={heading.id}
|
||||
style={{ paddingLeft: `${(heading.level - 2) * 12}px` }}
|
||||
>
|
||||
<li key={heading.id} className={heading.level > 2 ? 'pl-4' : undefined}>
|
||||
<a
|
||||
href={`#${heading.id}`}
|
||||
className="block text-[0.94rem] leading-7 text-muted transition-colors hover:text-ink"
|
||||
|
||||
@@ -9,46 +9,30 @@ type Heading = {
|
||||
};
|
||||
|
||||
export function TableOfContents({ headings }: { headings: Heading[] }) {
|
||||
const [activeId, setActiveId] = useState<string>('');
|
||||
const [activeId, setActiveId] = useState<string>(() => headings[0]?.id ?? '');
|
||||
|
||||
useEffect(() => {
|
||||
const handleScroll = () => {
|
||||
const headingElements = headings.map((heading) => ({
|
||||
id: heading.id,
|
||||
element: document.getElementById(heading.id),
|
||||
}));
|
||||
const elements = headings
|
||||
.map((heading) => document.getElementById(heading.id))
|
||||
.filter((element): element is HTMLElement => Boolean(element));
|
||||
|
||||
// Find the first heading that is currently visible or just above the fold
|
||||
// We look for headings that are above the 150px mark
|
||||
let currentActiveId = '';
|
||||
if (elements.length === 0) return;
|
||||
|
||||
for (const { id, element } of headingElements) {
|
||||
if (!element) continue;
|
||||
const rect = element.getBoundingClientRect();
|
||||
const observer = new IntersectionObserver((entries) => {
|
||||
const visible = entries
|
||||
.filter((entry) => entry.isIntersecting)
|
||||
.sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);
|
||||
|
||||
// If the heading is within the top portion of the screen
|
||||
// OR if we haven't found a better one yet, this one 'might' be it
|
||||
// We basically want the *last* heading that has a 'top' value <= some threshold
|
||||
if (rect.top <= 150) {
|
||||
currentActiveId = id;
|
||||
}
|
||||
if (visible[0]?.target.id) {
|
||||
setActiveId(visible[0].target.id);
|
||||
}
|
||||
}, {
|
||||
rootMargin: '-20% 0px -65% 0px',
|
||||
threshold: 0,
|
||||
});
|
||||
|
||||
// If we are at the very bottom, it's likely the last item
|
||||
if ((window.innerHeight + window.scrollY) >= document.body.offsetHeight - 50) {
|
||||
if (headings.length > 0) currentActiveId = headings[headings.length - 1].id;
|
||||
}
|
||||
|
||||
if (currentActiveId) {
|
||||
setActiveId(currentActiveId);
|
||||
}
|
||||
};
|
||||
|
||||
window.addEventListener('scroll', handleScroll, { passive: true });
|
||||
// Trigger once on mount
|
||||
handleScroll();
|
||||
|
||||
return () => window.removeEventListener('scroll', handleScroll);
|
||||
elements.forEach((element) => observer.observe(element));
|
||||
return () => observer.disconnect();
|
||||
}, [headings]);
|
||||
|
||||
if (headings.length === 0) return null;
|
||||
@@ -58,10 +42,7 @@ export function TableOfContents({ headings }: { headings: Heading[] }) {
|
||||
<h4 className="eyebrow mb-4">Contents</h4>
|
||||
<ul className="space-y-2">
|
||||
{Array.isArray(headings) && headings.map((heading) => (
|
||||
<li
|
||||
key={heading.id}
|
||||
style={{ paddingLeft: `${(heading.level - 2) * 10}px` }}
|
||||
>
|
||||
<li key={heading.id} className={heading.level > 2 ? 'pl-3' : undefined}>
|
||||
<a
|
||||
href={`#${heading.id}`}
|
||||
className={`block text-[0.82rem] leading-6 transition-colors ${activeId === heading.id
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
title: 'Blackwell: Datacenter vs GeForce GPUs'
|
||||
date: '2026-02-27'
|
||||
description: 'Jensen scammed us.'
|
||||
description: 'GeForce Blackwell and datacenter Blackwell expose meaningfully different tensor-core capabilities.'
|
||||
tags: ['Nvidia', 'GPU', 'GPU Kernel']
|
||||
---
|
||||
|
||||
@@ -28,24 +28,43 @@ any kind of work load. Why did I have to dig so hard to find this information? T
|
||||
|
||||
I needed to confirm this myself. <SideNote>NVFP4 is Nvidia's new low precision format. </SideNote> I downloaded the cutlass repo and ran the nvfp4 matrix multiply example. Here's what I got
|
||||
|
||||
|
||||
<Image
|
||||
src="/images/1_blackwell_dc_vs_gf/5090_65536_cropped.png"
|
||||
alt="A screenshot of a CUTLASS NVFP4 matrix multiplication benchmark on an RTX 5090"
|
||||
width={236}
|
||||
height={77}
|
||||
/>
|
||||
|
||||
Over a PETA FLOP of nvfp4 compute! ggs. This is already insane, and I'm very happy with it. I didn't get `wgmma` from hopper, nor the `tcgen05` instructions and the `TMEM`, but I did get a petaflop of nvfp4 compute.
|
||||
Nsight Compute tells us exactly what we would expect
|
||||
|
||||
|
||||
<Image
|
||||
src="/images/1_blackwell_dc_vs_gf/geforce_ncu.png"
|
||||
alt="Nsight Compute showing register pressure and memory bottlenecks on a GeForce GPU"
|
||||
width={1974}
|
||||
height={807}
|
||||
/>
|
||||
|
||||
Tensor cores are so fast that the memory is bottlenecking them. All of the shared memory is filling up. Huh, I guess nvidia realised this and created `tcgen05` but we don't get to see any of that.
|
||||
|
||||
|
||||
<Image
|
||||
src="/images/1_blackwell_dc_vs_gf/nvtop_b200.png"
|
||||
alt="nvtop showing B200 GPU memory capacity"
|
||||
width={647}
|
||||
height={106}
|
||||
/>
|
||||
|
||||
|
||||
To see how the GPU folk with datacenters live, I booted up a vast ai instance and ran the same matmul, but with cutlass kernels for `sm_100a`.
|
||||
|
||||
|
||||
<Image
|
||||
src="/images/1_blackwell_dc_vs_gf/b200_65536_cropped.png"
|
||||
alt="A CUTLASS benchmark result from a B200 GPU"
|
||||
width={300}
|
||||
height={108}
|
||||
/>
|
||||
|
||||
We're getting over 2 petaflops, and I'm sure these things can go even faster with better code. Not having `tcgen05` really holds back the geforce cards.
|
||||
This is amazing, I wish I'd be able to get a taste of this locally.
|
||||
|
||||
Why Jensen, why.
|
||||
|
||||
|
||||
92
lib/db.ts
92
lib/db.ts
@@ -2,39 +2,86 @@ import Database from 'better-sqlite3';
|
||||
import type BetterSqlite3 from 'better-sqlite3';
|
||||
import path from 'path';
|
||||
import fs from 'fs';
|
||||
import crypto from 'crypto';
|
||||
|
||||
let db: BetterSqlite3.Database | null = null;
|
||||
let insertStmt: BetterSqlite3.Statement | null = null;
|
||||
const runtimeAnalyticsSalt = crypto.randomBytes(32).toString('hex');
|
||||
|
||||
function getDb() {
|
||||
if (db) return db;
|
||||
function getAnalyticsSalt() {
|
||||
return process.env.ANALYTICS_SALT || runtimeAnalyticsSalt;
|
||||
}
|
||||
|
||||
try {
|
||||
const SERVER_STORAGE = '/server_storage';
|
||||
let dbDir: string;
|
||||
try {
|
||||
fs.accessSync(SERVER_STORAGE, fs.constants.W_OK);
|
||||
dbDir = SERVER_STORAGE;
|
||||
} catch {
|
||||
dbDir = process.cwd();
|
||||
function getDbPath() {
|
||||
if (process.env.VISIT_DB_PATH) {
|
||||
return process.env.VISIT_DB_PATH;
|
||||
}
|
||||
|
||||
const dbPath = path.join(dbDir, 'visitors.db');
|
||||
db = new Database(dbPath);
|
||||
db.pragma('journal_mode = WAL');
|
||||
const serverStorage = '/server_storage';
|
||||
try {
|
||||
fs.mkdirSync(serverStorage, { recursive: true, mode: 0o700 });
|
||||
fs.accessSync(serverStorage, fs.constants.W_OK);
|
||||
return path.join(serverStorage, 'visitors.db');
|
||||
} catch {
|
||||
const localStorage = path.join(process.cwd(), '.data');
|
||||
fs.mkdirSync(localStorage, { recursive: true, mode: 0o700 });
|
||||
return path.join(localStorage, 'visitors.db');
|
||||
}
|
||||
}
|
||||
|
||||
db.exec(`
|
||||
function createVisitorId(clientAddress: string, userAgent: string) {
|
||||
const day = new Date().toISOString().slice(0, 10);
|
||||
return crypto
|
||||
.createHmac('sha256', getAnalyticsSalt())
|
||||
.update(`${day}:${clientAddress}:${userAgent}`)
|
||||
.digest('hex')
|
||||
.slice(0, 32);
|
||||
}
|
||||
|
||||
function ensureSchema(database: BetterSqlite3.Database) {
|
||||
database.exec(`
|
||||
CREATE TABLE IF NOT EXISTS visits (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
ip_address TEXT NOT NULL,
|
||||
visitor_id TEXT NOT NULL,
|
||||
path TEXT NOT NULL,
|
||||
visited_at TEXT NOT NULL DEFAULT (datetime('now'))
|
||||
);
|
||||
`);
|
||||
|
||||
insertStmt = db.prepare(
|
||||
'INSERT INTO visits (ip_address, path) VALUES (?, ?)'
|
||||
);
|
||||
const columns = database
|
||||
.prepare("PRAGMA table_info('visits')")
|
||||
.all() as { name: string; notnull: number }[];
|
||||
const columnNames = new Set(columns.map((column) => column.name));
|
||||
|
||||
if (!columnNames.has('visitor_id')) {
|
||||
database.exec("ALTER TABLE visits ADD COLUMN visitor_id TEXT NOT NULL DEFAULT 'legacy'");
|
||||
columnNames.add('visitor_id');
|
||||
}
|
||||
|
||||
if (!columnNames.has('path')) {
|
||||
throw new Error('visits table is missing required path column');
|
||||
}
|
||||
|
||||
return {
|
||||
hasLegacyIpAddress: columnNames.has('ip_address'),
|
||||
};
|
||||
}
|
||||
|
||||
function getDb() {
|
||||
if (db) return db;
|
||||
|
||||
try {
|
||||
const dbPath = getDbPath();
|
||||
db = new Database(dbPath);
|
||||
db.pragma('busy_timeout = 5000');
|
||||
db.pragma('journal_mode = WAL');
|
||||
db.pragma('synchronous = NORMAL');
|
||||
|
||||
const schema = ensureSchema(db);
|
||||
|
||||
insertStmt = schema.hasLegacyIpAddress
|
||||
? db.prepare("INSERT INTO visits (ip_address, visitor_id, path) VALUES ('redacted', ?, ?)")
|
||||
: db.prepare('INSERT INTO visits (visitor_id, path) VALUES (?, ?)');
|
||||
|
||||
return db;
|
||||
} catch (e) {
|
||||
@@ -45,8 +92,11 @@ function getDb() {
|
||||
}
|
||||
}
|
||||
|
||||
export function logVisit(ip: string, visitPath: string) {
|
||||
export function logVisit(clientAddress: string, userAgent: string, visitPath: string) {
|
||||
const database = getDb();
|
||||
if (!database || !insertStmt) return;
|
||||
insertStmt.run(ip, visitPath);
|
||||
if (!database || !insertStmt) return null;
|
||||
|
||||
const visitorId = createVisitorId(clientAddress, userAgent);
|
||||
insertStmt.run(visitorId, visitPath);
|
||||
return visitorId;
|
||||
}
|
||||
|
||||
10
lib/format.ts
Normal file
10
lib/format.ts
Normal file
@@ -0,0 +1,10 @@
|
||||
const postDateFormatter = new Intl.DateTimeFormat('en-US', {
|
||||
month: 'long',
|
||||
day: 'numeric',
|
||||
year: 'numeric',
|
||||
timeZone: 'UTC',
|
||||
});
|
||||
|
||||
export function formatPostDate(date: string) {
|
||||
return postDateFormatter.format(new Date(date));
|
||||
}
|
||||
36
lib/mdx.ts
36
lib/mdx.ts
@@ -17,11 +17,38 @@ export type Post = {
|
||||
content: string;
|
||||
};
|
||||
|
||||
function readPostMetadata(data: Record<string, unknown>, slug: string): PostMetadata {
|
||||
if (
|
||||
typeof data.title !== 'string' ||
|
||||
typeof data.date !== 'string' ||
|
||||
typeof data.description !== 'string'
|
||||
) {
|
||||
throw new Error(`Invalid frontmatter for post: ${slug}`);
|
||||
}
|
||||
|
||||
if (!Number.isFinite(Date.parse(data.date))) {
|
||||
throw new Error(`Invalid date for post: ${slug}`);
|
||||
}
|
||||
|
||||
return {
|
||||
title: data.title,
|
||||
date: data.date,
|
||||
description: data.description,
|
||||
slug,
|
||||
tags: Array.isArray(data.tags)
|
||||
? data.tags.filter((tag): tag is string => typeof tag === 'string')
|
||||
: undefined,
|
||||
};
|
||||
}
|
||||
|
||||
export function getPostSlugs() {
|
||||
if (!fs.existsSync(postsDirectory)) {
|
||||
return [];
|
||||
}
|
||||
return fs.readdirSync(postsDirectory);
|
||||
return fs
|
||||
.readdirSync(postsDirectory, { withFileTypes: true })
|
||||
.filter((entry) => entry.isFile())
|
||||
.map((entry) => entry.name);
|
||||
}
|
||||
|
||||
export function getPostBySlug(slug: string): Post {
|
||||
@@ -43,10 +70,7 @@ export function getPostBySlug(slug: string): Post {
|
||||
const { data, content } = matter(fileContents);
|
||||
|
||||
return {
|
||||
metadata: {
|
||||
...data,
|
||||
slug: realSlug,
|
||||
} as PostMetadata,
|
||||
metadata: readPostMetadata(data, realSlug),
|
||||
content,
|
||||
};
|
||||
}
|
||||
@@ -57,6 +81,6 @@ export function getAllPosts(): PostMetadata[] {
|
||||
.filter((slug) => slug.endsWith('.mdx'))
|
||||
.map((slug) => getPostBySlug(slug).metadata)
|
||||
// Sort posts by date in descending order
|
||||
.sort((post1, post2) => (post1.date > post2.date ? -1 : 1));
|
||||
.sort((post1, post2) => new Date(post2.date).getTime() - new Date(post1.date).getTime());
|
||||
return posts;
|
||||
}
|
||||
|
||||
80
lib/request.ts
Normal file
80
lib/request.ts
Normal file
@@ -0,0 +1,80 @@
|
||||
const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
|
||||
|
||||
function sanitizeHeaderValue(value: string, maxLength: number) {
|
||||
return value.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, maxLength) || 'unknown';
|
||||
}
|
||||
|
||||
export function getClientAddress(headers: Headers) {
|
||||
const forwarded = headers.get('x-forwarded-for');
|
||||
if (forwarded) {
|
||||
const addresses = forwarded
|
||||
.split(',')
|
||||
.map((value) => value.trim())
|
||||
.filter(Boolean);
|
||||
|
||||
if (addresses.length > 0) {
|
||||
// Use the nearest address. This avoids trusting a spoofed left-most value
|
||||
// when Next or a reverse proxy appends the real peer address.
|
||||
return sanitizeHeaderValue(addresses[addresses.length - 1], 128);
|
||||
}
|
||||
}
|
||||
|
||||
const realIp = headers.get('x-real-ip');
|
||||
if (realIp) return sanitizeHeaderValue(realIp, 128);
|
||||
|
||||
return 'unknown';
|
||||
}
|
||||
|
||||
export function getUserAgent(headers: Headers) {
|
||||
return sanitizeHeaderValue(headers.get('user-agent') || 'unknown', 256);
|
||||
}
|
||||
|
||||
export function normalizeVisitPath(value: unknown) {
|
||||
if (typeof value !== 'string') return null;
|
||||
|
||||
const input = value.trim();
|
||||
if (
|
||||
input.length === 0 ||
|
||||
input.length > 2048 ||
|
||||
!input.startsWith('/') ||
|
||||
input.startsWith('//') ||
|
||||
CONTROL_CHARS.test(input)
|
||||
) {
|
||||
return null;
|
||||
}
|
||||
|
||||
try {
|
||||
const parsed = new URL(input, 'https://site.local');
|
||||
if (parsed.origin !== 'https://site.local') return null;
|
||||
return `${parsed.pathname}${parsed.search}`;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function isSameOriginRequest(request: Request) {
|
||||
const host = request.headers.get('host');
|
||||
if (!host) return false;
|
||||
const requestHost = host.toLowerCase();
|
||||
|
||||
const origin = request.headers.get('origin');
|
||||
if (origin) {
|
||||
try {
|
||||
return new URL(origin).host.toLowerCase() === requestHost;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
const referer = request.headers.get('referer');
|
||||
if (referer) {
|
||||
try {
|
||||
return new URL(referer).host.toLowerCase() === requestHost;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
const fetchSite = request.headers.get('sec-fetch-site');
|
||||
return fetchSite === 'same-origin' || fetchSite === 'none';
|
||||
}
|
||||
@@ -1,42 +0,0 @@
|
||||
import { NextResponse } from 'next/server';
|
||||
import type { NextRequest } from 'next/server';
|
||||
|
||||
const RATE_LIMIT_WINDOW = 60 * 1000; // 1 minute
|
||||
const MAX_REQUESTS = 100; // 100 requests per window
|
||||
const CLEANUP_THRESHOLD = 500;
|
||||
|
||||
const ipMap = new Map<string, { count: number; expires: number }>();
|
||||
|
||||
export function middleware(request: NextRequest) {
|
||||
const forwarded = request.headers.get('x-forwarded-for');
|
||||
const ip = forwarded ? forwarded.split(',')[0].trim() : 'unknown';
|
||||
const now = Date.now();
|
||||
|
||||
console.log(`[${new Date().toISOString()}] Request to ${request.nextUrl.pathname} from ${ip}`);
|
||||
|
||||
const record = ipMap.get(ip);
|
||||
|
||||
if (!record || now > record.expires) {
|
||||
ipMap.set(ip, { count: 1, expires: now + RATE_LIMIT_WINDOW });
|
||||
} else {
|
||||
record.count++;
|
||||
if (record.count > MAX_REQUESTS) {
|
||||
return new NextResponse('Too Many Requests', { status: 429 });
|
||||
}
|
||||
}
|
||||
|
||||
// Cleanup old entries probabilistically (1-in-10 requests)
|
||||
if (ipMap.size > CLEANUP_THRESHOLD && Math.random() < 0.1) {
|
||||
for (const [key, val] of ipMap.entries()) {
|
||||
if (now > val.expires) {
|
||||
ipMap.delete(key);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return NextResponse.next();
|
||||
}
|
||||
|
||||
export const config = {
|
||||
matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)'],
|
||||
};
|
||||
@@ -1,7 +1,24 @@
|
||||
import type { NextConfig } from "next";
|
||||
|
||||
const isDev = process.env.NODE_ENV === "development";
|
||||
const contentSecurityPolicy = [
|
||||
"default-src 'self'",
|
||||
`script-src 'self' 'unsafe-inline'${isDev ? " 'unsafe-eval'" : ""}`,
|
||||
"style-src 'self' 'unsafe-inline'",
|
||||
"img-src 'self' blob: data:",
|
||||
"font-src 'self' data:",
|
||||
"connect-src 'self'",
|
||||
"object-src 'none'",
|
||||
"frame-src 'none'",
|
||||
"frame-ancestors 'none'",
|
||||
"form-action 'self'",
|
||||
"base-uri 'self'",
|
||||
"upgrade-insecure-requests",
|
||||
].join("; ");
|
||||
|
||||
const nextConfig: NextConfig = {
|
||||
output: "standalone",
|
||||
poweredByHeader: false,
|
||||
serverExternalPackages: ['better-sqlite3'],
|
||||
headers: async () => {
|
||||
return [
|
||||
@@ -14,7 +31,7 @@ const nextConfig: NextConfig = {
|
||||
},
|
||||
{
|
||||
key: 'Content-Security-Policy',
|
||||
value: "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; form-action 'self'; base-uri 'self';",
|
||||
value: contentSecurityPolicy,
|
||||
},
|
||||
{
|
||||
key: 'X-Content-Type-Options',
|
||||
@@ -24,6 +41,18 @@ const nextConfig: NextConfig = {
|
||||
key: 'Referrer-Policy',
|
||||
value: 'strict-origin-when-cross-origin',
|
||||
},
|
||||
{
|
||||
key: 'Permissions-Policy',
|
||||
value: 'camera=(), microphone=(), geolocation=(), interest-cohort=()',
|
||||
},
|
||||
{
|
||||
key: 'Cross-Origin-Opener-Policy',
|
||||
value: 'same-origin',
|
||||
},
|
||||
{
|
||||
key: 'X-DNS-Prefetch-Control',
|
||||
value: 'off',
|
||||
},
|
||||
],
|
||||
},
|
||||
];
|
||||
|
||||
662
package-lock.json
generated
662
package-lock.json
generated
File diff suppressed because it is too large
Load Diff
17
package.json
17
package.json
@@ -5,21 +5,17 @@
|
||||
"scripts": {
|
||||
"dev": "next dev",
|
||||
"build": "next build",
|
||||
"start": "next start",
|
||||
"start": "node .next/standalone/server.js",
|
||||
"lint": "eslint"
|
||||
},
|
||||
"dependencies": {
|
||||
"@tailwindcss/typography": "^0.5.19",
|
||||
"better-sqlite3": "^12.6.2",
|
||||
"date-fns": "^4.1.0",
|
||||
"gray-matter": "^4.0.3",
|
||||
"next": "16.1.6",
|
||||
"next-mdx-remote": "^5.0.0",
|
||||
"next": "^16.2.6",
|
||||
"next-mdx-remote": "^6.0.0",
|
||||
"react": "19.2.3",
|
||||
"react-dom": "19.2.3",
|
||||
"rehype-autolink-headings": "^7.1.0",
|
||||
"rehype-slug": "^6.0.0",
|
||||
"remark-gfm": "^4.0.1"
|
||||
"react-dom": "19.2.3"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@tailwindcss/postcss": "^4",
|
||||
@@ -29,8 +25,11 @@
|
||||
"@types/react-dom": "^19",
|
||||
"babel-plugin-react-compiler": "1.0.0",
|
||||
"eslint": "^9",
|
||||
"eslint-config-next": "16.1.6",
|
||||
"eslint-config-next": "^16.2.6",
|
||||
"tailwindcss": "^4",
|
||||
"typescript": "^5"
|
||||
},
|
||||
"overrides": {
|
||||
"postcss": "8.5.10"
|
||||
}
|
||||
}
|
||||
|
||||
55
proxy.ts
Normal file
55
proxy.ts
Normal file
@@ -0,0 +1,55 @@
|
||||
import { NextResponse } from 'next/server';
|
||||
import type { NextRequest } from 'next/server';
|
||||
import { getClientAddress } from '@/lib/request';
|
||||
|
||||
const RATE_LIMIT_WINDOW = 60 * 1000;
|
||||
const MAX_REQUESTS = 100;
|
||||
const CLEANUP_THRESHOLD = 500;
|
||||
|
||||
const requestMap = new Map<string, { count: number; expires: number }>();
|
||||
let nextCleanup = Date.now() + RATE_LIMIT_WINDOW;
|
||||
|
||||
function cleanupExpired(now: number) {
|
||||
if (requestMap.size <= CLEANUP_THRESHOLD && now < nextCleanup) return;
|
||||
|
||||
for (const [key, value] of requestMap.entries()) {
|
||||
if (now > value.expires) {
|
||||
requestMap.delete(key);
|
||||
}
|
||||
}
|
||||
|
||||
nextCleanup = now + RATE_LIMIT_WINDOW;
|
||||
}
|
||||
|
||||
export function proxy(request: NextRequest) {
|
||||
const now = Date.now();
|
||||
cleanupExpired(now);
|
||||
|
||||
const ip = getClientAddress(request.headers);
|
||||
const record = requestMap.get(ip);
|
||||
|
||||
if (!record || now > record.expires) {
|
||||
requestMap.set(ip, { count: 1, expires: now + RATE_LIMIT_WINDOW });
|
||||
} else {
|
||||
record.count += 1;
|
||||
|
||||
if (record.count > MAX_REQUESTS) {
|
||||
return new NextResponse('Too Many Requests', {
|
||||
status: 429,
|
||||
headers: {
|
||||
'Retry-After': String(Math.ceil((record.expires - now) / 1000)),
|
||||
},
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
if (process.env.REQUEST_LOGS === 'true') {
|
||||
console.log(`[${new Date(now).toISOString()}] ${request.nextUrl.pathname} ${ip}`);
|
||||
}
|
||||
|
||||
return NextResponse.next();
|
||||
}
|
||||
|
||||
export const config = {
|
||||
matcher: ['/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp|ico)$).*)'],
|
||||
};
|
||||
13
public/theme-init.js
Normal file
13
public/theme-init.js
Normal file
@@ -0,0 +1,13 @@
|
||||
(function () {
|
||||
try {
|
||||
var storedTheme = window.localStorage.getItem("theme-preference");
|
||||
var theme =
|
||||
storedTheme === "light" || storedTheme === "dark"
|
||||
? storedTheme
|
||||
: window.matchMedia("(prefers-color-scheme: dark)").matches
|
||||
? "dark"
|
||||
: "light";
|
||||
document.documentElement.dataset.theme = theme;
|
||||
} catch {
|
||||
}
|
||||
})();
|
||||
BIN
visitors.db
BIN
visitors.db
Binary file not shown.
BIN
visitors.db-shm
BIN
visitors.db-shm
Binary file not shown.
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user