Nuxt xLog Website Builder
A specialized skill for building and maintaining static websites generated from xLog blogs using Vue 3 + Vite with the vite-ssg plugin.
What This Skill Does
This skill helps you work with a static website generator that syncs content from xLog (a decentralized blogging platform) and generates optimized static websites. It provides guidance on the architecture, build process, configuration, and development practices specific to this Vue 3 + Vite + vite-ssg stack.
Architecture Overview
The project uses:
**Vue 3 + Vite** for modern frontend development with fast tooling**vite-ssg** for static site generation**unplugin-vue-router** for file-based routing from the `pages/` directory**xLog integration** via Crossbell GraphQL API for content fetching**UnoCSS** for atomic CSS styling**TypeScript** for full type safetyStep-by-Step Instructions
1. Initial Setup and Development
When starting development:
```bash
Install dependencies
pnpm install
Prepare git hooks
pnpm prepare
Start development server (opens at http://localhost:3333)
pnpm dev
```
2. Configure xLog Integration
Choose one of two methods:
**Method A: Web Interface**
Navigate to `/config` in the browserSet xLog handle through the UIConfiguration is stored in localStorage**Method B: Environment Variable**
Create/edit `.env` fileSet `XLOG_HANDLE=your-handle`Server-side operations will use this fallback3. Content Management
The data flow follows this pattern:
1. Content is fetched from xLog via Crossbell GraphQL indexer
2. No SDK required - direct API calls in `src/logics/xlog-direct.ts`
3. Responses are cached using `withCache()` with configurable TTL
4. Static pages are generated at build time via vite-ssg
**Key files for xLog integration:**
`src/logics/xlog-direct.ts` - GraphQL helpers with caching`src/logics/site.ts` - Global site state management`src/logics/errors.ts` - Centralized error handling with retry logic`src/logics/cache.ts` - In-memory caching system`src/logics/metadata.ts` - Post enhancement with extra metadata`src/types.ts` - TypeScript interfaces for xLog data structures4. Working with Markdown
The markdown pipeline includes:
**Shiki** syntax highlighting (dual light/dark themes)**Frontmatter** YAML metadata processing**Anchor links** for headings**Table of contents** auto-generation**GitHub Alerts** support**Magic Links** for repository enhancementAll markdown processing configuration is in `vite.config.ts`.
5. Image Handling
For photos and images:
```bash
Compress images using Sharp
pnpm compress
Organize photos with EXIF data
pnpm photos
```
**Key features:**
Automatic OG image generation via `scripts/generate-xlog-og.ts`Click-to-zoom functionality in postsEXIF data extraction for photo management6. Building for Production
Run the complete build pipeline:
```bash
pnpm build
```
This executes:
1. `generate-xlog-og.ts` - Generate Open Graph images
2. `vite-ssg build` - Static site generation
3. `copy-fonts.ts` - Copy font files to public assets
4. `rss.ts` - Generate RSS/Atom/JSON feeds
5. Copy `_redirects` file for deployment
**Note:** `NO_WEBFONT_FETCH=1` is set during build to skip remote Google Fonts downloads in CI/SSG. Unset locally if you want UnoCSS to fetch web fonts on demand.
7. Preview and Validate
Before deployment:
```bash
Preview production build
pnpm preview
```
**Verify:**
Static files in `dist/` directoryRSS feeds exist: `feed.xml`, `feed.atom`, `feed.json`Font files in `public/assets/fonts/``_redirects` file present8. Code Quality
```bash
Run linting with automatic fixes
pnpm lint
```
Uses `@antfu/eslint-config` with custom overrides defined in `eslint.config.js`.
**Git hooks:**
Pre-commit runs `lint-staged` with ESLint fixesConfigured via `simple-git-hooks`Important Development Practices
Type Safety
All xLog API operations use strict TypeScript interfaces in `src/types.ts`Raw API responses are transformed for consistencyEnhanced post types support metadata supplementsError Handling Pattern
Wrap async operations with `withErrorHandling()` from `src/logics/errors.ts`Implement graceful fallbacks for missing dataLog errors with context using centralized loggerCaching Strategy
Use `withCache()` wrapper for API responses with configurable TTLCache keys include relevant parameters for proper invalidationDifferent cache durations per data typePerformance Monitoring
Track operations with `perfTracker.measure()`API timeouts and retry logic configured per operationBuild process optimizes fonts, images, and assetsKey Directories
`src/components/` - Vue components including xLog-specific ones`src/logics/` - Business logic and API clients`pages/` - File-based routing (`.vue` and `.md` files)`scripts/` - Build scripts for RSS, images, fonts`public/` - Static assets including generated OG imagesConfiguration Files
`vite.config.ts` - Main build config with markdown processing`unocss.config.ts` - Atomic CSS framework configuration`tsconfig.json` - TypeScript strict type checking`eslint.config.js` - Linting rules with @antfu/eslint-config`package.json` - Uses pnpm catalog entries for version managementDeployment
The generated `dist/` directory can be deployed to any static hosting service (Vercel, Netlify, GitHub Pages, etc.). All necessary optimizations are included in the build process.
Constraints
Always use TypeScript with strict type checkingPrefer file-based routing over programmatic routesUse UnoCSS shortcuts for consistent stylingCache API responses appropriately to avoid rate limitsHandle xLog API failures gracefully with fallbacksNever skip the font copying step in buildsAlways generate RSS feeds during production buildsExamples
**Fetching xLog site data:**
```typescript
import { getSiteInfo } from '~/logics/xlog-direct'
// With caching and error handling built-in
const siteInfo = await getSiteInfo(handle)
```
**Adding a new page:**
1. Create `pages/my-page.vue` or `pages/my-page.md`
2. File-based routing automatically handles the route
3. Use frontmatter in `.md` files for metadata
**Custom markdown component:**
1. Add component to `src/components/`
2. Reference in markdown files directly
3. Vue components work seamlessly in markdown