Project Guide

This document explains how to run, build, and maintain the project locally.

Technology Stack

• Next.js - application framework and routing
• Tailwind CSS - utility-first styling
• shadcn/ui - reusable UI component patterns built on Radix primitives

Requirements

• Node.js 20+
• pnpm 10+

Getting Started

Run all commands from the project root (this folder):

pnpm install
pnpm dev

The app will be available at http://localhost:3000.

If environment variables are required for a specific setup:

cp .env.example .env

Development Workflow

1. Start the dev server with pnpm dev.
2. Regenerate the skill and app data when changing the animation catalog:
   • pnpm generate:animate-text-skill
   • pnpm validate:animate-text-catalog
3. Add or update routes in src/app.
4. Build reusable UI in src/components/ui.
5. Build page-specific sections in src/components/pages/<slug>
6. Compose pages from those sections inside route files under src/app.
7. Run quality checks before committing:
   • pnpm lint
   • pnpm format
   • pnpm typecheck (tsgo --noEmit)
   • pnpm build

Available Scripts

• pnpm dev - start Next.js in development mode
• pnpm generate:animate-text-skill - rebuild the installable skill and generated site data from catalog/text-animations
• pnpm validate:animate-text-catalog - validate canonical catalog inputs and ensure generated outputs are up to date
• pnpm test:animate-text-skill - smoke test the generated public skill helper scripts
• pnpm build - create a production build
• pnpm start - run the production server
• pnpm lint - run OXC lint checks
• pnpm lint:fix - run OXC lint with auto-fixes
• pnpm format - check formatting with Oxfmt
• pnpm format:fix - format files with Oxfmt
• pnpm typecheck - run TypeScript type checks with tsgo

Project Structure

.
├─ public/                    # static assets served as-is
├─ catalog/                   # canonical source-of-truth data for the text animation library
├─ skills/                    # installable generated skill output
├─ templates/                 # templates used to generate skill documents
├─ src/
│  ├─ app/                    # Next.js App Router (routes, layouts, not-found)
│  ├─ components/
│  │  ├─ ui/                  # shared UI primitives
│  │  └─ pages/
│  │     ├─ home/             # components used only by the Home page
│  │     └─ <slug>/           # components used only by one specific page
│  ├─ content/                # markdown content grouped by feature/page
│  ├─ configs/                # app and website configuration
│  ├─ constants/              # static constants
│  ├─ contexts/               # React providers/contexts
│  ├─ hooks/                  # reusable React hooks
│  ├─ lib/                    # utilities and framework helpers
│  ├─ styles/                 # global and feature styles
│  └─ types/                  # shared TypeScript types
├─ scripts/                   # repo-maintainer scripts including catalog generation/validation
├─ next.config.ts             # Next.js configuration
├─ postcss.config.mjs         # PostCSS configuration
├─ tailwind.plugins.mjs       # Tailwind plugin setup
├─ .oxlintrc.json             # OXC lint configuration
├─ .oxfmtrc.json              # OXC formatter configuration
└─ package.json

Website Config

Website-level settings are defined in src/configs/website-config.ts.

Use this config for branding, metadata defaults, and repository links. Common fields:

• projectName - project name used in UI and metadata
• metaThemeColors.light / metaThemeColors.dark - browser theme colors
• src/app/opengraph-image.tsx - generated OG/social preview image used for Open Graph and Twitter
• githubOrg / githubRepo - repository metadata for links/integrations

Example:

const config = {
  projectName: '<YOUR_PROJECT_NAME>',
  metaThemeColors: {
    light: '#ffffff',
    dark: '#09090b',
  },
};

Content Directory

Content lives in src/content and is organized by folders per section/page type.

Example structure:

src/content/
├─ blog/
├─ docs/
└─ legal/

Rules for this project:

• Use Markdown only (.md files).
• Keep content grouped by folder (for example: docs/, blog/, legal/).
• Use nested folders when you need hierarchy inside a section.

Documentation (/docs) Conventions

For the /docs section, this project follows the same page conventions as FumaDocs. Use the official FumaDocs page conventions as the primary reference when creating or editing docs pages.

Build and Output

• Run pnpm build to generate the production build in .next/.
• Run pnpm start to serve the compiled build.
• postbuild can generate sitemap files and robots.txt via next-sitemap.
• Generated/runtime directories such as .next/, .turbo/, and node_modules/ are not source files.

Animate Text Skill

This repository now contains two downstream outputs generated from catalog/text-animations/:

• skills/animate-text/ - the installable public skill for the skills.sh ecosystem
• src/data/text-animations/generated/ - app-facing generated modules used by the website

Canonical editing rules:

• edit catalog/text-animations/** by hand
• do not hand-edit skills/animate-text/**
• do not hand-edit src/data/text-animations/generated/**

Typical maintainer flow:

pnpm generate:animate-text-skill
pnpm validate:animate-text-catalog
pnpm test:animate-text-skill

Install form for consumers:

npx skills add <owner>/<repo> --skill animate-text