Performance Optimizations

Relevant source files

The following files were used as context for generating this wiki page:

• src/utils/useExternalLinkWarmup.ts
• src/data/external-link-warmup.ts
• src/config.ts
• src/types/config.ts
• src/styles/transition.css
• package.json
• README.md

The Charlotte project incorporates several front-end performance optimizations aimed at improving both perceived and actual loading times. The primary strategies include pre-warming external links to reduce navigation latency, implementing smooth page transitions for a better user experience, and leveraging modern web development practices like asset optimization.

This document outlines the key performance-related features, their configuration, and their implementation based on the project's source code.

External Link Warmup

To reduce the latency when a user clicks on an external link, the application implements a "warmup" mechanism. This system proactively establishes connections and even fetches content for specified external URLs when a user hovers over the corresponding link. This is controlled via the performance.externalLinkWarmup object in the main configuration.

Sources: src/config.ts:63-69, README.md:81-85

Configuration

The feature is configured in src/config.ts within the siteConfig.performance object.

// File: src/config.ts:63-69

performance: {
    externalLinkWarmup: {
        enable: true, // 外链预热总开关（dns-prefetch / preconnect / fetch）
        enableFetch: true, // 是否启用 hover 时 fetch 预热（隐私敏感可关闭）
        urls: externalLinkWarmupUrls, // 外链预热链接表（完整 URL）from "./data/external-link-warmup"
    },
},

The available options are detailed below:

Property	Type	Default	Description
enable	boolean	true	A master switch to enable or disable the entire external link warmup feature.
enableFetch	boolean	true	If enabled, performs a fetch request on hover in addition to preconnecting. This can be disabled for privacy reasons.
urls	string[]	[]	An array of full URL strings that are eligible for warmup. This list is imported from a separate data file.

Sources: src/types/config.ts:31-37, src/config.ts:63-69

The list of URLs to be pre-warmed is maintained in src/data/external-link-warmup.ts.

// File: src/data/external-link-warmup.ts:5-8

export const externalLinkWarmupUrls: string[] = [
	"https://tabs.chuwu.top/",
	"https://pomo.chuwu.top/",
];

Implementation Logic

The core logic resides in src/utils/useExternalLinkWarmup.ts. The setupExternalLinkWarmup function attaches a pointerover event listener to the document to detect when a user hovers over any element.

The following diagram illustrates the sequence of events when a user hovers over a link.

Event Handler Flow

The logic within the pointerover event handler can be broken down as follows.

Key implementation details:

• Preconnect: The script dynamically injects a <link rel="preconnect" ...> tag into the document's head. This hints to the browser that it should establish a connection to the external origin in advance, which includes DNS lookup, TCP handshake, and TLS negotiation.
• Fetch on Hover: If enableFetch is true, it initiates a fetch request with mode: 'no-cors' and cache: 'force-cache'. This can warm up the browser's HTTP cache for the resource.
• Session Storage: To avoid redundant fetch calls for the same link within a single user session, the script uses sessionStorage to track which URLs have already been warmed up.

Sources: src/utils/useExternalLinkWarmup.ts:30-37, src/utils/useExternalLinkWarmup.ts:73-78, src/utils/useExternalLinkWarmup.ts:40-48

Page Transitions & Animations

The project uses Swup.js, integrated via @swup/astro, to provide smooth, app-like page transitions. This improves perceived performance by avoiding full-page reloads during internal navigation.

Source: package.json:23

Transition States

The file src/styles/transition.css defines the styles for various transition states managed by Swup. When a page transition is initiated, the <html> element gets specific classes that trigger CSS animations.

The lifecycle of a page transition is visualized below.

Onload Animations

In addition to page transitions, the site uses staggered fade-in animations for components on initial page load to create a smooth, visually appealing entry effect.

• A keyframe animation named fade-in-up is defined.
• The .onload-animation class applies this animation.
• Various components like #navbar, #sidebar, and #content-wrapper have this class with different animation-delay values to appear sequentially.

/* File: src/styles/transition.css:10-19 */

@keyframes fade-in-up {
    0% {
        transform: translateY(2rem);
        opacity: 0;
    }
    100% {
        transform: translateY(0);
        opacity: 1;
    }
}

Source: src/styles/transition.css:10-19

Build and Asset Optimization

The project relies on Astro's build system and other conventions for standard web performance optimizations.

• Build Process: The pnpm build script runs astro build, which handles bundling, minification of JS/CSS, and other optimizations.
• Image Formats: The configuration and content files consistently use the .webp image format, which offers better compression than older formats like JPEG and PNG.
• Cache Cleaning: A pnpm clean script is provided to remove build caches (.astro, dist, .vite), which can help resolve issues with stale content during development.

Sources: package.json:8, src/config.ts:20, 93, package.json:15